Add a vector search index resource to a Databricks app

Add vector search indexes as Databricks Apps resources to enable semantic search and similarity-based retrieval in your applications. Vector search indexes store and query high-dimensional vector embeddings, powering use cases like retrieval-augmented generation (RAG), semantic search, and recommendation systems.

Privilege requirements

To access a vector search index, the app's service principal must have the USE CATALOG privilege on the parent catalog, the USE SCHEMA privilege on the parent schema, and the SELECT privilege on the index. When you add the index resource, Databricks automatically grants these privileges to the app's service principal.

For this automatic granting to succeed, one of the following must be true for each privilege:

• For USE CATALOG: Either all account users have the USE CATALOG privilege on the catalog, or you have the MANAGE privilege on the catalog.
• For USE SCHEMA: Either all account users have the USE SCHEMA privilege on the schema, or you have the MANAGE privilege on the schema.
• For SELECT: Either all account users have the SELECT privilege on the index, or you have the MANAGE privilege on the index.

For more information about querying vector search indexes with these permissions, see How to query a vector search index.

See Unity Catalog privileges and securable objects.

Add a vector search index resource

Before you add a vector search index as a resource, review the app resource prerequisites.

1. When you create or edit an app, navigate to the Configure step.
2. In the App resources section, click + Add resource.
3. Select Vector search index as the resource type.
4. Choose a vector search index from the available indexes in your workspace. The index must already exist in Unity Catalog.
5. Select the permission level for your app:
   • Can select: Grants the app permission to query the vector search index for similarity searches. Corresponds to the SELECT privilege.
6. (Optional) Specify a custom resource key, which is how you reference the index in your app configuration. The default key is vector-search-index.

note

Vector search indexes are Unity Catalog tables with type TABLE_ONLINE_VECTOR_INDEX_REPLICA or TABLE_ONLINE_VECTOR_INDEX_DIRECT. When you select a vector search index, you're selecting a specially configured table that supports semantic search operations.

Environment variables

When you deploy an app with a vector search index resource, Databricks exposes the full three-level name through environment variables that you can reference using the valueFrom field.

Example configuration:

YAML

env:
  - name: VECTOR_SEARCH_INDEX
    valueFrom: vector-search-index # Use your custom resource key if different

Using the index in your application:

Python

import os
from databricks.sdk import WorkspaceClient

# Access the vector search index name
index_name = os.getenv("VECTOR_SEARCH_INDEX")

# Initialize workspace client
w = WorkspaceClient()

# Query the vector search index
results = w.vector_search_indexes.query_index(
    index_name=index_name,
    query_text="What is machine learning?",
    num_results=10
)

# Process results
for result in results.manifest.columns:
    print(f"Result: {result}")

For more information, see Use environment variables to access resources.

Remove a vector search index resource

When you remove a vector search index resource from an app, the app's service principal loses access to the index. The index itself remains unchanged and continues to be available for other users and applications that have appropriate permissions.

Best practices

Consider the following when you work with vector search index resources:

• Make sure the app's service principal has access to underlying data sources if the index references other tables.
• Monitor query performance and adjust index configuration or embedding models if response times degrade.
• Consider index refresh schedules to keep embeddings synchronized with source data.
• Use appropriate similarity metrics (cosine, euclidean, dot product) based on your embedding model.