TraceQL

TraceQL executes through POST /v1/traceql. It is a polymorphic route: a payload can be a read-only query or a mutating command. SDKs and gateway policy must classify the payload before deciding whether a retry is safe.

Read-Only Query

1
{
2
  "query": "FROM products TENANT tenant-a MATCH description \"wireless mouse\" LIMIT 10"
3
}

Read-only TraceQL returns the same query response shape as the native query route. Transient failures may be retried only when the SDK can prove the payload is read-only.

Mutating Command

1
{
2
  "query": "PUT products tenant-a prod-004 {\"price\": 9.99, \"description\": \"Mouse pad\"}"
3
}

Mutating TraceQL requests require Idempotency-Key before idempotency retries are allowed. Empty keys and keys containing CR/LF must be rejected before network I/O.

SQL-ish Boundary

TraceQL includes a bounded SQL-ish SELECT adapter for compatibility:

1
{
2
  "query": "SELECT * FROM products WHERE tenant_id = 'tenant-a' AND in_stock = true LIMIT 10"
3
}

This is not SQL or PostgreSQL compatibility. JOIN, GROUP, ORDER, UNION, DDL, DML, and arbitrary SQL execution are outside the v0 contract.

Use the API reference for the exact TraceQlQueryRequest and TraceQlQueryResponse shapes.