LAlance-format
Table
Data

Query a table

Changed on

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

Request

  • Base URL
    http://localhost:2333
  • Auth
    • OAuth 2
      Client credentials
      Token URL: /oauth/token
    • or HTTP bearer
    • or API key in header x-api-key

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

contextunknown
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

maximum_nprobesinteger

Maximum number of IVF partitions to search. When omitted, all partitions may be searched if needed.

minimum_nprobesinteger

Minimum number of IVF partitions to search before adaptive expansion.

nprobesinteger

Legacy exact number of IVF partitions to search. Ignored when minimum_nprobes or maximum_nprobes is provided.

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.4894159,
  "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,
  "maximum_nprobes": 1,
  "identity": {
    "api_key": "api_key",
    "auth_token": "auth_token"
  },
  "bypass_vector_index": true,
  "minimum_nprobes": 1,
  "nprobes": 0,
  "context": {
    "key": "context"
  },
  "vector": {
    "single_vector": [
      6.846853,
      6.846853
    ],
    "multi_vector": [
      [
        7.4577446,
        7.4577446
      ],
      [
        7.4577446,
        7.4577446
      ]
    ]
  },
  "id": [
    "id",
    "id"
  ]
}

Response

Query results in Arrow IPC file format

Changes

  • cb1671c5b63cRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

  • 591cd95574b0Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status