org.gridgain.grid.cache.query

Interface GridCacheQuery<T>

All Known Implementing Classes:

GridCacheQueryAdapter

public interface GridCacheQuery<T>

Main API for configuring and executing cache queries.

Cache queries are created from GridCacheQueries API via any of the available createXXXQuery(...) methods.

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 GridCacheQuerySqlField annotation. Query can be created with GridCacheQueries.createSqlQuery(Class, String) method.

Field Queries

By default select clause is ignored as query result contains full objects. If it is needed to select individual fields, use GridCacheQueries.createSqlFieldsQuery(String) method. This type of query replaces full objects with individual fields. Note that selected fields must be annotated with GridCacheQuerySqlField 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):

 GridCacheQuery<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 GridCacheQuerySqlFunction. Classes containing these methods must be registered in GridH2IndexingSpi#setIndexCustomFunctionClasses(Class[]).

Full Text Queries

GridGain supports full text queries based on Apache Lucene engine. This queries are created by GridCacheQueries.createFullTextQuery(Class, String) method. Note that all fields that are expected to show up in text query results must be annotated with GridCacheQueryTextField 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 (see GridCacheQueries.createScanQuery(GridBiPredicate) method).

Limitations

Data in GridGain 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 collocated mode or at least one side of the join is stored in GridCacheMode.REPLICATED cache. Refer to GridCacheAffinityKey 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.
     @GridCacheQuerySqlField(index = true)
     private long id;

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

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

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

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

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

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

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

 GridCache<Long, Person> cache = G.grid().cache();
 ...
 // Create query which selects salaries based on range for all employees
 // that work for a certain company.
 GridCacheQuery<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 GridGain employees
 // with salaries less than 1000.
 qry.execute("GridGain", 0, 1000);

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

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

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

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

Geo-Spatial Indexes and Queries

GridGain also support Geo-Spatial Indexes. Here is an example of geo-spatial index (supported by GridH2IndexingSpi):

 private class MapPoint implements Serializable {
     // Geospatial index.
     @GridCacheQuerySqlField(index = true)
     private com.vividsolutions.jts.geom.Point location;

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

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

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

 com.vividsolutions.jts.geom.GeometryFactory factory = new com.vividsolutions.jts.geom.GeometryFactory();

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

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	DFLT_PAGE_SIZE Default query page size.

Method Summary

Methods

Modifier and Type	Method and Description
GridCacheQuery<T>	enableDedup(boolean dedup) Sets whether or not to deduplicate query result set.
<R> GridCacheQueryFuture<R>	execute(GridClosure<T,R> rmtTransform, Object... args) Executes the query the same way as execute(Object...) method but transforms result remotely.
<R> GridCacheQueryFuture<R>	execute(GridReducer<T,R> rmtReducer, Object... args) Executes the query the same way as execute(Object...) method but reduces result remotely.
GridCacheQueryFuture<T>	execute(Object... args) Executes the query and returns the query future.
GridCacheQuery<T>	includeBackups(boolean incBackups) Sets whether or not to include backup entries into query result.
GridCacheQuery<T>	keepAll(boolean keepAll) Sets whether or not to keep all query results local.
GridCacheQueryMetrics	metrics() Gets metrics for this query.
GridCacheQuery<T>	pageSize(int pageSize) Sets result page size.
GridCacheQuery<T>	projection(GridProjection prj) Sets optional grid projection to execute this query on.
void	resetMetrics() Resets metrics for this query.
GridCacheQuery<T>	timeout(long timeout) Sets query timeout.

Field Detail

DFLT_PAGE_SIZE

static final int DFLT_PAGE_SIZE

Default query page size.

See Also:

Constant Field Values

Method Detail

pageSize

GridCacheQuery<T> pageSize(int pageSize)

Sets result page size. If not provided, 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.

timeout

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

keepAll

GridCacheQuery<T> keepAll(boolean keepAll)

Sets whether or not to keep all query results local. If not - only the current page is kept locally. Default value is true.

Parameters:

keepAll - Keep results or not.

Returns:

this query instance for chaining.

includeBackups

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

enableDedup

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

projection

GridCacheQuery<T> projection(GridProjection prj)

Sets optional grid projection to execute this query on.

Parameters:

prj - Projection.

Returns:

this query instance for chaining.

execute

GridCacheQueryFuture<T> execute(@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. If keepAll(boolean) flag is set to false, then 'get(..)' methods will only return the last page received, otherwise all pages will be accumulated and returned to user as a collection.

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

<R> GridCacheQueryFuture<R> execute(GridReducer<T,R> rmtReducer,
                                  @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.

execute

<R> GridCacheQueryFuture<R> execute(GridClosure<T,R> rmtTransform,
                                  @Nullable
                                  Object... args)

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

Parameters:

rmtTransform - Remote transformer.

args - Optional arguments.

Returns:

Future for the query result.

metrics

GridCacheQueryMetrics metrics()

Gets metrics for this query.

Returns:

Query metrics.

resetMetrics

void resetMetrics()

Resets metrics for this query.