Query events with AQL
The Actyx Query Language (AQL) allows you to query, filter, transform, and soon aggregate events in a structured fashion.
Features
AQL currently has the following features:
- Query events by source, tags, app ID, timestamp, event key
- Filter by event payload to discard events
- Select event payload contents
- Transform event payloads using arithmetic operations and case expressions
Currently, AQL queries (or subscriptions) always return events. The ability to aggregate (e.g. SUM) events is being worked on.
Run AQL queries
You can run AQL queries using the CLI, the Node Manager or any of the SDKs. Here are examples how to use AQL in each one:
- CLI
- Node Manager
- Typescript SDK
- C#/.NET SDK
- Rust SDK
Use the Actyx CLI's events query
subcommand to run AQL queries:
ax events query localhost "FROM 'discovery'"
This will return a list of JSON objects which are either events or errors/warnings if the query is invalid or cannot be executed.
The Query screen in the Node Manager allows you to perform AQL queries:
Install the Typescript/Javascript SDK using npm install @actyx/sdk
and then run AQL queries as follows:
import { Actyx } from '@actyx/sdk'
;(async () => {
// Connect to the local Actyx process
const actyx = await Actyx.of({
appId: 'com.example.app',
displayName: 'Example App',
version: '1.0.0',
})
// Run AQL query
const results = await actyx.queryAql("FROM 'discovery'")
// Do something with the results
results.forEach((result) => {
if (result.type === 'event') {
console.log(JSON.stringify(result.payload))
}
})
})()
Query events by time
Beta features
If a query begins with FEATURES()
it uses beta functionality. Please refer to the AQL reference guide for a detailed specification of AQL and its features.
You can query events by their timestamp. This is an example of a query for events between 14:09 and 14:11 on 06 August 2021:
FEATURES(timeRange)
FROM from(2021-08-06T14:09:00Z) & to(2021-08-06T14:11:00Z)
Query events by tags
In addition to a specific time, you could also add a query for specific tags:
FEATURES(timeRange)
FROM from(2021-08-06T14:09:00Z) & to(2021-08-06T14:11:00Z)
& 'machine2512'
Usage of tags
When published, each event can be tagged with an arbitrary number of tags. Check out conceptual guide on tags or our how-to guides for business logic for more info.
Tags with IDs
By convention, events corresponding to a specific instance of a domain entity are tagged with <entity>:<id>
.
When using Actyx Pond, you will have come across the Tag.withId()
helper.
It uses this convention as well.
So, e.g., you'd use FROM 'machine:42'
to select events that have been tagged with Tag<MachineEvent>('machine').withId(42)
.
Query events by app ID
You could add also use a query such as the following to get the events for a specific appId and tag:
FROM 'machine2512' & appId(com.actyx.example)
Transform data
With AQL, you can write down the transformation from events into query results in an incremental fashion, doing one step at a time.
For the following example, we assume that our event payload is structured as follows:
{
"byUser": {
"name": "<string>",
"id": "<string>"
},
"type": "<string>",
...
}
Filter events
If one of the above examples was not be specific enough, you can also filter out certain results:
FEATURES(timeRange)
FROM from(2021-08-06T14:09:00Z) & to(2021-08-06T14:11:00Z)
FILTER _.type = "Started"
The above query only returns events that have a property "type" with value "Started".
Transform events
For the returned events, you can also modify the format of the payload:
FEATURES(timeRange)
FROM from(2021-08-06T14:09:00Z) & to(2021-08-06T14:11:00Z)
FILTER _.type = "Started"
SELECT _["byUser"].name <--- As the property is camelCase, you have to use a specific syntax
The above query only returns the value of the property "name" within the property "byUser".
If you have any questions, comments, or suggestions, we very much welcome you to our forum or discord chat!
Full reference documentation
Check out our reference documentation on AQL for more info on expressions and data transformations!