org.apache.ignite.cache.query

## Class SqlFieldsQuery

- java.lang.Object
- - org.apache.ignite.cache.query.Query<List<?>>
  - - org.apache.ignite.cache.query.SqlFieldsQuery

- All Implemented Interfaces:
    Serializable

      public class SqlFieldsQuery
      extends Query<List<?>>

  SQL Fields query. This query can return specific fields of data based on SQL `'select'` clause.

  # Collocated Flag

  Collocation flag is used for optimization purposes. Whenever Ignite executes a distributed query, it sends sub-queries to individual cluster members. If you know in advance that the elements of your query selection are collocated together on the same node, usually based on some affinity-key, Ignite can make significant performance and network optimizations.

  For example, in case of Word-Count example, we know that all identical words are processed on the same cluster member, because we use the `word` itself as affinity key. This allows Ignite to execute the `'limit'` clause on the remote nodes and bring back only the small data set specified within the 'limit' clause, instead of the whole query result as would happen in a non-collocated execution.

  See Also:
    `IgniteCache.query(Query)`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DFLT_LAZY` Do not remove.

    - ### Fields inherited from class org.apache.ignite.cache.query.Query

      `DFLT_PAGE_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SqlFieldsQuery(SqlFieldsQuery qry)` Copy constructs SQL fields query.
    `SqlFieldsQuery(String sql)` Constructs SQL fields query.
    `SqlFieldsQuery(String sql, boolean collocated)` Constructs SQL fields query.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `SqlFieldsQuery` | `copy()`
    `Object[]` | `getArgs()` Gets SQL arguments.
    `@Nullable int[]` | `getPartitions()`
    `String` | `getQueryInitiatorId()`
    `@Nullable String` | `getSchema()` Get schema for the query.
    `String` | `getSql()` Gets SQL clause.
    `int` | `getTimeout()` Gets the query execution timeout in milliseconds.
    `int` | `getUpdateBatchSize()` Gets update internal bach size.
    `boolean` | `isCollocated()` Checks if this query is collocated.
    `boolean` | `isDistributedJoins()` Check if distributed joins are enabled for this query.
    `boolean` | `isEnforceJoinOrder()` Checks if join order of tables if enforced.
    `boolean` | `isLazy()` Deprecated. Use `Query.getPageSize()` instead.
    `boolean` | `isReplicatedOnly()` Deprecated. No longer used as of Apache Ignite 2.8.
    `static void` | `resetThreadedQueryInitiatorId()` Used at the job worker to clear originator for current thread.
    `SqlFieldsQuery` | `setArgs(Object... args)` Sets SQL arguments.
    `SqlFieldsQuery` | `setCollocated(boolean collocated)` Sets flag defining if this query is collocated.
    `SqlFieldsQuery` | `setDistributedJoins(boolean distributedJoins)` Specify if distributed joins are enabled for this query.
    `SqlFieldsQuery` | `setEnforceJoinOrder(boolean enforceJoinOrder)` Sets flag to enforce join order of tables in the query.
    `SqlFieldsQuery` | `setLazy(boolean lazy)` Deprecated. Use `setPageSize(int)` instead.
    `SqlFieldsQuery` | `setLocal(boolean loc)` Sets whether this query should be executed on local node only.
    `SqlFieldsQuery` | `setPageSize(int pageSize)` Sets optional page size, if `0`, then default is used.
    `SqlFieldsQuery` | `setPartitions(int... parts)` Sets partitions for a query.
    `SqlFieldsQuery` | `setQueryInitiatorId(String qryInitiatorId)`
    `SqlFieldsQuery` | `setReplicatedOnly(boolean replicatedOnly)` Deprecated. No longer used as of Apache Ignite 2.8.
    `SqlFieldsQuery` | `setSchema(@Nullable String schema)` Set schema for the query.
    `SqlFieldsQuery` | `setSql(String sql)` Sets SQL clause.
    `static void` | `setThreadedQueryInitiatorId(String originator)` Used at the Job worker to setup originator by default for current thread.
    `SqlFieldsQuery` | `setTimeout(int timeout, TimeUnit timeUnit)` Sets the query execution timeout.
    `SqlFieldsQuery` | `setUpdateBatchSize(int updateBatchSize)` Sets update internal bach size.
    `static String` | `threadedQueryInitiatorId()`
    `String` | `toString()`

    - ### Methods inherited from class org.apache.ignite.cache.query.Query

      `getPageSize, isLocal, prepare`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DFLT_LAZY

          public static boolean DFLT_LAZY

      Do not remove. For tests only.

  - ### Constructor Detail

    - #### SqlFieldsQuery

          public SqlFieldsQuery(SqlFieldsQuery qry)

      Copy constructs SQL fields query.
      Parameters:
        `qry` - SQL query.

    - #### SqlFieldsQuery

          public SqlFieldsQuery(String sql)

      Constructs SQL fields query.
      Parameters:
        `sql` - SQL query.

    - #### SqlFieldsQuery

          public SqlFieldsQuery(String sql,
                                boolean collocated)

      Constructs SQL fields query.
      Parameters:
        `sql` - SQL query.
        `collocated` - Collocated flag.

  - ### Method Detail

    - #### getSql

          public String getSql()

      Gets SQL clause.
      Returns:
        SQL clause.

    - #### setSql

          public SqlFieldsQuery setSql(String sql)

      Sets SQL clause.
      Parameters:
        `sql` - SQL clause.
      Returns:
        `this` For chaining.

    - #### getArgs

          public Object[] getArgs()

      Gets SQL arguments.
      Returns:
        SQL arguments.

    - #### setArgs

          public SqlFieldsQuery setArgs(Object... args)

      Sets SQL arguments.
      Parameters:
        `args` - SQL arguments.
      Returns:
        `this` For chaining.

    - #### getTimeout

          public int getTimeout()

      Gets the query execution timeout in milliseconds.
      Returns:
        Timeout value.

    - #### setTimeout

          public SqlFieldsQuery setTimeout(int timeout,
                                           TimeUnit timeUnit)

      Sets the query execution timeout. Query will be automatically cancelled if the execution timeout is exceeded.
      Parameters:
        `timeout` - Timeout value. Zero value disables timeout.
        `timeUnit` - Time unit.
      Returns:
        `this` For chaining.

    - #### isCollocated

          public boolean isCollocated()

      Checks if this query is collocated.
      Returns:
        `true` If the query is collocated.

    - #### setCollocated

          public SqlFieldsQuery setCollocated(boolean collocated)

      Sets flag defining if this query is collocated. Collocation flag is used for optimization purposes of queries with GROUP BY statements. Whenever Ignite executes a distributed query, it sends sub-queries to individual cluster members. If you know in advance that the elements of your query selection are collocated together on the same node and you group by collocated key (primary or affinity key), then Ignite can make significant performance and network optimizations by grouping data on remote nodes.
      Parameters:
        `collocated` - Flag value.
      Returns:
        `this` For chaining.

    - #### isEnforceJoinOrder

          public boolean isEnforceJoinOrder()

      Checks if join order of tables if enforced.
      Returns:
        Flag value.

    - #### setEnforceJoinOrder

          public SqlFieldsQuery setEnforceJoinOrder(boolean enforceJoinOrder)

      Sets flag to enforce join order of tables in the query. If set to `true` query optimizer will not reorder tables in join. By default is `false`.

      It is not recommended to enable this property until you are sure that your indexes and the query itself are correct and tuned as much as possible but query optimizer still produces wrong join order.

      Parameters:
        `enforceJoinOrder` - Flag value.
      Returns:
        `this` For chaining.

    - #### setDistributedJoins

          public SqlFieldsQuery setDistributedJoins(boolean distributedJoins)

      Specify if distributed joins are enabled for this query.
      Parameters:
        `distributedJoins` - Distributed joins enabled.
      Returns:
        `this` For chaining.

    - #### isDistributedJoins

          public boolean isDistributedJoins()

      Check if distributed joins are enabled for this query.
      Returns:
        `true` If distributed joins enabled.

    - #### setPageSize

          public SqlFieldsQuery setPageSize(int pageSize)

      Sets optional page size, if `0`, then default is used.
      Overrides:
        `setPageSize` in class `Query<List<?>>`
      Parameters:
        `pageSize` - Optional page size.
      Returns:
        `this` for chaining.

    - #### setLocal

          public SqlFieldsQuery setLocal(boolean loc)

      Sets whether this query should be executed on local node only.
      Overrides:
        `setLocal` in class `Query<List<?>>`
      Parameters:
        `loc` - Local flag.
      Returns:
        `this` for chaining.

    - #### setReplicatedOnly

          @Deprecated
          public SqlFieldsQuery setReplicatedOnly(boolean replicatedOnly)

      Deprecated. No longer used as of Apache Ignite 2.8.
      Specify if the query contains only replicated tables. This is a hint for potentially more effective execution.
      Parameters:
        `replicatedOnly` - The query contains only replicated tables.
      Returns:
        `this` For chaining.

    - #### isReplicatedOnly

          @Deprecated
          public boolean isReplicatedOnly()

      Deprecated. No longer used as of Apache Ignite 2.8.
      Check is the query contains only replicated tables.
      Returns:
        `true` If the query contains only replicated tables.

    - #### setLazy

          public SqlFieldsQuery setLazy(boolean lazy)

      Deprecated. Use `setPageSize(int)` instead.
      Sets lazy query execution flag.

      If `lazy=false` Ignite will attempt to fetch the whole query result set to memory and send it to the client. For small and medium result sets this provides optimal performance and minimize duration of internal database locks, thus increasing concurrency.

      If result set is too big to fit in available memory this could lead to excessive GC pauses and even `OutOfMemoryError`. Use this flag as a hint for Ignite to fetch result set lazily, thus minimizing memory consumption at the cost of moderate performance hit.

      Defaults to `true`, meaning that the only first page of result set is fetched to memory.

      Parameters:
        `lazy` - Lazy query execution flag.
      Returns:
        `this` For chaining.

    - #### isLazy

          public boolean isLazy()

      Deprecated. Use `Query.getPageSize()` instead.
      Gets lazy query execution flag.

      See `setLazy(boolean)` for more information.

      Returns:
        Lazy flag.

    - #### getPartitions

          @Nullable
          public @Nullable int[] getPartitions()

      Returns:
        Partitions for query, in ascending order.

    - #### setPartitions

          public SqlFieldsQuery setPartitions(@Nullable
                                              int... parts)

      Sets partitions for a query. The query will be executed only on nodes which are primary for specified partitions.

      Note what passed array'll be sorted in place for performance reasons, if it wasn't sorted yet.

      Parameters:
        `parts` - Partitions.
      Returns:
        `this` for chaining.

    - #### getSchema

          @Nullable
          public @Nullable String getSchema()

      Get schema for the query. If not set, current cache name is used, which means you can omit schema name for tables within the current cache.
      Returns:
        Schema. Null if schema is not set.

    - #### setSchema

          public SqlFieldsQuery setSchema(@Nullable
                                          @Nullable String schema)

      Set schema for the query. If not set, current cache name is used, which means you can omit schema name for tables within the current cache.
      Parameters:
        `schema` - Schema. Null to unset schema.
      Returns:
        `this` for chaining.

    - #### getUpdateBatchSize

          public int getUpdateBatchSize()

      Gets update internal bach size. Default is 1 to prevent deadlock on update where keys sequence are different in several concurrent updates.
      Returns:
        Update internal batch size

    - #### setUpdateBatchSize

          public SqlFieldsQuery setUpdateBatchSize(int updateBatchSize)

      Sets update internal bach size. Default is 1 to prevent deadlock on update where keys sequence are different in several concurrent updates.
      Parameters:
        `updateBatchSize` - Update internal batch size.
      Returns:
        `this` for chaining.

    - #### getQueryInitiatorId

          public String getQueryInitiatorId()

      Returns:
        Query's initiator identifier string (client host+port, user name, job name or any user's information about query initiator).

    - #### setQueryInitiatorId

          public SqlFieldsQuery setQueryInitiatorId(String qryInitiatorId)

      Parameters:
        `qryInitiatorId` - Query's initiator identifier string (client host+port, user name, job name or any user's information about query initiator).
      Returns:
        `this` for chaining.

    - #### copy

          public SqlFieldsQuery copy()

      Returns:
        Copy of this query.

    - #### setThreadedQueryInitiatorId

          public static void setThreadedQueryInitiatorId(String originator)

      Used at the Job worker to setup originator by default for current thread.
      Parameters:
        `originator` - Query's originator string.

    - #### resetThreadedQueryInitiatorId

          public static void resetThreadedQueryInitiatorId()

      Used at the job worker to clear originator for current thread.

    - #### threadedQueryInitiatorId

          public static String threadedQueryInitiatorId()

      Returns:
        originator set up by the job worker.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Query<List<?>>`

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.15.0
Release Date | : April 25 2023