Package com.orchestranetworks.query

# Interface Query<T>

public interface Query<T>
An object that represents a compiled and validated SQL query.

A query is executed by calling the method `getResult()`.

Note that this class is not thread-safe.

Since:
  6.0.0
See Also:
  - `QueryBuilder`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `explain()`
  Returns a meaningful string representation of the query plan that is used to compute the result of this query.
  `QueryResult<T>`
  `getResult()`
  Executes the query on the registered dataset(s), and returns a result object, ready to iterate.
  `void`
  `setFetchSize(int rows)`
  Provides a hint to the underlying database with the number of records to fetch at a time from the result of `executing` this query.
  `void`
  `setIncludeOcculting(boolean includeOcculting)`
  Sets whether or not the query must consider records in occulting mode.
  `void`
  `setLocale(Locale aLocale)`
  Sets a locale to the query.
  `void`
  `setParameter(int aPosition, Object aValue)`
  Sets a value to a positional parameter in the query.
  `void`
  `setSession(Session aSession)`
  Sets the user session on the query.

- ## Method Details

  - ### getResult

    QueryResult<T> getResult() throws QueryPermissionException
    Executes the query on the registered dataset(s), and returns a result object, ready to iterate.

    In terms of isolation, when the result object gets iterated, it is guaranteed that all internal persistence and indexing entities used in this process will utilize the same snapshot (the one at the moment the current method was executed).

    Throws:
      `QueryPermissionException` - if a session is provided and at least one forbidden node is used in the request.

  - ### explain

    String explain()
    Returns a meaningful string representation of the query plan that is used to compute the result of this query.

  - ### setSession

    void setSession(Session aSession)
    Sets the user session on the query. This activates the permission checks and sets the session locale.

    Applying the permissions checks will have the following effects:

    - the records will be filtered using the access rules on records and scripted access rules, if any;
    - a `QueryPermissionException` will be thrown on execution if at least one forbidden node is used in the query. Currently, this does not take into account record-dependent access rules set on fields.

See Also:
  - `setLocale(Locale)`

- ### setLocale

  void setLocale(Locale aLocale)
  Sets a locale to the query.
  See Also:
    - `setSession(Session)`

- ### setParameter

  void setParameter(int aPosition, Object aValue)
  Sets a value to a positional parameter in the query.

  A parameter is represented by a question mark ('?') in the query. The first position is 0:

         Query<Tuple> query = dataset.createQuery("SELECT * FROM customer WHERE age = ? AND name = ?");
         query.setParameter(0, 42);
         query.setParameter(1, "John");

  The type of the specified value should match the type of the parameter. See Sql Mapping of data types for more information.

  See Also:
    - `Request.setXPathParameter(java.lang.String, java.lang.Object)`

- ### setFetchSize

  void setFetchSize(int rows)
  Provides a hint to the underlying database with the number of records to fetch at a time from the result of `executing` this query. If the fetch size specified is '0', the underlying implementation determines the fetch size independently.

  See Setting a fetch size for the limitations when using PostgreSQL as the underlying database.

  Parameters:
    `rows` - the number of rows to fetch
  See Also:
    - `Request.setFetchSize(int)`
    - `Statement.setFetchSize(int)`

- ### setIncludeOcculting

  void setIncludeOcculting(boolean includeOcculting)
  Sets whether or not the query must consider records in occulting mode.

  By default, these records are ignored.

  See Also:
    - `Request.setIncludeOcculting(boolean)`