v52

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

Table

Data

Get query execution plan explanation

Get the query execution plan for a query against table id. Returns a human-readable explanation of how the query will be executed.

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

post/v1/table/{id}/explain_plan

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:ExplainTableQueryPlanRequest: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.

verboseboolean

Whether to return verbose explanation

Example request

{
  "identity": {
    "api_key": "api_key",
    "auth_token": "auth_token"
  },
  "query": {
    "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"
    ]
  },
  "context": {
    "key": "context"
  },
  "id": [
    "id",
    "id"
  ],
  "branch": "branch",
  "verbose": false
}

Response

Query execution plan explanation

string required

Human-readable query execution plan