Package org.apache.ignite.internal.processors.cache.query

## Class CacheQuery<T>

- java.lang.Object
- - org.apache.ignite.internal.processors.cache.query.CacheQuery<T>

    public class CacheQuery<T>
    extends Object

Main API for configuring and executing cache queries.

# SQL Queries

`SQL` query allows to execute distributed cache queries using standard SQL syntax. All values participating in where clauses or joins must be annotated with `QuerySqlField` annotation.

## Field Queries

By default `select` clause is ignored as query result contains full objects. This type of query replaces full objects with individual fields. Note that selected fields must be annotated with `QuerySqlField` annotation.

## Cross-Cache Queries

You are allowed to query data from several caches. Cache that this query was created on is treated as default schema in this case. Other caches can be referenced by their names.

Note that cache name is case sensitive and has to always be specified in double quotes. Here is an example of cross cache query (note that 'replicated' and 'partitioned' are cache names for replicated and partitioned caches accordingly):

     CacheQuery<Map.Entry<Integer, FactPurchase>> storePurchases = cache.queries().createSqlQuery(
         Purchase.class,
         "from \"replicated\".Store, \"partitioned\".Purchase where Store.id=Purchase.storeId and Store.id=?");

## Custom functions in SQL queries.

It is possible to write custom Java methods and call then form SQL queries. These methods must be public static and annotated with `QuerySqlFunction`. Classes containing these methods must be registered in `CacheConfiguration.setSqlFunctionClasses(Class[])`.

# Full Text Queries

Ignite supports full text queries based on Apache Lucene engine. Note that all fields that are expected to show up in text query results must be annotated with `QueryTextField` annotation.

# Scan Queries

Sometimes when it is known in advance that SQL query will cause a full data scan, or whenever data set is relatively small, the full scan query may be used. This query will iterate over all cache entries, skipping over entries that don't pass the optionally provided key-value filter.

## Limitations

Data in Ignite cache is usually distributed across several nodes, so some queries may not work as expected. Keep in mind following limitations (not applied if data is queried from one node only):

- `Group by` and `sort by` statements are applied separately on each node, so result set will likely be incorrectly grouped or sorted after results from multiple remote nodes are grouped together.
- Aggregation functions like `sum`, `max`, `avg`, etc. are also applied on each node. Therefore you will get several results containing aggregated values, one for each node.
- Joins will work correctly only if joined objects are stored in colocated mode or at least one side of the join is stored in `CacheMode.REPLICATED` cache. Refer to `AffinityKey` javadoc for more information about colocation.

# Query usage

As an example, suppose we have data model consisting of `'Employee'` and `'Organization'` classes defined as follows:

     public class Organization {
         // Indexed field.
         @QuerySqlField(index = true)
         private long id;

         // Indexed field.
         @QuerySqlField(index = true)
         private String name;
         ...
     }

     public class Person {
         // Indexed field.
         @QuerySqlField(index = true)
         private long id;

         // Indexed field (Organization ID, used as a foreign key).
         @QuerySqlField(index = true)
         private long orgId;

         // Without SQL field annotation, this field cannot be used in queries.
         private String name;

         // Not indexed field.
         @QuerySqlField
         private double salary;

         // Index for text search.
         @QueryTextField
         private String resume;
         ...
     }

Then you can create and execute queries that check various salary ranges like so:

     Cache<Long, Person> cache = Ignition.ignite().cache();
     ...
     // Create query which selects salaries based on range for all employees
     // that work for a certain company.
     CacheQuery<Map.Entry<Long, Person>> qry = cache.queries().createSqlQuery(Person.class,
         "from Person, Organization where Person.orgId = Organization.id " +
             "and Organization.name = ? and Person.salary > ? and Person.salary <= ?");

     // Query all nodes to find all cached Ignite employees
     // with salaries less than 1000.
     qry.execute("Ignition", 0, 1000);

     // Query only remote nodes to find all remotely cached Ignite employees
     // with salaries greater than 1000 and less than 2000.
     qry.projection(grid.remoteProjection()).execute("Ignition", 1000, 2000);

Here is a possible query that will use Lucene text search to scan all resumes to check if employees have `Master` degree:

     CacheQuery<Map.Entry<Long, Person>> mastersQry =
         cache.queries().createFullTextQuery(Person.class, "Master");

     // Query all cache nodes.
     mastersQry.execute();

# Geo-Spatial Indexes and Queries

Ignite also support Geo-Spatial Indexes. Here is an example of geo-spatial index:

     private class MapPoint implements Serializable {
         // Geospatial index.
         @QuerySqlField(index = true)
         private org.locationtech.jts.geom.Point location;

         // Not indexed field.
         @QuerySqlField
         private String name;

         public MapPoint(org.locationtech.jts.geom.Point location, String name) {
             this.location = location;
             this.name = name;
         }
     }

Example of spatial query on the geo-indexed field from above:

     org.locationtech.jts.geom.GeometryFactory factory = new org.locationtech.jts.geom.GeometryFactory();

     org.locationtech.jts.geom.Polygon square = factory.createPolygon(new Coordinate[] {
         new org.locationtech.jts.geom.Coordinate(0, 0),
         new org.locationtech.jts.geom.Coordinate(0, 100),
         new org.locationtech.jts.geom.Coordinate(100, 100),
         new org.locationtech.jts.geom.Coordinate(100, 0),
         new org.locationtech.jts.geom.Coordinate(0, 0)
     });

     Map.Entry<String, UserData> records = cache.queries().createSqlQuery(MapPoint.class, "select * from MapPoint where location && ?")
         .queryArguments(square)
         .execute()
         .get();

### Constructor Summary

Constructors
`CacheQuery​(GridCacheContext<?,​?> cctx, GridCacheQueryType type, @Nullable String clsName, @Nullable String clause, @Nullable IgniteBiPredicate<Object,​Object> filter, @Nullable Integer part, boolean incMeta, boolean keepBinary, Boolean dataPageScanEnabled, IndexQueryDesc idxQryDesc, @Nullable Collection<KeyCacheObject> skipKeys)` Cache query adapter for SET, SPI, TEXT queries.
`CacheQuery​(GridCacheContext<?,​?> cctx, GridCacheQueryType type, @Nullable IgniteBiPredicate<Object,​Object> filter, @Nullable IgniteClosure<Map.Entry,​Object> transform, @Nullable Integer part, boolean keepBinary, boolean forceLocal, Boolean dataPageScanEnabled, @Nullable Set<KeyCacheObject> skipKeys)` Cache query adapter for SCAN query.

`CacheQuery​(GridCacheContext<?,​?> cctx, GridCacheQueryType type, IgniteLogger log, int pageSize, long timeout, boolean incBackups, boolean dedup, ClusterGroup prj, IgniteBiPredicate<Object,​Object> filter, @Nullable Integer part, @Nullable String clsName, String clause, IndexQueryDesc idxQryDesc, int limit, boolean incMeta, boolean keepBinary, int taskHash, Boolean dataPageScanEnabled, @Nullable Collection<KeyCacheObject> skipKeys)`

Cache query adapter for local query processing.

`CacheQuery​(GridCacheContext<?,​?> cctx, GridCacheQueryType type, IndexQueryDesc idxQryDesc, @Nullable Integer part, @Nullable String clsName, @Nullable IgniteBiPredicate<Object,​Object> filter)` Cache query adapter for INDEX query.

### Method Summary

All Methods Instance Methods Concrete Methods
`@Nullable String` `clause()`
`boolean` `enableDedup()`
`CacheQuery<T>` `enableDedup​(boolean dedup)` Sets whether or not to deduplicate query result set.
`CacheQueryFuture<T>` `execute​(@Nullable Object... args)` Executes the query and returns the query future.
`<R> CacheQueryFuture<R>` `execute​(IgniteReducer<T,​R> rmtReducer, @Nullable Object... args)` Executes the query the same way as `execute(Object...)` method but reduces result remotely.
`GridCloseableIterator` `executeScanQuery​(List<Object> newAndUpdatedEntries)`
`boolean` `forceLocal()`
`@Nullable IndexQueryDesc` `idxQryDesc()`
`boolean` `includeBackups()`
`CacheQuery<T>` `includeBackups​(boolean incBackups)` Sets whether or not to include backup entries into query result.
`boolean` `includeMetadata()`
`Boolean` `isDataPageScanEnabled()`
`boolean` `keepBinary()`
`void` `keepBinary​(boolean keepBinary)` Forces query to keep binary object representation even if query was created on plain projection.
`int` `limit()`
`CacheQuery<T>` `limit​(int limit)` Sets limit of returned records.
`int` `pageSize()`
`CacheQuery<T>` `pageSize​(int pageSize)` Sets result page size.
`@Nullable Integer` `partition()`
`ClusterGroup` `projection()`
`CacheQuery<T>` `projection​(ClusterGroup prj)` Sets optional grid projection to execute this query on.
`@Nullable String` `queryClassName()`
`<K,​V> @Nullable IgniteBiPredicate<K,​V>` `scanFilter()`
`Collection<KeyCacheObject>` `skipKeys()`
`int` `taskHash()`
`long` `timeout()`
`CacheQuery<T>` `timeout​(long timeout)` Sets query timeout.
`String` `toString()`
`<K,​V> @Nullable IgniteClosure<Map.Entry<K,​V>,​Object>` `transform()`
`GridCacheQueryType` `type()`
`void` `validate()`

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

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

### Constructor Detail

#### CacheQuery

    public CacheQuery​(GridCacheContext<?,​?> cctx,
                      GridCacheQueryType type,
                      @Nullable
                      @Nullable IgniteBiPredicate<Object,​Object> filter,
                      @Nullable
                      @Nullable IgniteClosure<Map.Entry,​Object> transform,
                      @Nullable
                      @Nullable Integer part,
                      boolean keepBinary,
                      boolean forceLocal,
                      Boolean dataPageScanEnabled,
                      @Nullable
                      @Nullable Set<KeyCacheObject> skipKeys)

Cache query adapter for SCAN query.

Parameters:
  `cctx` - Context.
  `type` - Query type.
  `filter` - Scan filter.
  `part` - Partition.
  `keepBinary` - Keep binary flag.
  `forceLocal` - Flag to force local query.
  `dataPageScanEnabled` - Flag to enable data page scan.
  `skipKeys` - Set of keys that must be skiped during iteration.

#### CacheQuery

    public CacheQuery​(GridCacheContext<?,​?> cctx,
                      GridCacheQueryType type,
                      @Nullable
                      @Nullable String clsName,
                      @Nullable
                      @Nullable String clause,
                      @Nullable
                      @Nullable IgniteBiPredicate<Object,​Object> filter,
                      @Nullable
                      @Nullable Integer part,
                      boolean incMeta,
                      boolean keepBinary,
                      Boolean dataPageScanEnabled,
                      IndexQueryDesc idxQryDesc,
                      @Nullable
                      @Nullable Collection<KeyCacheObject> skipKeys)

Cache query adapter for SET, SPI, TEXT queries.

Parameters:
  `cctx` - Context.
  `type` - Query type.
  `clsName` - Class name.
  `clause` - Clause.
  `filter` - Scan filter.
  `part` - Partition.
  `incMeta` - Include metadata flag.
  `keepBinary` - Keep binary flag.
  `dataPageScanEnabled` - Flag to enable data page scan.
  `skipKeys` - Set of keys that must be skiped during iteration.

#### CacheQuery

    public CacheQuery​(GridCacheContext<?,​?> cctx,
                      GridCacheQueryType type,
                      IgniteLogger log,
                      int pageSize,
                      long timeout,
                      boolean incBackups,
                      boolean dedup,
                      ClusterGroup prj,
                      IgniteBiPredicate<Object,​Object> filter,
                      @Nullable
                      @Nullable Integer part,
                      @Nullable
                      @Nullable String clsName,
                      String clause,
                      IndexQueryDesc idxQryDesc,
                      int limit,
                      boolean incMeta,
                      boolean keepBinary,
                      int taskHash,
                      Boolean dataPageScanEnabled,
                      @Nullable
                      @Nullable Collection<KeyCacheObject> skipKeys)

Cache query adapter for local query processing.

Parameters:
  `cctx` - Context.
  `type` - Query type.
  `log` - Logger.
  `pageSize` - Page size.
  `timeout` - Timeout.
  `incBackups` - Include backups flag.
  `dedup` - Enable dedup flag.
  `prj` - Grid projection.
  `filter` - Key-value filter.
  `part` - Partition.
  `clsName` - Class name.
  `clause` - Clause.
  `limit` - Response limit. Set to 0 for no limits.
  `incMeta` - Include metadata flag.
  `keepBinary` - Keep binary flag.
  `taskHash` - Task hash.
  `dataPageScanEnabled` - Flag to enable data page scan.
  `skipKeys` - Set of keys that must be skiped during iteration.

#### CacheQuery

    public CacheQuery​(GridCacheContext<?,​?> cctx,
                      GridCacheQueryType type,
                      IndexQueryDesc idxQryDesc,
                      @Nullable
                      @Nullable Integer part,
                      @Nullable
                      @Nullable String clsName,
                      @Nullable
                      @Nullable IgniteBiPredicate<Object,​Object> filter)

Cache query adapter for INDEX query.

Parameters:
  `cctx` - Context.
  `type` - Query type.
  `idxQryDesc` - Index query descriptor.
  `part` - Partition number to iterate over.
  `clsName` - Class name.
  `filter` - Index query remote filter.

### Method Detail

#### isDataPageScanEnabled

    public Boolean isDataPageScanEnabled()

Returns:
  Flag to enable data page scan.

#### skipKeys

    public Collection<KeyCacheObject> skipKeys()

Returns:
  Set of keys that must be skiped during iteration.

#### type

    public GridCacheQueryType type()

Returns:
  Type.

#### queryClassName

    @Nullable
    public @Nullable String queryClassName()

Returns:
  Class name.

#### clause

    @Nullable
    public @Nullable String clause()

Returns:
  Clause.

#### includeMetadata

    public boolean includeMetadata()

Returns:
  Include metadata flag.

#### keepBinary

    public boolean keepBinary()

Returns:
  `True` if binary should not be deserialized.

#### keepBinary

    public void keepBinary​(boolean keepBinary)

Forces query to keep binary object representation even if query was created on plain projection.

Parameters:
  `keepBinary` - Keep binary flag.

#### forceLocal

    public boolean forceLocal()

Returns:
  `True` if the query is forced local.

#### taskHash

    public int taskHash()

Returns:
  Task hash.

#### pageSize

    public CacheQuery<T> pageSize​(int pageSize)

Sets result page size. If not provided, `Query.DFLT_PAGE_SIZE` will be used. Results are returned from queried nodes one page at a tme.

Parameters:
  `pageSize` - Page size.
Returns:
  `this` query instance for chaining.

#### pageSize

    public int pageSize()

Returns:
  Page size.

#### timeout

    public CacheQuery<T> timeout​(long timeout)

Sets query timeout. `0` means there is no timeout (this is a default value).

Parameters:
  `timeout` - Query timeout.
Returns:
  `this` query instance for chaining.

#### limit

    public int limit()

Returns:
  Response limit. Returns 0 for no limits.

#### limit

    public CacheQuery<T> limit​(int limit)

Sets limit of returned records. `0` means there is no limit

Parameters:
  `limit` - Records limit.
Returns:
  `this` query instance for chaining.

#### timeout

    public long timeout()

Returns:
  Timeout.

#### includeBackups

    public CacheQuery<T> includeBackups​(boolean incBackups)

Sets whether or not to include backup entries into query result. This flag is `false` by default.

Parameters:
  `incBackups` - Query `includeBackups` flag.
Returns:
  `this` query instance for chaining.

#### includeBackups

    public boolean includeBackups()

Returns:
  Include backups.

#### enableDedup

    public CacheQuery<T> enableDedup​(boolean dedup)

Sets whether or not to deduplicate query result set. If this flag is `true` then query result will not contain some key more than once even if several nodes returned entries with the same keys. Default value is `false`.

Parameters:
  `dedup` - Query `enableDedup` flag.
Returns:
  `this` query instance for chaining.

#### enableDedup

    public boolean enableDedup()

Returns:
  Enable dedup flag.

#### projection

    public CacheQuery<T> projection​(ClusterGroup prj)

Sets optional grid projection to execute this query on.

Parameters:
  `prj` - Projection.
Returns:
  `this` query instance for chaining.

#### projection

    public ClusterGroup projection()

Returns:
  Grid projection.

#### scanFilter

    @Nullable
    public <K,​V> @Nullable IgniteBiPredicate<K,​V> scanFilter()

Returns:
  Key-value filter.

#### transform

    @Nullable
    public <K,​V> @Nullable IgniteClosure<Map.Entry<K,​V>,​Object> transform()

Returns:
  Transformer.

#### partition

    @Nullable
    public @Nullable Integer partition()

Returns:
  Partition.

#### idxQryDesc

    @Nullable
    public @Nullable IndexQueryDesc idxQryDesc()

Returns:
  Index query description.

#### validate

    public void validate()
                  throws IgniteCheckedException

Throws:
  `IgniteCheckedException` - If query is invalid.

#### execute

    public CacheQueryFuture<T> execute​(@Nullable
                                       @Nullable Object... args)

Executes the query and returns the query future. Caller may decide to iterate over the returned future directly in which case the iterator may block until the next value will become available, or wait for the whole query to finish by calling any of the `'get(..)'` methods on the returned future.

Note that if the passed in grid projection is a local node, then query will be executed locally without distribution to other nodes.

Also note that query state cannot be changed (clause, timeout etc.), except arguments, if this method was called at least once.

Parameters:
  `args` - Optional arguments.
Returns:
  Future for the query result.

#### execute

    public <R> CacheQueryFuture<R> execute​(IgniteReducer<T,​R> rmtReducer,
                                           @Nullable
                                           @Nullable Object... args)

Executes the query the same way as `execute(Object...)` method but reduces result remotely.

Parameters:
  `rmtReducer` - Remote reducer.
  `args` - Optional arguments.
Returns:
  Future for the query result.

#### executeScanQuery

    public GridCloseableIterator executeScanQuery​(List<Object> newAndUpdatedEntries)
                                           throws IgniteCheckedException

Parameters:
  `newAndUpdatedEntries` - Collection of entries created or updated in transaction.
Returns:
  Scan query iterator.
Throws:
  `IgniteCheckedException`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`