Getting Started
Create your first data pipeline in TrailStack.
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 10returns at least one row
Prerequisites
- TrailStack Console: sign in and confirm you can open the
Spacespage. curl: verify it is installed withcurl --version.- A terminal: macOS Terminal/iTerm, Linux shell, or Windows PowerShell/WSL.
sourcein 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
- Open the TrailStack Console.
- Go to the Spaces page.
- Click
Create. - Enter a space name (for example,
my-app-events). - 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 tokenClickHouse endpointClickHouse databaseClickHouse usernameClickHouse password
Recommended first:
- Click
Download .envand save it as.my-app-events.envin 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 eventand 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 queryand 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
401or403on ingest: Use the new SpaceInject tokenfrom 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, andClickHouse databaseare 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.