Getting Started

This guide follows the Console getting started tutorial: create a Space, ingest a JSON event, wait for transformation, and query records from ClickHouse.

Quick Start Snapshot

• Goal: create one Space and verify end-to-end JSON-to-SQL flow
• Time: about 5-10 minutes (including transformation time)
• Final result: SELECT * FROM evt__records LIMIT 10 returns at least one row

Prerequisites

• TrailStack Console: sign in and confirm you can open the Spaces page.
• curl: verify it is installed with curl --version.
• A terminal: macOS Terminal/iTerm, Linux shell, or Windows PowerShell/WSL.
• source in examples is for bash/zsh. On Windows, use WSL or set variables manually in your shell.
• Permission to create a Space in your TrailStack workspace.

1. Create a Space

1. Open the TrailStack Console.
2. Go to the Spaces page.
3. Click Create.
4. Enter a space name (for example, my-app-events).
5. Click Create space.

Your Space is the pipeline that transforms incoming JSON events into typed SQL tables backed by ClickHouse.

Success check:

• You see Space "<name>" successfully created.
• You see the credentials/result page with ingest and query examples.

2. Collect Credentials and Endpoints

On the result page, copy these values:

• Inject token
• ClickHouse endpoint
• ClickHouse database
• ClickHouse username
• ClickHouse password

Recommended first:

• Click Download .env and save it as .my-app-events.env in your working directory. The next snippets use this exact filename.

Optional:

• Download CSV: exports credentials as a table for secure storage.

Note:

• The credentials page warns these values may not be shown again. Store them in your secret manager.

3. Ingest a Test Event

Recommended:

• Expand Ingest example event and run the exact generated command.

Template (for scripting):

source .my-app-events.env

curl -X POST "https://api.trailstack.io/v1/Spaces/AppendRecords?spaceName=$TRAILSTACK_SPACE_NAME&fireAndForget=false" \
  -H "Authorization: Bearer $TRAILSTACK_INJECT_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary '{"source":"example","event":"test_event","attrs":{"str":"Hello TrailStack!"}}'

Success check:

• Command exits with 0.
• No auth error is returned.

4. Wait for Transformation

TrailStack transforms JSON into typed SQL tables. This usually takes a couple of minutes.

Success check:

• While transformation is running, the page shows a spinner message.
• When transformation finishes, the query command starts returning rows.

5. Query Data as SQL

Recommended:

• Expand Make a database query and run the exact generated command.

Template (for scripting):

source .my-app-events.env

curl -X POST "https://api.trailstack.io:8443?database=$TRAILSTACK_CLICKHOUSE_DB" \
  -u "$TRAILSTACK_CLICKHOUSE_USER:$TRAILSTACK_CLICKHOUSE_PASSWORD" \
  -d "SELECT * FROM evt__records LIMIT 10 FORMAT Pretty"

Success check:

• Command exits with 0.
• Output contains at least one row from evt__records.

6. Complete Setup

Click Complete to return to the Spaces list.

You can reopen the Space later to view endpoint and connection details.

Troubleshooting

• 401 or 403 on ingest: Use the new Space Inject token from the result page and retry.
• Query returns no rows: Wait 1-2 more minutes and run the same query again.
• Query auth failure: Verify ClickHouse username, ClickHouse password, and ClickHouse database are from the same Space.

Next Steps

• Send real application events to AppendRecords.
• Replace the demo query with event-specific SQL.
• Configure Space retention (TTL months) if needed.