---
title: "Query a table"
method: POST
path: "/v1/table/{id}/query"
tags: ["Table"]
---

# Query a table

`POST /v1/table/{id}/query`

Query a table with vector search and optional filtering. Returns results in Arrow IPC stream format.

## Path parameters

- `id` string, required

## Request body

- QueryRequest
  - `name` string, required
  - `namespace` string[], required
  - `bypass_vector_index` boolean, nullable — Whether to bypass vector index
  - `columns` string[], nullable — Optional list of columns to return
  - `distance_type` string, nullable — Distance metric to use
  - `ef` integer, nullable — Search effort parameter for HNSW index
  - `fast_search` boolean, nullable — Whether to use fast search
  - `filter` string, nullable — Optional SQL filter expression
  - `full_text_query` QueryRequestFullTextQuery, nullable — Optional full-text search query. Provide either string_query or structured_query, not both.
    - `string_query` StringFtsQuery
      - `columns` string[], nullable
      - `query` string, required
    - `structured_query` StructuredFtsQuery
      - `query` FtsQuery, required — Full-text search query. Exactly one query type field must be provided. This structure follows the same pattern as AlterTransactionAction to minimize differences and compatibility issues across codegen in different languages.
        - `match` MatchQuery
          - `boost` number, float
          - `column` string, nullable, required
          - `fuzziness` integer, nullable
          - `max_expansions` integer — The maximum number of terms to expand for fuzzy matching. Default to 50.
          - `operator` 'And' | 'Or'
          - `prefix_length` integer — The number of beginning characters being unchanged for fuzzy matching. Default to 0.
          - `terms` string, required
        - `phrase` PhraseQuery
          - `column` string, nullable
          - `slop` integer
          - `terms` string, required
        - `boost` BoostQuery — Boost query that scores documents matching positive query higher and negative query lower
          - `positive` FtsQuery, required — recursive
          - `negative` FtsQuery, required — recursive
          - `negative_boost` number, float — Boost factor for negative query (default: 0.5)
        - `multi_match` MultiMatchQuery
          - `match_queries` MatchQuery[], required
            - `boost` number, float
            - `column` string, nullable, required
            - `fuzziness` integer, nullable
            - `max_expansions` integer — The maximum number of terms to expand for fuzzy matching. Default to 50.
            - `operator` 'And' | 'Or'
            - `prefix_length` integer — The number of beginning characters being unchanged for fuzzy matching. Default to 0.
            - `terms` string, required
        - `boolean` BooleanQuery — Boolean query with must, should, and must_not clauses
          - `must` FtsQuery[], required — Queries that must match (AND)
          - `must_not` FtsQuery[], required — Queries that must not match (NOT)
          - `should` FtsQuery[], required — Queries that should match (OR)
  - `k` integer, required — Number of results to return
  - `lower_bound` number, float, nullable — Lower bound for search
  - `nprobes` integer, nullable — Number of probes for IVF index
  - `offset` integer, nullable — Number of results to skip
  - `prefilter` boolean, nullable — Whether to apply filtering before vector search
  - `refine_factor` integer, nullable — Refine factor for search
  - `upper_bound` number, float, nullable — Upper bound for search
  - `vector` QueryRequestVector, nullable, required — Query vector(s) for similarity search. Provide either single_vector or multi_vector, not both.
    - `single_vector` number[] — Single query vector
    - `multi_vector` array[] — Multiple query vectors for batch search
      - number[]
  - `vector_column` string, nullable — Name of the vector column to search
  - `version` integer, nullable — Table version to query
  - `with_row_id` boolean, nullable — If true, return the row id as a column called `_rowid`

## Response `200`

Query results in Arrow IPC stream format

## Other responses

- `400` — Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
- `401` — Unauthorized. The request lacks valid authentication credentials for the operation.
- `403` — Forbidden. Authenticated user does not have the necessary permissions.
- `404` — A server-side problem that means can not find the specified resource.
- `503` — The service is not ready to handle the request. The client should wait and retry. The service may additionally send a Retry-After header to indicate when to retry.
- `5XX` — A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

## Changes

- **2025-07-21** `6790486d1fac` — 14 breaking, 19 warning, 49 info
  - added the new required request property `name`
  - added the new required request property `namespace`
  - request property `full_text_query/structured_query/query/match/operator` was restricted to a list of enum values
  - request property `full_text_query/structured_query/query/multi_match/match_queries/items/operator` was restricted to a list of enum values
  - …78 more

[Change history](https://skmtc.dev/lance-format/apis/lance-namespace-specification/changes/v1/table/:id/query/post.md)

---

[API](https://skmtc.dev/lance-format/apis/lance-namespace-specification.md) · [All operations](https://skmtc.dev/lance-format/apis/lance-namespace-specification/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lance-format/lance-namespace-specification/revisions/6790486d1fac/schema)