# Query Vector Index

Launch stage: GA

`POST /api/2.0/vector-search/indexes/{name}/query`

Query the specified vector index.

API scopes: vector-search

## Path parameters

- `name` (string, optional)
  Name of the vector index to query.

## Request body

- `num_results` (int32, optional)
  Number of results to return. Defaults to 10.
- `columns` (array of string, optional)
  List of column names to include in the response.
- `filters_json` (string, optional)
  JSON string representing query filters.
  
   Example filters:
  
   - `{"id <": 5}`: Filter for id less than 5.
   - `{"id >": 5}`: Filter for id greater than 5.
   - `{"id <=": 5}`: Filter for id less than equal to 5.
   - `{"id >=": 5}`: Filter for id greater than equal to 5.
   - `{"id": 5}`: Filter for id equal to 5.
- `query_vector` (array of float, optional)
  Query vector. Required for Direct Vector Access Index and Delta Sync Index using self-managed vectors.
- `query_text` (string, optional)
  Query text. Required for Delta Sync Index using model endpoint.
- `score_threshold` (float, optional)
  Threshold for the approximate nearest neighbor search. Defaults to 0.0.
- `query_type` (string, optional)
  The query type to use. Choices are `ANN` and `HYBRID` and `FULL_TEXT`. Defaults to `ANN`.
- `reranker` (object, optional)
  If set, the top 50 results are reranked with the Databricks Reranker model before returning the `num_results` results to the user.
   The setting `columns_to_rerank` selects which columns are used for reranking. For each datapoint, the columns selected are concatenated before
   being sent to the reranking model. See https://docs.databricks.com/aws/en/vector-search/query-vector-search#rerank for more information.
  - `model` (string, optional)
    Reranker identifier:
      - When model_type=BASE/UNSPECIFIED: must be "databricks_reranker".
      - When model_type=FINETUNED: the Model Serving endpoint name hosting a finetuned reranker.
  - `parameters` (object, optional)
    Parameters that control how the reranker processes the query results.
    - `columns_to_rerank` (array of string, optional)
- `query_columns` (array of string, optional, Beta)
  Text columns to search for `query_text`. When empty, all text columns are searched.
- `sort_columns` (array of string, optional, Beta)
  Sort results by column values instead of the default relevance ordering.
   Each clause has the form `"<column> ASC"` or `"<column> DESC"`, for example
   `["rating DESC", "price ASC"]`.
- `facets` (array of string, optional, Beta)
  Facets to compute over the matched results. Each entry has one of these forms:
     `"<column>"`                         - top 10 distinct values by count
     `"<column> TOP <n>"`                 - top n distinct values, where n > 0
     `"<column> BUCKETS [[from,to],...]"` - inclusive numeric ranges
   `TOP` and `BUCKETS` are case-insensitive. A column may appear at most once.

## Returns

- `manifest` (object, optional)
  Metadata about the result set.
  - `column_count` (int32, optional)
    Number of columns in the result set.
  - `columns` (array of object, optional)
    Information about each column in the result set.
    - `name` (string, optional)
      Name of the column.
    - `type_text` (string, optional)
      Data type of the column (e.g., "string", "int", "array<float>")
  - `facet_column_count` (int32, optional, Beta)
    Number of columns in `facet_result`.
  - `facet_columns` (array of object, optional, Beta)
    Information about each column in `facet_result`.
    - `name` (string, optional)
      Name of the column.
    - `type_text` (string, optional)
      Data type of the column (e.g., "string", "int", "array<float>")
- `result` (object, optional)
  Data returned in the query result.
  - `row_count` (int32, optional)
    Number of rows in the result set.
  - `data_array` (array of array of object, optional)
    Data rows returned in the query.
- `next_page_token` (string, optional)
  [Optional] Token that can be used in `QueryVectorIndexNextPage` API to get next page of results.
   If more than 1000 results satisfy the query, they are returned in groups of 1000.
   Empty value means no more results. The maximum number of results that can be returned is 10,000.
- `facet_result` (object, optional, Beta)
  Facet aggregation rows returned by a query.
  - `facet_row_count` (int32, optional, Beta)
    Number of facet rows returned.
  - `facet_array` (array of array of object, optional, Beta)
    Facet rows. Each row is `[facet_column_name, value_or_range, count]`.

## Request

### Query using multiple filters

```json
{
  "columns": [
    "id",
    "age",
    "text"
  ],
  "filters_json": "{\"id\": 5, \"age >=\": 18}",
  "num_results": 10,
  "query_vector": [
    1,
    2,
    3
  ]
}
```

### Query using single filter

```json
{
  "columns": [
    "id",
    "text"
  ],
  "filters_json": "{\"id\": 5}",
  "num_results": 10,
  "query_vector": [
    1,
    2,
    3
  ]
}
```

### Query using text

```json
{
  "columns": [
    "id"
  ],
  "num_results": 20,
  "query_text": "Databricks AI Search"
}
```

### Query using vector

```json
{
  "columns": [
    "id",
    "text"
  ],
  "num_results": 10,
  "query_vector": [
    1,
    2,
    3
  ]
}
```

## Response

### Successful response for query operation.

```json
{
  "manifest": {
    "column_count": 3,
    "columns": [
      {
        "name": "id"
      },
      {
        "name": "text"
      },
      {
        "name": "text_vector"
      }
    ]
  },
  "next_page_token": "dummy-next-page-token",
  "result": {
    "data_array": [
      [
        "1",
        "Databricks AI Search",
        [
          1,
          2,
          3
        ]
      ]
    ],
    "row_count": 1
  }
}
```