Quickstart

Create a table, load a few events, and query them with ScopeQL.

You need a reachable ScopeDB endpoint and a way to run ScopeQL statements. If you have not set up your endpoint and API key yet, start with Connect to ScopeDB.

1. Create an event table

Event data usually has a few fields you query often and a larger payload that changes over time. Start with typed columns for stable fields and an object column for the original event.

CREATE TABLE events (
    time timestamp,
    service string,
    name string,
    message string,
    var object
);

2. Insert sample events

Use VALUES to create a small input relation, then reshape each row before inserting it.

VALUES
    (
        '2026-01-21T10:00:00Z',
        'checkout',
        'checkout_started',
        'User opened checkout',
        {'region': 'apac', 'plan': 'pro'}
    ),
    (
        '2026-01-21T10:00:03Z',
        'checkout',
        'payment_failed',
        'Credit card gateway timed out',
        {'region': 'apac', 'gateway': 'credit_card'}
    )
SELECT
    $0::timestamp AS time,
    $1::string AS service,
    $2::string AS name,
    $3::string AS message,
    $4::object AS var
INSERT INTO events;

3. Query recent events

ScopeQL is a pipeline. Start from a relation, filter it, then select the fields you want to return.

FROM events
WHERE service = 'checkout'
SELECT time, name, message, var['region']::string AS region
ORDER BY time DESC
LIMIT 10;

4. Aggregate events

Use GROUP BY ... AGGREGATE to summarize the same table.

FROM events
WHERE time >= '2026-01-21T10:00:00Z'::timestamp
GROUP BY service, name
AGGREGATE count() AS events
ORDER BY events DESC;

5. Next steps

Continue with:

• Ingest events to load application data through the ingest API.
• Query events to learn the common query patterns for event data.
• Model flexible events to decide what belongs in typed columns and what belongs in var.
• HTTP API if you want to call ScopeDB from your own service.