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

Class 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 records = cache.queries().createSqlQuery(MapPoint.class, "select * from MapPoint where location && ?")
     .queryArguments(square)
     .execute()
     .get();

    • 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.

      • 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.

      • partition

        @Nullable
public @Nullable Integer partition()
        Returns:
        Partition.

      • idxQryDesc

        @Nullable
public @Nullable IndexQueryDesc idxQryDesc()
        Returns:
        Index query description.

      • 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.