Executing standard queries

In order to execute a standard query, your application needs to implement the following steps:

1. Create a new Query event.

2. Initialize the query by calling the Query event's initQuery action passing in the name of the database's Connection event and the query string. The relevant init action should be called each time before calling the query's start action.

3. Call the Query event's setReturnType action to specify the return type. Apama recommends specifying the return type using one of the following constants:

Query.RESULT_EVENT

Query.RESULT_EVENT_HETERO

Query.NATIVE

Query.HISTORICAL

See Return Types below for more information on return types.

4. If the return type is Native, indicate the event type to be returned by specifying it with the Query event's setEventType action.

The setEventType action is defined as:

action setEventType(string eventType)

In addition, you need to add mapping rules to the ADBC adapter's configuration file for the event type being returned.

5. In addition, if the return type is Native, specify the database table column that stores the event's timestamp with the Query event's setTimeColumn action.

The setTimeColumn action is defined as:

action setTimeColumn(string timeColumn)

6. If the query will return a large number of results, call the Query event's setBatchSize action passing in an integer setting the batch size.

7. If you set a batchsize, also use the Query event's setBatchDoneCallback action passing in values for the token and callback parameters.

action setBatchDoneCallback(
string token,
action<Query,string,integer,float,string,string> callback)

8. If the application needs to know the query's result set schema, call the Query event's setSchemaCallback action passing in the name of the handler action.

9. Call the Query event's start action passing in the name of the handler action that will be called when the query completes.

Return Types:

NATIVE — This return type is most commonly used for playback. When a query is run, each row of the query will be passed through the IAF mapping rules and the matching event will be sent as-is to the correlator. The Native return type would not be used for general database queries.

In addition to specifying the Native return type, your query needs to specify the event type to be returned and the name of the database table's column that contains the event's time stamp. Specify the event by using the Query event's setEventType action; specify the time column by using the Query event's setTimeColumn action. You also need to add mapping rules for this event type to the ADBC adapter's configuration file.

HISTORICAL — This return type is also used for playback. When a query is run, each row of the query will be passed through the IAF mapping rules and then the matching event will be wrapped in a container event. The container event will have a name based on that of the event name. For example a Tick event would be wrapped in a HistoricalTick event. Event wrapping allows events to be sent to the correlator without triggering application listeners. A separate user monitor can listen for wrapped events, modify the contained event, and reroute it such that application listeners can match on it. The Wrapped return type would not be used for general database queries.

RESULT_EVENT — This return type is used for general database queries. When a query is run, each row in the result set will be mapped to a dictionary in a generic ResultEvent. The ADBC adapter will generate a SchemaEvent containing the schema (name and type) of the fields in the result set of the query. The SchemaEvent will be sent first, before any ResultEvents.

The definition for ResultEvent is:

event ResultEvent {
    integer messageId; // Unique id of query
    string serviceId;
    integer schemaId; // ResultSchema event schemaId to use with ResultEvent
    dictionary <string, string> row; // Data
  }

The definition for ResultSchema is:

event ResultSchema {
    integer messageId; // Unique id of query
    string serviceId;
    integer schemaId;
    sequence <string> fieldOrder;
    dictionary <string, string> fieldTypes;
    sequence <string> indexFields;
    dictionary<string,string> extraParams;
  }

RESULT_EVENT_HETERO — This return type is intended for advanced database queries. It is not applicable to SQL databases. Some market databases support queries which can, in essence, return multiple tables. For example a market database might allow queries which return streams of both Tick and Quote data. For such databases multiple SchemaEvents would be generated indexed by id.