Motivation for Using Custom Query

GigaSpaces provides various methods for performing queries on the space. The most common are template-based matching, and the SQLQuery. These allow the executing of queries expressively, based on well defined query semantics. Parallel queries are also supported implicitly, when using any of these query methods with a partitioned space.

There are cases where the well defined query semantics don't meet specific requirements, or where the requirements are met, but performance isn't adequate. The purpose of the custom query pattern is to extend the existing query capabilities by enabling users to write code and execute it as part of the query path. Similar to a database-stored procedure, a custom query needs to be running close to the data. The custom query should be triggered during the normal query execution path, and should therefore be able to effect the result while the query is taking place.

Currently, the component in GigaSpaces that enables such intervention is the space filter. However, the filters are relatively static – they are configured as part of the space configuration and can not be changed during runtime. To overcome this limitation, you need to build a generic filter that gets the custom query commands as parts of its arguments. It uses these arguments to execute multiple custom queries without changing its behavior or implementation – instead of having a different filter per query, one filter is used for all queries, which acts as the hosting environment for query commands that are received as arguments.

In the diagram below, the flow of events is as follows:

• The application creates a QueryTask template which acts as a command. It passes this template as an argument to a readMultiple/takeMultiple operation on a space proxy.
• If the space proxy happens to be clustered, it issues parallel requests to all the spaces that are currently running with this template.
• A QueryTaskFilter is configured in each space, and parses each template to see if it matches a command interface. If it does, it calls the execute method on that template.
• The execute method gets the space as an argument and based on the template implementation; it can execute queries on the space, parse the results, and finally, store them as a single result object in the space.
• The result object is assigned with an ID which is also set back into the template by the filter.
• At this stage, the filter completes its tasks, and the space performs matching using the given QueryTask template – the template is matched to the result of the custom query, which is returned to the client.

Executing Custom Query

The sequence diagram below shows the flow of events once the template gets into the filter's execution:

Code Example

The example below populates objects into the space and then executes the following query:

"select sum(accountNumber) from Entity where flags <= 5 "

The example consists of two parts, a generic framework and a specific custom query example that implements the query statement above.

The generic framework classes are not specific to this example. They include the filter implementation, and an AbstractQueryTask, which is used to provide common framework for the creation of QueryTasks.

It also includes space schema (QueryFilter-space-schema) configuration, that is set to run the filter as part of the space startup, and is already configured to intercept readMultiple and takeMultiple operations.

The space schema using this filter should have the following added:

<filter-names>DefaultSecurityFilter, Statistics, QueryFilter</filter-names>
	<QueryFilter>
		<enabled>true</enabled>
		<security>false</security>
		<class>com.gs.example.query.QueryTaskFilter</class>
		<url>none</url>
		<priority>1</priority>
		<operation-code>2,3,11,13,51</operation-code>
	</QueryFilter>

The generic framework needs to be included as part of the space server setup.

The example classes:

SumTask – implements the custom query logic.
TestRunner – a simple test which populates data into an embedded space, and executes the custom query against that embedded space.

Installing and Running the Example

To install the example, download the CustomQuery.zip archive and extract it to your <GigaSpaces Root>/examples/Advanced/Data_Grid directory.

To run the example, execute the run command from the example directory.

Upon a successful run, you should see the following output:

INFO: java:// protocol. Get <IMDG> space from <IMDG_container> container
 ---> Start write 1000 entries
 ---> Finish write 1000 entries
 ---> Start execute  select sum(accountNumber) from Entity where flags <= 5 1000 entries
 ---> Read Multiple
SumTask: Executing custom SUM query
--> sum = 15
 ---> Total Sum = 15
 ---> Take Multiple
SumTask: Executing custom SUM query
--> sum = 15
 ---> sum(accountNumber) = 15
 ---> Total Sum = 15

Writing your Own Custom Query

To run your own custom query, write a Task class that extends the AbstractQueryTask.java class, similar to the implementation of the SumTask class. Write the querie's business logic as part of the class's execute method.

Using Custom Query Framework Outside Context of the Example

To use the custom query framework outside the environment, put the CustomQuery.zip file in your space and application classpath. When you start the space, make sure you start with a schema argument set to QueryFilter in the following way:

SpaceFinder.find("/./myspace?schema=QueryFilter");