Registry / vector-search / databricks-vectorsearch

databricks-vectorsearch

library0.75pypypi✓ verified 24d ago

The `databricks-vectorsearch` Python client library provides programmatic access to Databricks Vector Search, a serverless similarity search engine. It enables users to manage vector search endpoints and indexes, facilitating the creation of Retrieval Augmented Generation (RAG) applications. The library integrates seamlessly with the Databricks Data Intelligence Platform and Unity Catalog for data governance. Currently at version 0.67, it is actively developed with regular updates.

vector-search llm-agents database ai-ml

pip install databricks-vectorsearch

package ↗homepage ↗

INSTALL

IMPORT

SIG · DATABRICKS-VECTORS

databricks-vectorsearch

vector-searchpythonv0.75

Install

10.9s avg

Import

4252ms

Disk

117MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.75 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 5.240s · 116.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 10.9s · import 3.264s · 117MB

117MB installed

● package 117MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VectorSearchClient

✓ from databricks.vector_search.client import VectorSearchClient

Initializes the VectorSearchClient and performs a similarity search on an existing index. Ensure `DATABRICKS_WORKSPACE_URL` and `DATABRICKS_TOKEN` environment variables are set or replaced with actual values.

import os from databricks.vector_search.client import VectorSearchClient # Replace with your Databricks workspace URL and Personal Access Token workspace_url = os.environ.get("DATABRICKS_WORKSPACE_URL", "https://<your-workspace-url>.databricks.com") pat = os.environ.get("DATABRICKS_TOKEN", "") if not pat: print("Warning: DATABRICKS_TOKEN environment variable not set. This example may not work without authentication.") # Initialize the Vector Search Client client = VectorSearchClient(workspace_url=workspace_url, personal_access_token=pat) # Replace with your endpoint and index names endpoint_name = "<your-vector-search-endpoint>" index_name = "<your-catalog>.<your-schema>.<your-index-name>" try: # Get an existing index instance index = client.get_index(index_name=index_name) # Perform a similarity search query_text = "What is Databricks Vector Search?" results = index.similarity_search( query_text=query_text, num_results=2, columns=["text", "id"] # specify columns to return ) print(f"Similarity search results for '{query_text}':") for result in results.get('result', {}).get('data_array', []): print(f" ID: {result}, Text: {result[:100]}...") except Exception as e: print(f"An error occurred: {e}") print("Please ensure the Vector Search endpoint and index exist and your credentials are correct.")

Debug

Known issues

breakingIn Databricks Runtime 15.3 and above, the `vector_search()` SQL function's `query` argument was replaced by `query_text` or `query_vector`. Using `query` in newer runtimes will result in an error.

fix

Update your SQL queries to use `query_text` for text-based searches or `query_vector` for vector-based searches, depending on your index configuration.

affects: Databricks Runtime <=15.2 (for `query`), >=15.3 (for `query_text`/`query_vector`)

gotchaThe `VectorSearchIndex` class should not be instantiated directly. Instead, obtain an index instance using methods provided by the `VectorSearchClient` (e.g., `client.get_index()`).

fix

Always interact with index objects obtained via `VectorSearchClient` methods.

affects: All

gotchaFor production deployments, Databricks strongly recommends using Service Principals for authentication instead of Personal Access Tokens (PATs). Service Principals offer better security and can improve query performance.

fix

Configure your client with `service_principal_client_id` and `service_principal_client_secret` along with `azure_tenant_id` for Azure, or equivalent for other clouds, and enable service principal usage for vector search index ownership.

affects: All

gotchaRemoving the owner of a Vector Search Index can break associated Databricks Liquid (DLT) pipelines and other dependencies, requiring index recreation. Assigning a Service Principal as the index owner prevents this issue.

fix

When creating or modifying Vector Search Indexes, ensure a Service Principal is assigned as the owner.

affects: All

deprecatedThe `budget_policy_id` parameter for creating Vector Search endpoints and indexes has been deprecated. It has been replaced by `usage_policy_id`.

fix

Use the `usage_policy_id` parameter instead of `budget_policy_id` when creating or updating endpoints and indexes.

affects: All

Errors

Common errors & fixes

databricks.vector_search.exceptions.InvalidInputException: Please specify either personal access token or service principal client ID and secret.

The `VectorSearchClient` was initialized without providing necessary authentication credentials (personal access token or service principal details) in an environment where automatic credential detection is not available or fails, such as outside a Databricks notebook or in a deployed application.

fix

Explicitly provide authentication details to the `VectorSearchClient` during instantiation. For personal access token (PAT) authentication, include `workspace_url` and `personal_access_token`. For service principal authentication, include `workspace_url`, `service_principal_client_id`, and `service_principal_client_secret` (and `azure_tenant_id` for Azure Databricks).

Example (PAT):
```python
from databricks.vector_search.client import VectorSearchClient
client = VectorSearchClient(
    workspace_url="https://your-workspace.databricks.com",
    personal_access_token="dapi..."
)
```

Example (Service Principal):
```python
from databricks.vector_search.client import VectorSearchClient
client = VectorSearchClient(
    workspace_url="https://your-workspace.databricks.com",
    service_principal_client_id="your-client-id",
    service_principal_client_secret="your-client-secret"
)
```

b'{"error_code":"PERMISSION_DENIED","message":"Failed to call Model Serving endpoint: <endpoint-name>."}'

The service principal or user attempting to query the vector search index lacks the necessary 'CAN QUERY' permissions on the underlying embedding model serving endpoint specified in the error message.

fix

Ensure that the service principal or user identity making the request has 'CAN QUERY' permissions on the Databricks Model Serving endpoint that the vector search index relies on for embeddings. Verify permissions in the Databricks workspace's 'Serving' section for the specified endpoint.

TypeError: VectorSearchIndex.similarity_search() got an unexpected keyword argument 'query_type'

This error typically occurs when using `databricks-vectorsearch` through `langchain-community` (specifically in versions `> 0.2.9` for `langchain-community`) where the `query_type` parameter is passed to `similarity_search()`, but the method signature in the `databricks-vectorsearch` integration does not yet support it directly or expects a different parameter name.

fix

This issue is often a versioning conflict or an API change between `langchain-community` and `databricks-vectorsearch`. Try downgrading your `langchain-community` package to a compatible version (e.g., `<= 0.2.9`). Alternatively, if `query_type` is meant for hybrid search, check the `databricks-vectorsearch` or LangChain documentation for the correct parameter for hybrid or full-text searches. For `databricks-vectorsearch` directly, `query_type` is a parameter for the `vector_search()` SQL function or can be passed to the SDK's query method, but not necessarily directly to `similarity_search` from the `VectorSearchIndex` object in older versions of the LangChain integration.

Index creation failed: Failed to call Model Serving endpoint <endpoint-name>.

This error occurs during vector search index creation when the specified model serving endpoint is either inaccessible, unstable, or does not host a compatible text embedding model. For example, using a non-text embedding model for index creation will cause this.

fix

Verify that the model serving endpoint name is correct and the endpoint is in a 'Ready' state. Confirm that the model served by the endpoint is a supported text embedding model (e.g., GTE Large (En) or BGE Large (En)). You can check the endpoint's status and the model it serves in the Databricks UI under 'Serving' or 'Model Serving'.

ModuleNotFoundError: No module named 'databricks.vector_search'

The `databricks-vectorsearch` Python package has not been installed in the current Python environment or notebook cluster.

fix

Install the `databricks-vectorsearch` package using pip. In a Databricks notebook, use the magic command `%pip install databricks-vectorsearch` followed by `dbutils.library.restartPython()` to ensure the newly installed library is available.

Upgrade

Version history

0.75latest on PyPI · released Jun 10, 2026

Audit

Dependencies

deprecationrequiredInternal dependency for handling deprecated features.

mlflow-skinnyrequiredLikely for integration with MLflow for model serving or tracking.

protobufrequiredCommon dependency for data serialization.

requestsrequiredUsed for making HTTP requests to the Databricks Vector Search API.

Agent activity

55 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/databricks-vectorsearch/ ↗

homepagehttps://docs.databricks.com/en/generative-ai/vector-search.html ↗