# Query an AI Search index

Launch stage: Public Preview

`POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:query`

Query (search) an AI Search index. Read-only, so a read-scoped token may invoke it.

API scopes: ai-search

## Path parameters

- `name` (string, required)
  Full resource name of the index to query.
   Format: `workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}`

## Request body

- `columns` (array of string, required)
  Column names to include in each result row.
- `query_vector` (array of float, optional)
  Query vector. Required for Direct Access indexes and Delta Sync indexes with self-managed
   vectors.
- `query_text` (string, optional)
  Query text. Required for Delta Sync indexes that compute embeddings from a model endpoint.
- `filters_json` (string, optional)
  JSON string describing query filters (e.g. `{"id >": 5}`).
- `score_threshold` (float, optional)
  Score threshold for the approximate nearest-neighbor search. Defaults to 0.0.
- `query_type` (string, optional)
  Query type: `ANN`, `HYBRID`, or `FULL_TEXT`. Defaults to `ANN`.
- `columns_to_rerank` (array of string, optional)
  Columns whose values are sent to the reranker.
- `reranker` (object, optional)
  If set, results are reranked before being returned.
  - `model` (string, optional)
    Reranker identifier: "databricks_reranker" for the base model, or a Model Serving
     endpoint name when `model_type` is MODEL_TYPE_FINETUNED.
  - `parameters` (object, optional)
    Parameters controlling reranking.
    - `columns_to_rerank` (array of string, optional)
      Columns whose values are concatenated and sent to the reranker.
  - `model_type` (string, optional)
    Discriminator for how `model` is interpreted.
    Possible values:
    - `MODEL_TYPE_UNSPECIFIED`
    - `MODEL_TYPE_BASE`
    - `MODEL_TYPE_FINETUNED`
- `query_columns` (array of string, optional)
  Text columns to search for `query_text`. When empty, all text columns are searched.
- `sort_columns` (array of string, optional)
  Sort clauses, e.g. `["rating DESC", "price ASC"]`. Overrides relevance ordering.
- `facets` (array of string, optional)
  Facets to compute over the matched results (e.g. `"category TOP 5"`).
- `max_results` (int32, optional)
  Maximum number of results to return (the legacy `num_results`). Defaults to 10.

## Returns

- `manifest` (object, optional, Output only)
  Metadata describing the result columns.
  - `column_count` (int32, optional, Output only)
    Number of columns in the result set.
  - `columns` (array of object, optional, Output only)
    Information about each column in the result set.
    - `name` (string, optional, Output only)
      Name of the column.
    - `type_text` (string, optional, Output only)
      Data type of the column (e.g., "string", "int", "array<float>").
  - `facet_column_count` (int32, optional, Output only)
    Number of columns in the facet result.
  - `facet_columns` (array of object, optional, Output only)
    Information about each facet column.
    - `name` (string, optional, Output only)
      Name of the column.
    - `type_text` (string, optional, Output only)
      Data type of the column (e.g., "string", "int", "array<float>").
- `result` (object, optional, Output only)
  The matched result rows.
  - `row_count` (int32, optional, Output only)
    Number of rows in the result set.
  - `data_array` (array of array of object, optional, Output only)
    Result rows; each row is a list of column values aligned with the manifest columns.
- `facet_result` (object, optional, Output only)
  Facet aggregation rows, when facets were requested.
  - `facet_row_count` (int32, optional, Output only)
    Number of facet rows returned.
  - `facet_array` (array of array of object, optional, Output only)
    Facet rows; each row is `[facet_column_name, value_or_range, count]`.

## Response

```json
{
  "manifest": {
    "column_count": 0,
    "columns": [
      {}
    ],
    "facet_column_count": 0,
    "facet_columns": [
      {}
    ]
  },
  "result": {
    "row_count": 0,
    "data_array": [
      []
    ]
  },
  "facet_result": {
    "facet_row_count": 0,
    "facet_array": [
      []
    ]
  }
}
```