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

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.

Node Manager

The Query screen in the Node Manager allows you to perform AQL queries:

Typescript SDK

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))        }    })})()

C#/.NET SDK

C# SDK

Rust SDK

Rust SDK

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!