Chapter 7 Working With the Query Language : Lifecycle of a Query—Use of Query Functions

Lifecycle of a Query—Use of Query Functions
This section explains how to use functions to create and execute queries, and to gather query results. In summary:
1.
Create the Query Definition: A query definition is a Java runtime object (similar to a factory class).
2.
Open a Query Statement: A query statement is an object that represents one instance of the query. You can create multiple statements that can run in parallel.
3.
Set Bind Variables (if Used): For the named query statement, set values for bind variables (if any are used in the query definition).
4.
5.
See Closing a Statement and Deleting a Query Definition, for details on how queries and query statements that are no longer used are removed.
Also see Using Data from a Result Set and Using Data from a Callback Rule Function for details on how to get and use query results.
Create the Query Definition
Creating a query definition is a distinct and separate step from opening and executing a query statement. Creating a query definition is the most expensive step in the process of making the query available for execution. Therefore it is often best done at engine startup.
Format:

 
Query.create(String QueryDefinitionName, String QueryText);

 
The query definition name is used in other functions to identify the query definition. The query text contains the select statement.
Example:

 
Query.create("report","select zipcode, total_sales, agent_name from /Concepts/Sales where total_sales > $min");

 
Where $min is a bind variable whose value is provided at runtime.
If a query statement based on this definition is executed and returns a result set, the result set columns would be, zipcode, total_sales, and agent_name, with rows of entity values that match the condition specified at the time the query was executed.
Open a Query Statement
Format:

 
Query.Statement.open(String QueryDefinitionName, String StatementName);

 
The query definition name references the query definition that contains the query text. The statement name defined here is used in other functions to identify this query statement.
Example:

 
Query.Statement.open("report", S_Id);

 
Where S_Id is a string variable that contains the statement name. Names can be constructed in various ways, as shown in Simple Snapshot Query Example.
Set Bind Variables (if Used)
If you used bind variables in the query definition, then you set the values after opening the query statement, and before executing it. This sequence is required. The functions need not be executed right after each other, however. For example, the Query.Statement.open() function could be in a startup rule function and the Query.Statement.setvar() function could be in a rule function called on assertion of an event, followed by the Query.Statement.execute() function.
Open a named query statement for each set of variable values that are used at execution time. For example, if you set the variable values two different ways, you would provide two open query statements, each with its own name, to keep the configured queries and their returned information distinct from each other
Format

 
Query.Statement.setVar(String StatementName, String BindVariableName, Object Value);

 
Example

 
Query.Statement.setVar(S_Id, "min", evt.min_total_sales);

 
See Using Bind Variables in Query Text for more details.
Execute an Instance of the Query Statement and Obtain Results
To execute a query and specify how a query returns values, you use one of the following functions:
Query.Statement.execute() provides results using a result set. This function is used for snapshot queries only.
Query.Statement.executeWithCallback() provides results using a callback rule function, which is called once for each matching result. This function can be used with snapshot or continuous queries.
To Obtain Results Using a Result Set
The Query.Statement.execute() function returns values in a result set. The result set is a tabular form (with rows and columns) on which you can perform operations to return data. It is used for snapshot queries only. Execution is synchronous.
Format

 
Query.Statement.execute(String StatementName, String resultsetName);

 
Example

 
Query.Statement.execute(S_Id, evt@extId);

 
In the above example, S_Id is a string variable providing the name that was given in the Query.Statement.open() function. The example shows use of the external ID of event evt (evt@extId) as the result set name, as a way to ensure that each result set has a unique name.
See Using Data from a Result Set for more information.
Closing a Result Set
After you have collected the data you need, close the result set. You can close the result set directly, or close it indirectly by closing a higher-level item such as the the statement or the query definition. To close the result set use the following function:
Query.ResultSet.close(String ResultsetName);
For example:
Query.ResultSet.close("rset");
To Obtain Results Using a Callback Rule Function
You can use Query.Statement.executeWithCallback(), for snapshot or continuous queries. If you set the IsContinuous argument to true, the query runs as a continuous query.
The behavior depends on whether the query executes as a snapshot or as a continuous query:
When used with snapshot queries, the query looks at the current state of the cache and calls the rule function once for each matching row, in quick succession.
When used in continuous queries, the query listens for changes to the cache, and calls the rule function as matches occur over the lifetime of the query.
The format of the Query.Statement.executeWithCallback() function is shown below.
Format

 
Query.Statement.executeWithCallback(
String  StatementName,
String  ExecutionName,
String  CallbackUri,
boolean IsContinuous,
Object  Closure)
The ExecutionName parameter keeps results from different executions distinct from each other.
The CallbackUri parameter value provides the project path to the callback rule function.
The IsContinuous parameter defines if the query is a snapshot or continuous query.
The Closure parameter is stored during the execution of the query, and provided as a parameter to the callback function every time that function is called.
Example

 
String execID = evt@extId;
Query.Statement.executeWithCallback(
MyStmt, MyexecID, "/MyRuleFunction", false, evt);

 
See Using Data from a Callback Rule Function for more details.
Closing a Statement and Deleting a Query Definition
You can close or delete at different levels. You can delete a query definition to make room for new query definitions. You can also delete (close) the statement that is running, without deleting the query definition itself. Use the following functions as needed for your situation:
Query.Statement.close(String StatementName);
Query.delete(String QueryDefinitionName);
When you delete a query or a statement, all their subordinate artifacts are deleted as well, including result sets.
You can also close just the result set. See Closing a Result Set.