Spaces

A Space is your data pipeline — where JSON events become SQL tables.

What a Space is

A Space is a self-contained data pipeline. Each Space has its own:

• Ingestion endpoint — a single HTTPS URL where you send JSON events
• Inject token — a bearer token that authenticates your event submissions
• ClickHouse database — where your events are stored as typed SQL tables
• Credentials — username, password, and connection endpoint for querying
• Storage quota and compute budget — tracked and billed independently

Spaces are isolated from each other. Events sent to one Space are not visible from another. Each Space manages its own tables, schema evolution, and storage metering independently.

How events flow

Every event follows the same path from JSON to SQL:

1. Ingest — you send a JSON payload via HTTP POST to the AppendRecords endpoint.
2. WAL — the event is written to the write-ahead log and acknowledged.
3. Transform — TrailStack detects the event schema, creates or evolves ClickHouse tables, and inserts typed rows.
4. Query — your data is available via standard ClickHouse SQL, typically within about a minute.

Each event type gets its own view, named evt_<event>. If you send {"event": "page_view", ...}, TrailStack creates a view called evt_page_view with your properties as typed columns. When you send events with new fields, columns are added automatically. See Ingestion Guide for type detection and edge cases.

Transformation typically takes about a minute.

How to query your data

You can use any ClickHouse-compatible client to query your data. All queries go over the ClickHouse HTTP interface on port 8443:

• curl — for quick one-off checks from the terminal
• Grafana — for building dashboards (see Connecting Tools)
• DBeaver — for visual SQL exploration
• AI/MCP tools — Claude Desktop or Cursor can query your data in plain English

The all_events view spans all event types in a Space. Use it to see what data you have:

SELECT event_name, count()
FROM all_events
WHERE time > now() - INTERVAL 24 HOUR
GROUP BY event_name
ORDER BY count() DESC
LIMIT 10

For queries on a specific event type, use the typed view directly:

SELECT *
FROM evt_page_view
WHERE time > now() - INTERVAL 1 HOUR
LIMIT 100

Your credentials

Each Space generates a complete set of credentials when you create it:

Your credentials are shown in the Connection details section on the Space page after creation. The password is displayed once — copy it immediately. Store your credentials somewhere safe: a secret manager, a password vault, or at minimum a local file that isn't committed to version control.

If you lose your credentials, you can issue new ones from the Space page using Issue new credentials. Your existing data stays — you don't need to recreate the Space.