> 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.

# Native and Bounded GraphQL

TraceDB has three separate GraphQL-related surfaces:

* `POST /v1/graphql`: native TraceDB GraphQL root fields with a GraphQL-style
  `data` / `errors` envelope.
* `POST /v1/graphql/bounded`: bounded compatibility adapter that compiles a
  single root table query into the shared query model.
* `GET /v1/graphql/schema`: generated SDL from applied table schemas.

Do not describe bounded GraphQL helpers as native GraphQL execution, and do not
describe the schema route as a resolver runtime.

## Native GraphQL

Native GraphQL accepts implemented TraceDB root fields and returns a standard
GraphQL `data` / `errors` envelope.

```json
{
  "query": "query { get(input: \"{\\\"table\\\":\\\"products\\\",\\\"id\\\":\\\"prod-001\\\",\\\"tenant_id\\\":\\\"tenant-a\\\"}\") { record { id fields } } }"
}
```

Mutating root fields such as `schemaApply`, `put`, `batch`, `patch`, `delete`,
`compact`, `snapshot`, `restore`, and `jobRun` should include
`Idempotency-Key` before idempotency retries are enabled.

## Bounded GraphQL

Bounded GraphQL is a compatibility adapter for a single query-only root table
field.

```json
{
  "query": "{ products(tenant_id: \"tenant-a\", match: \"wireless\", limit: 10) { record_id score { final_score } } }"
}
```

The bounded adapter exposes one list item per row under the selected table
root. It does not support
mutations, subscriptions, aliases, fragments, directives, variables,
introspection, nested query objects beyond `where` / `filter`, or multiple root
table fields.

## Schema Export

`GET /v1/graphql/schema` exports SDL from applied table schemas. It is useful
for understanding bounded adapter shape, but it is not a resolver runtime and
does not imply full GraphQL parity.

GraphQL-specific failures use GraphQL `errors`. Non-GraphQL HTTP routes use the
standard TraceDB error envelope documented in [Errors](/api/errors).