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

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

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

Query, filter, full-text search and vector search documents.

## 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 schema of the namespace.

- QueryResult — The result of a query.
  - `aggregations` object
  - `aggregation_groups` AggregationGroup[]
  - `rows` Row[]
    - `id` union, required — An identifier for a document.
      - string, uuid — A UUID.
      - string — A string ID.
      - integer — An integer ID.
    - `vector` union — A vector embedding associated with a document.
      - number[] — A dense vector encoded as an array of floats.
      - string — A dense vector encoded as a base64 string.
  - `performance` QueryPerformance, required — The performance information for a query.
    - `cache_hit_ratio` number, required — The ratio of cache hits to total cache lookups.
    - `cache_temperature` string, required — A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`).
    - `server_total_ms` integer, required — Request time measured on the server, including time spent waiting for other queries to complete if the namespace was at its concurrency limit.
    - `query_execution_ms` integer, required — Request time measured on the server, excluding time spent waiting due to the namespace concurrency limit.
    - `exhaustive_search_count` integer, required — The number of unindexed documents processed by the query.
    - `approx_namespace_size` integer, required — the approximate number of documents in the namespace.
  - `billing` QueryBilling, required — The billing information for a query.
    - `billable_logical_bytes_queried` integer, required — The number of billable logical bytes queried from the namespace.
    - `billable_logical_bytes_returned` integer, required — The number of billable logical bytes returned from the query.

## 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)