Learn more about the Cortex Query Language transaction stage used to find transactions based on events that meet certain constraints.
Note
This stage is unsupported with RT Correlation Rules.
Syntax
transaction<field_1, field_2, ...>[span =<time>[timeshift =<epoch time>[timezone = "<time zone>"]] | startswith =<condition>endswith =<condition>allowunclosed= true|false] maxevents =<number of events per transaction>
Description
The transaction stage is used to find transactions based on events that meet certain constraints. This stage aggregates all fields in a JSON string array by fields defined as transaction fields. For example, using the transaction stage to find transactions based on the user and user_ip fields will make the aggregation of json strings of all fields by the user and user_ip fields. A maximum of 50 fields can be aggregated in a transation stage.
You can also configure whether the transactions falls within a certain time frame, which is optional to define. You can set one of the following:
span=: Use this command to set a time frame per transaction, where<time><time>timeshift =, which are both optional. You can configure the<epoch time>timezone = "<time zone>"<time zone>“+08:00”, or using a time zone name from the List of Supported Time Zones, such as"America/Chicago". The query still runs without defining the epoch time or time zone. If notimeshift =is set, the query runs according to last time set in the log.<epoch time>timezone = "<time zone>"startswithandendswith: Use these commands to set a condition for the beginning or end of the transaction, where the condition can be a logical expression or free text search.
Set the allowunclosed flag to true to include transactions which don't contain an ending event. The last event will be 12 hours after the starting event. By default, this is set to true and transactions without an ending event are included.
Use the maxevents command to define the maximum number of events to include per transaction. If this command is not set, the default value is 100.
When using the transaction stage, 5 additional fields are added to the results displayed:
_start_time: Indicates the initial timestamp of the transaction._end_time: Indicates the last timestamp for the transaction._duration: Displays the difference in seconds between the timestamps for the first and last events in the transaction._num_of_rows: Indicates the number of events in the transaction._transaction_id: Displays the unique transaction ID.
Time Suffix | Description |
|---|---|
MS | milliseconds |
S | seconds |
M | minutes |
H | hours |
D | days |
W | weeks |
MO | months |
Y | years |
Example using Span
Return a maximum of 10 events per transaction from the xdr_data records based on the user and agent_id fields, where the transaction time frame is 1 hour.
dataset=xdr_data |transaction user, agent_id span=1h timeshift = 1615353499 timezone = “+08:00” maxevents=10
This query results in the following XQL JSON:
{'TRANSACTION': {'fields': ['user', 'agent_id'], 'maxevents': 10, 'span': {'amount': 1, 'units': 'h', 'timeshift': None}}}Example using Startswith and Endswith
Return a maximum of 99 events per transaction from the xdr_data records based on the f1 and f2 fields. The starting event of each transaction is an event, where one of the fields contains a string "str_1", and the ending event of each transaction is an event, where one of the fields contains a string "str_2".
dataset=xdr_data | transaction f1, f2 startswith="str_1" endswith="str2" maxevents=99
This query results in the following XQL JSON:
{'TRANSACTION': {'fields': ['f1', 'f2'], 'search': {'startswith': {'filter': {'free_text': 'str_1'}}, 'endswith': {'filter': {'free_text': 'str2'}}}, 'maxevents': 99}}