Skip to main content
Last updated on

Query a vector search index

This article describes how to query a vector search index, including how to use filters and reranking.

For example notebooks illustrating how to create and query vector search endpoints and indexes, see Vector search example notebooks. For reference information, see the Python SDK reference.

Installation​

To use the vector search SDK, you must install it in your notebook. Use the following code to install the package:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

Then use the following command to import VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

For information about authentication, see Data protection and authentication.

How to query a vector search index​

You can only query the vector search index using the Python SDK, the REST API, or the SQL vector_search() AI function.

note

If the user querying the index is not the owner of the vector search index, the user must have the following UC privileges:

  • USE CATALOG on the catalog that contains the vector search index.
  • USE SCHEMA on the schema that contains the vector search index.
  • SELECT on the vector search index.

The default query type is ann (approximate nearest neighbor). To perform a hybrid keyword-similarity search, set the parameter query_type to hybrid. With hybrid search, all text metadata columns are included, and a maximum of 200 results are returned.

To use the reranker in a query, see Use the reranker in a query.

Beta

Full-text search is available as a beta feature. To perform a full-text search, set the parameter query_type to FULL_TEXT. With full-text search, you can retrieve up to 200 results based on keyword matching without using vector embeddings.

For details, see the Python SDK reference.

Python
# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

Use filters on queries​

A query can define filters based on any column in the Delta table. similarity_search returns only rows that match the specified filters.

The following table lists the supported filters.

Filter operator

Behavior

Examples

NOT

Standard: Negates the filter. The key must end with “NOT”. For example, “color NOT” with value “red” matches documents where the color is not red.

Storage-optimized: See != (bangeq sign) operator.

Standard: {"id NOT": 2} {“color NOT”: “red”}

Storage-optimized: "id != 2" "color != 'red'"

<

Standard: Checks if the field value is less than the filter value. The key must end with ” <”. For example, “price <” with value 200 matches documents where the price is less than 200.

Storage-optimized: See < (lt sign) operator.

Standard: {"id <": 200}

Storage-optimized: "id < 200"

<=

Standard: Checks if the field value is less than or equal to the filter value. The key must end with ” <=”. For example, “price <=” with value 200 matches documents where the price is less than or equal to 200.

Storage-optimized: See <= (lt eq sign) operator.

Standard: {"id <=": 200}

Storage-optimized: "id <= 200"

>

Standard: Checks if the field value is greater than the filter value. The key must end with ” >”. For example, “price >” with value 200 matches documents where the price is greater than 200.

Storage-optimized: See > (gt sign) operator.

Standard: {"id >": 200}

Storage-optimized: "id > 200"

>=

Standard: Checks if the field value is greater than or equal to the filter value. The key must end with ” >=”. For example, “price >=” with value 200 matches documents where the price is greater than or equal to 200.

Storage-optimized: See >= (gt eq sign) operator.

Standard: {"id >=": 200}

Storage-optimized: "id >= 200"

OR

Standard: Checks if the field value matches any of the filter values. The key must contain OR to separate multiple subkeys. For example, color1 OR color2 with value ["red", "blue"] matches documents where either color1 is red or color2 is blue.

Storage-optimized: See or operator.

Standard: {"color1 OR color2": ["red", "blue"]}

Storage-optimized: "color1 = 'red' OR color2 = 'blue'"

LIKE

Standard: Matches whitespace-separated tokens in a string. See the code examples below.

Storage-optimized: See like operator.

Standard: {"column LIKE": "hello"}

Storage-optimized: "column LIKE 'hello'"

No filter operator specified

Standard: Filter checks for an exact match. If multiple values are specified, it matches any of the values.

Storage-optimized: See = (eq sign) operator and in predicate.

Standard: {"id": 200} {"id": [200, 300]}

Storage-optimized: "id = 200" "id IN (200, 300)"

to_timestamp (storage-optimized endpoints only)

Storage-optimized: Filter on a timestamp. See to_timestamp function

Storage-optimized: "date > TO_TIMESTAMP('1995-01-01')"

See the following code examples:

Python
# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

Use the reranker in a query​

Preview

This feature is in Public Preview.

Agent performance depends on retrieving the most relevant information for a query. Reranking is a technique that improves retrieval quality by evaluating the retrieved documents to identify the ones that are semantically most relevant. Databricks has developed a research-based compound AI system to identify these documents. You can also specify columns containing metadata that you want the reranker to use for additional context as it assesses each document's relevance.

Reranking incurs a small latency delay but can significantly improve retrieval quality and agent performance. Databricks recommends trying out reranking for any RAG agent use case.

The examples in this section show how to use the vector search reranker. When you use the reranker, you set the columns to return (columns) and the metadata columns to use for reranking (columns_to_rerank) separately. num_results is the final number of results to return. This does not affect the number of results used for reranking.

The query debug message includes information about how long the reranking step took. For example:

Bash
'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

If the reranker call fails, that information is included in the debug message:

Bash
'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}
note

The order that columns are listed in columns_to_rerank is important. The reranking calculation takes the columns in the order they are listed, and considers only the first 2000 characters it finds.

Python
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()
Python
from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )