Defining query keys

At runtime, each partition is identified by a unique key value, which is the value of one or more fields in the events that the query operates on.

Note: Using a key is optional. If you do not specify a key, all events the query operates on are in one partition. Since this is an unusual use case for queries, the documentation assumes that you always choose to specify a key.

An event member that is declared as a constant cannot be used as a query key.

In a query, each input definition in the inputs section specifies the query key in the key definition. The key definition specifies one or more fields in the event that the window will contain. For example:

query ImprobableWithdrawalLocations {
inputs {
Withdrawal() key cardNumber within (600.0);
}
find (Withdrawal:w1 -> Withdrawal:w2)
where (w1.country != w2.country) {
getAccountInfo();
sendEmail();
}
}

In this example, the definition for Withdrawal events specifies that the cardNumber field is the key. When the correlator processes a Withdrawal event, it adds the event to the partition identified by the Withdrawal event's cardNumber value.

Suppose the input definition in this example specifies two key fields:

Each partition is now identified by a combination of the cardNumber value and the cardType value. When you specify two or more key fields, insert a comma after each field except the last one. It is allowable to specify key fields in an order that is different than the order of the fields in the event.

When you specify more than one input in a query, each input definition must specify the same number and data type order of key fields. For example:

For each input in this example, the key is the cardNumber field. The data type of the cardNumber field in the Withdrawal event must be the same as the data type of the cardNumber field in the AddressChange event.

Sometimes, a field in one event contains the same information as a field in another event but the two fields have different names. For example, information about the type of a card could be in the cardType field in Withdrawal events and the typeOfCard field in AddressChange events. In this situation, you must specify an alias for one of the event field names. You do this in the input definition's key definition. In the following example, as cardType in the second input definition specifies the alias:

inputs {
Withdrawal() key cardNumber, cardType within (600.0);
AddressChange() key cardNumber, typeOfCard as cardType retain 1;
}

When you specify more than one input, the key definition in each input definition must specify the same number of fields in the same order. Also, the data type of a field in one key definition must be the same as the data type of its corresponding field in every other key definition in the same inputs block. If the names of corresponding key fields are not the same, you must use the as keyword to specify an alias.

While specification of an alias for a key field name is sometimes required, it is always an option you can choose to use. For example:

inputs {
Withdrawal() key number as cardNumber, cardType within (600.0);
AddressChange() key number as cardNumber, typeOfCard as cardType retain 1;
}

An alias maps a field in an event to a key field. You cannot use an alias as a field of the event. For example, consider the following query:

query Q {
inputs {
A() key surname as lastName, dob as dateOfBirth retain 5;
B() key lastName, dateOfBirth retain 4;
}
find A:a -> B:b ...
}