Package ortus.boxlang.runtime.types

Class Query

java.lang.Object
ortus.boxlang.runtime.types.Query
All Implemented Interfaces:
Serializable, Iterable<IStruct>, Collection<IStruct>, IReferenceable, IType
public class Query extends Object implements IType, IReferenceable, Collection<IStruct>, Serializable
This type represents a representation of a database query result set. It provides language specific methods to access columnar data, both as value lists and within iterative loops
See Also:

  • Field Details

    • $bx

      public transient BoxMeta $bx
      Metadata object

  • Constructor Details

    • Query

      public Query(IStruct meta)
      Create a new query with additional metadata
      Parameters:
      meta - Struct of metadata, most likely JDBC metadata such as sql, cache parameters, etc.

    • Query

      public Query()
      Create a new query with a default (empty) metadata struct

  • Method Details

    • fromResultSet

      public static Query fromResultSet(ResultSet resultSet)
      Create a new query and populate it from the given JDBC ResultSet.
      Parameters:
      resultSet - JDBC result set.
      Returns:
      Query object

    • fromArray

      public static Query fromArray(Array columnNames, Array columnTypes, Object rowData)
      Create a new query with columns and data
      Parameters:
      columnNames - List of column names
      columnTypes - List of column types
      rowData - List of row data
      Returns:
      Query object

    • setMetadata

      public Query setMetadata(IStruct meta)
      Override Query metadata - used for setting custom query meta on cached queries.

    • getColumns

      public Map<Key,QueryColumn> getColumns()
      Get the list of column definitions for this query
      Returns:
      map of columns

    • hasColumns

      public boolean hasColumns()
      Does this query have columns?
      Returns:
      true if query has columns

    • hasColumn

      public boolean hasColumn(Key name)
      Does this query have a specific column?
      Returns:
      true if query has column

    • getData

      public List<Object[]> getData()
      Get the data for this query This method is really only for debugging and the underlying List you get will not be synchronized with the query.
      Returns:
      list of arrays of data

    • addColumn

      public Query addColumn(Key name, QueryColumnType type)
      Add a column to the query, populated with nulls
      Parameters:
      name - column name
      type - column type
      Returns:
      this query

    • addColumn

      public Query addColumn(Key name, QueryColumnType type, Object[] columnData)
      Add a column to the query, populated with provided data. If the data array is shorter than the current number of rows, the remaining rows will be populated with nulls.
      Parameters:
      name - column name
      type - column type
      Returns:
      this query

    • getColumnData

      public Object[] getColumnData(Key name)
      Get all data in a column as a Java Object[] Data is copied, so re-assignments into the array will not be reflected in the query. Mutating a complex object in the array will be reflected in the query.
      Parameters:
      name - column name
      Returns:
      array of column data

    • getColumnDataAsArray

      public Array getColumnDataAsArray(Key name)
      Get all data in a column as an BoxLang Array Data is copied, so re-assignments into the array will not be reflected in the query. Mutating a complex object in the array will be reflected in the query.
      Parameters:
      name - column name
      Returns:
      array of column data

    • getColumnIndex

      public int getColumnIndex(Key name)
      Get the index of a column
      Parameters:
      name - column name
      Returns:
      index of column, or -1 if not found

    • getColumn

      public QueryColumn getColumn(Key name)
      Get the QueryColumn object for a column Throws an exception if the column doesn't exist
      Parameters:
      name - column name
      Returns:
      QueryColumn object

    • getRow

      public Object[] getRow(int index)
      Get data for a row as an array. 0-based index! Array is passed by reference and changes made to it will be reflected in the query.
      Parameters:
      index - row index, starting at 0
      Returns:
      array of row data

    • insertQueryAt

      public Query insertQueryAt(int position, Query target)
      Insert a query into this query at a specific position
      Parameters:
      position - position to insert at
      target - query to insert
      Returns:
      this query
      Throws:
      BoxRuntimeException - if the query columns do not match

    • addRow

      public int addRow(Object[] row)
      Add a row to the query
      Parameters:
      row - row data as array of objects
      Returns:
      this query

    • addRow

      public int addRow(Array row)
      Add a row to the query
      Parameters:
      row - row data as a BoxLang array
      Returns:
      this query

    • swapRow

      public Query swapRow(int sourceRow, int destinationRow)
      Swap a row with another row in the query
      Parameters:
      sourceRow - The row to swap from
      destinationRow - The row to swap to
      Returns:
      this query

    • addEmptyRow

      public int addEmptyRow()
      Add an empty row to the query
      Returns:
      this query

    • addRow

      public int addRow(IStruct row)
      Add a row to the query
      Parameters:
      row - row data as Struct
      Returns:
      this query

    • addRows

      public int addRows(int rows)
      Add empty rows to the query
      Parameters:
      rows - Number of rows to add
      Returns:
      Last row added

    • deleteColumn

      public void deleteColumn(Key name)
      Deletes a column from the query.
      Parameters:
      name - the name of the column to delete

    • deleteRow

      public Query deleteRow(int index)
      Delete a row from the query
      Parameters:
      index - row index, starting at 0
      Returns:
      this query

    • addData

      public int addData(Object rowData)
      Helper method for queryNew() and queryAddRow() to handle the different scenarios for adding data to a query
      Parameters:
      rowData - Data to populate the query. Can be a struct (with keys matching column names), an array of structs, or an array of arrays (in same order as columnList)
      Returns:
      index of last row added

    • getRowAsStruct

      public IStruct getRowAsStruct(int index)
      Get data for a row as a Struct. 0-based index! Data is copied, so re-assignments into the struct will not be reflected in the query. Mutating a complex object in the array will be reflected in the query.
      Parameters:
      index - row index, starting at 0
      Returns:
      array of row data

    • getCell

      public Object getCell(Key columnName, int rowIndex)
      Get data for a single cell. 0-based index!
      Parameters:
      columnName - column name
      rowIndex - row index, starting at 0
      Returns:
      cell data

    • setCell

      public Query setCell(Key columnName, int rowIndex, Object value)
      Set data for a single cell. 0-based index!
      Parameters:
      columnName - column name
      rowIndex - row index, starting at 0
      Returns:
      this query

    • validateRow

      public void validateRow(int index)
      Validate that a row index is within bounds Throw exception if not
      Parameters:
      index - row index, 0-based

    • getRowFromContext

      public int getRowFromContext(IBoxContext context)
      Validate that a row index is within bounds Throw exception if not
      Parameters:
      context - context to get row from
      Returns:
      row index, 0-based

    • getColumnList

      public String getColumnList()
      Get the list of column names as a comma-separated string TODO: Look into caching this and invalidating when columns are added/removed
      Returns:
      column names as string

    • getColumnArray

      public Array getColumnArray()
      Get the list of column names as an array
      Returns:
      column names as array

    • sort

      public void sort(Comparator<IStruct> compareFunc)
      Sort the query
      Parameters:
      compareFunc - function to use for sorting

    • size

      public int size()
      Collection implementation
      Specified by:
      size in interface Collection<IStruct>

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<IStruct>

    • contains

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<IStruct>

    • iterator

      public Iterator<IStruct> iterator()
      Specified by:
      iterator in interface Collection<IStruct>
      Specified by:
      iterator in interface Iterable<IStruct>

    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection<IStruct>

    • toArray

      public <T> T[] toArray(T[] a)
      Specified by:
      toArray in interface Collection<IStruct>

    • toStructArray

      public Array toStructArray()
      Get the data as a Boxlang Array of Structs. Useful for queries with `returntype: "array"`.

    • add

      public boolean add(IStruct row)
      Specified by:
      add in interface Collection<IStruct>

    • remove

      public boolean remove(Object o)
      Specified by:
      remove in interface Collection<IStruct>

    • containsAll

      public boolean containsAll(Collection<?> c)
      Specified by:
      containsAll in interface Collection<IStruct>

    • addAll

      public boolean addAll(Collection<? extends IStruct> rows)
      Specified by:
      addAll in interface Collection<IStruct>

    • removeAll

      public boolean removeAll(Collection<?> c)
      Specified by:
      removeAll in interface Collection<IStruct>

    • retainAll

      public boolean retainAll(Collection<?> c)
      Specified by:
      retainAll in interface Collection<IStruct>

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<IStruct>

    • dereference

      public Object dereference(IBoxContext context, Key name, Boolean safe)
      IReferencable implementation
      Specified by:
      dereference in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The key to dereference
      safe - Whether to throw an exception if the key is not found
      Returns:
      The requested object

    • dereferenceAndInvoke

      public Object dereferenceAndInvoke(IBoxContext context, Key name, Object[] positionalArguments, Boolean safe)
      Description copied from interface: IReferenceable
      Dereference this object by a key and invoke the result as an invokable (UDF, java method) using positional arguments
      Specified by:
      dereferenceAndInvoke in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The key to dereference
      positionalArguments - The positional arguments to pass to the invokable
      safe - Whether to throw an exception if the key is not found
      Returns:
      The requested object

    • dereferenceAndInvoke

      public Object dereferenceAndInvoke(IBoxContext context, Key name, Map<Key,Object> namedArguments, Boolean safe)
      Description copied from interface: IReferenceable
      Dereference this object by a key and invoke the result as an invokable (UDF, java method) using named arguments
      Specified by:
      dereferenceAndInvoke in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The key to dereference
      namedArguments - The named arguments to pass to the invokable
      safe - Whether to throw an exception if the key is not found
      Returns:
      The requested object

    • assign

      public Object assign(IBoxContext context, Key name, Object value)
      Description copied from interface: IReferenceable
      Assign a value to a key in this object
      Specified by:
      assign in interface IReferenceable
      Parameters:
      context - The context we're executing inside of
      name - The name of the scope to get
      value - The value to assign to the scope
      Returns:
      The value that was assigned

    • asString

      public String asString()
      IType implementation
      Specified by:
      asString in interface IType
      Returns:
      The string representation

    • getBoxMeta

      public BoxMeta getBoxMeta()
      Specified by:
      getBoxMeta in interface IType

    • intStream

      public IntStream intStream()

    • getMetaData

      public IStruct getMetaData()
      Retrieve query metadata as a struct. Used to populate QueryMeta. Will populate the following keys if they don't already exist: - recordCount: Number of rows in the query - columns: List of column names - _HASHCODE: Hashcode of the query
      Returns:
      The metadata as a struct

    • duplicate

      public Query duplicate()
      Duplicate the current query.
      Returns:
      A copy of the current query.

    • duplicate

      public Query duplicate(boolean deep)
      Duplicate the current query.
      Parameters:
      deep - If true, nested objects will be duplicated as well.
      Returns:
      A copy of the current query.