> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# 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

```json
{
  "query": "FROM products TENANT tenant-a MATCH description \"wireless mouse\" LIMIT 10"
}
```

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

```json
{
  "query": "PUT products tenant-a prod-004 {\"price\": 9.99, \"description\": \"Mouse pad\"}"
}
```

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:

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

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.