v52

latestOpenAPI 3.1.1Apache 2.0raw.githubusercontent.com2026-08-0354155395.9 KB

Table

Data

Query a table

Query table id with vector search, full text search and optional SQL filtering. Returns results in Arrow IPC file or stream format.

REST NAMESPACE ONLY REST namespace returns the response as Arrow IPC file binary data instead of the QueryTableResponse JSON object. The REST response maps to the QueryTableResponse model as follows:

the Arrow IPC file binary body maps to data
response headers map to context via the header. prefix (see the Context schema)

post/v1/table/{id}/query

Path parameters

idstring required

string identifier of an object in a namespace, following the Lance Namespace spec. When the value is equal to the delimiter, it represents the root namespace. For example, v1/namespace/$/list performs a ListNamespace on the root namespace.

Query parameters

delimiterstring

An optional delimiter of the string identifier, following the Lance Namespace spec. When not specified, the $ delimiter must be used.

Request body

{"stackTrail":"components:schemas:QueryTableRequest:properties:context","oasType":"schema","type":"unknown","description":"Arbitrary context as key-value pairs.\nHow to use the context is custom to the specific implementation.\n\nOn a request, it carries caller-provided context to the implementation.\nOn a response, it carries implementation-provided context back to the caller.\n\nREST NAMESPACE ONLY\nContext entries are mapped to and from HTTP headers using the `header.` prefix:\n- On a request, any entry whose key starts with `header.` is sent as an HTTP\n request header with the prefix stripped. For example, the entry\n `{\"header.Authorization\": \"Bearer abc\"}` is sent as the request header\n `Authorization: Bearer abc`.\n- On a response, every HTTP response header is returned as an entry whose key is the\n header name prefixed with `header.`. For example, the response header\n `x-request-id: abc123` is returned as the entry `{\"header.x-request-id\": \"abc123\"}`.\n"}

idstring[]

branchstring

Branch to target. When not specified, the main branch is used.

bypass_vector_indexboolean

Whether to bypass vector index

distance_typestring

Distance metric to use

efinteger

Search effort parameter for HNSW index

fast_searchboolean

Whether to use fast search

filterstring

Optional SQL filter expression. Field references in the expression must use Lance field path syntax: nested fields use dot-separated segments, literal dots require backtick-quoted segments, and backticks inside quoted segments are doubled.

kinteger required

Number of results to return

lower_boundnumber float

Lower bound for search

nprobesinteger

Number of probes for IVF index

offsetinteger

Number of results to skip

prefilterboolean

Whether to apply filtering before vector search

refine_factorinteger

Refine factor for search

upper_boundnumber float

Upper bound for search

vector_columnstring

Lance field path of the vector field to search. Nested fields use dot-separated segments; use backtick-quoted segments for literal dots and double backticks inside quoted segments. Use canonical full paths for display and errors; leaf names alone only identify top-level fields; invalid or unresolved paths should return InvalidInput or TableColumnNotFound.

versioninteger

Table version to query

with_row_idboolean

If true, return the row id as a column called _rowid

Example request

{
  "ef": 0,
  "offset": 0,
  "columns": {
    "column_aliases": {
      "key": "column_aliases"
    },
    "column_names": [
      "column_names",
      "column_names"
    ]
  },
  "vector_column": "vector_column",
  "fast_search": true,
  "k": 0,
  "upper_bound": 1.2315135,
  "branch": "branch",
  "version": 0,
  "with_row_id": true,
  "prefilter": true,
  "filter": "filter",
  "refine_factor": 0,
  "full_text_query": {
    "string_query": {
      "columns": [
        "columns",
        "columns"
      ],
      "query": "query"
    },
    "structured_query": {
      "query": {
        "boolean": {
          "must_not": [
            null,
            null
          ],
          "should": [
            null,
            null
          ],
          "must": [
            null,
            null
          ]
        },
        "phrase": {
          "terms": "terms",
          "column": "column",
          "slop": 0
        },
        "match": {
          "fuzziness": 0,
          "terms": "terms",
          "column": "column",
          "boost": 6.0274563,
          "prefix_length": 0,
          "operator": "operator",
          "max_expansions": 0
        },
        "boost": {
          "negative": null,
          "negative_boost": 7.0614014,
          "positive": null
        },
        "multi_match": {
          "match_queries": [
            {
              "fuzziness": 0,
              "terms": "terms",
              "column": "column",
              "boost": 6.0274563,
              "prefix_length": 0,
              "operator": "operator",
              "max_expansions": 0
            },
            {
              "fuzziness": 0,
              "terms": "terms",
              "column": "column",
              "boost": 6.0274563,
              "prefix_length": 0,
              "operator": "operator",
              "max_expansions": 0
            }
          ]
        }
      }
    }
  },
  "distance_type": "distance_type",
  "lower_bound": 3.6160767,
  "identity": {
    "api_key": "api_key",
    "auth_token": "auth_token"
  },
  "bypass_vector_index": true,
  "nprobes": 0,
  "context": {
    "key": "context"
  },
  "vector": {
    "single_vector": [
      1.0246457,
      1.0246457
    ],
    "multi_vector": [
      [
        1.4894159,
        1.4894159
      ],
      [
        1.4894159,
        1.4894159
      ]
    ]
  },
  "id": [
    "id",
    "id"
  ]
}

Response

Query results in Arrow IPC file format