Getting Started

The smallest useful ChronusQL query reads JSON events from an input stream, projects fields, and writes JSON rows to an output stream.

SELECT value INTO output FROM input

Tested input:

{"value":1}
{"value":2}

Tested output:

{"value":1}
{"value":2}

ChronusQL streams JSON objects. A query names an input stream in `FROM`, names an output stream in `INTO`, and emits one JSON object per output row unless the query is an aggregate query.

The first filtering example from the tests is:

SELECT value INTO output FROM input WHERE value > 10

Tested input:

{"value":5}
{"value":12}
{"value":20}

Tested output:

{"value":12}
{"value":20}

The same query can be executed through the CLI by passing a query string, a named input binding, and a named output binding:

chronusql --query "SELECT value INTO output FROM input WHERE value > 10" --input input=input.jsonl --output output=output.jsonl

The current test harness calls the CLI entry point with these arguments:

var args = new[]
{
    "--query", sql,
    "--input", $"input={inputPath}",
    "--output", $"output={outputPath}"
};

First Timestamp Example

ChronusQL can use a timestamp field from each JSON payload:

SELECT value INTO output FROM input TIMESTAMP BY ts

Tested input:

{"ts":1000,"value":3}
{"ts":2000,"value":4}

Tested output:

{"value":3}
{"value":4}

`TIMESTAMP BY` is required for event-time windows, `MATCH_RECOGNIZE`, and `WINDOW BY ... COMPUTE`. If `TIMESTAMP BY` is omitted, ChronusQL uses the input event arrival time.

First Windowing Example

A tumbling window groups events into fixed event-time intervals:

SELECT Window.EndTime AS WindowEnd, COUNT(*) AS EventCount
INTO output
FROM input TIMESTAMP BY ts
GROUP BY TumblingWindow(Duration(minute, 2))

With events at minute 0, 1, 2, 3, and 4, the tested result is three rows: two events in the first 2-minute window, two events in the next, and one event in the final window.

{"WindowEnd":638712865200000000,"EventCount":2}
{"WindowEnd":638712866400000000,"EventCount":2}
{"WindowEnd":638712867600000000,"EventCount":1}

The core event-time flow is:

flowchart LR
    A["JSON input events"] --> B["TIMESTAMP BY field or arrival time"]
    B --> C["Filter and project"]
    C --> D["Optional grouping or windowing"]
    D --> E["JSON output rows"]