---
title: "POST /v2/namespaces/{namespace}/explain_query"
method: POST
path: "/v2/namespaces/{namespace}/explain_query"
---

# POST /v2/namespaces/{namespace}/explain_query

`POST /v2/namespaces/{namespace}/explain_query`

Explain a query plan.

## Path parameters

- `namespace` string, required

## Request body

- object — Query, filter, full-text search and vector search documents.
  - `vector_encoding` union — The encoding to use for vectors in the response.
    - 'float'
    - 'base64'
  - `consistency` object — The consistency level for a query.
    - `level` union — The query's consistency level.
      - 'strong' — Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
      - 'eventual' — Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
  - `rank_by` unknown
  - `top_k` integer — The number of results to return.
  - `filters` unknown
  - `include_attributes` union — Whether to include attributes in the response.
    - boolean — When `true`, include all attributes in the response. When `false`, include no attributes in the response.
    - string[] — Include exactly the specified attributes in the response.
  - `exclude_attributes` string[] — List of attribute names to exclude from the response. All other attributes will be included in the response.
  - `aggregate_by` object — Aggregations to compute over all documents in the namespace that match the filters.
  - `group_by` unknown[] — Groups documents by the specified attributes (the "group key") before computing aggregates. Aggregates are computed separately for each group.
    - unknown
  - `compute_attributes` object — Computes additional values on documents returned by a query. Each key is the name of the computed attribute; each value is an expression describing how to compute it.
  - `distance_metric` union — A function used to calculate vector similarity.
    - 'cosine_distance' — Defined as `1 - cosine_similarity` and ranges from 0 to 2. Lower is better.
    - 'euclidean_squared' — Defined as `sum((x - y)^2)`. Lower is better.
  - `limit` union
    - integer
    - Limit — Limits the documents returned by a query.
      - `total` integer, required — Limits the total number of documents returned.
      - `per` object — Limits the number of documents with the same value for a set of attributes (the "limit key") that can appear in the results.
        - `attributes` string[], required — The attributes to include in the limit key.
        - `limit` integer, required — The maximum number of documents to return for each value of the limit key.

## Response `200`

The query plan explanation.

- object — The response to a successful query explain.
  - `plan_text` string — The textual representation of the query plan.

## Other responses

- `default` — An error response.

---

[API](https://skmtc.net/turbopuffer/apis/turbopuffer-api.md) · [All operations](https://skmtc.net/turbopuffer/apis/turbopuffer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/turbopuffer/turbopuffer-api/versions/245e887f04ab/schema)