LAlance-format
Table
Data

Analyze query execution plan

Changed on

Analyze the query execution plan for a query against table id. Returns detailed statistics and analysis of the query execution plan.

REST NAMESPACE ONLY REST namespace returns the response as a plain string instead of the AnalyzeTableQueryPlanResponse JSON object.

post/v1/table/{id}/analyze_plan

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 execution plan analysis

string required

Human-readable query execution plan analysis

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