`ai_search` function

Applies to: Databricks SQL Databricks Runtime

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

The ai_search() function retrieves information from one or more AI Search indexes. Given a natural-language query and indexes configured as knowledge sources, the function generates optimized search queries, retrieves and deduplicates results across sources, reranks them by relevance, and returns the most relevant documents. By default, it also synthesizes a grounded natural-language answer over the retrieved documents.

Use ai_search to enrich operational data with relevant context at scale, build batch retrieval-augmented generation (RAG) pipelines, or expose retrieval as a tool to a compound AI system — all from a single SQL function call.

Requirements

Databricks Runtime 18.2 or above.
One or more AI Search indexes to use as knowledge sources.
If you are using Serverless compute, the serverless environment version must be set to 3 or above, as this enables features like VARIANT.
The ai_search function is available using Databricks notebooks, SQL editor, Databricks workflows, jobs, or Spark Declarative Pipelines on Lakeflow.

Syntax

ai_search(query, knowledge_sources [, instructions] [, options])

Arguments

query: A STRING or VARIANT expression. The natural-language search query. VARIANT input, such as the output of another AI function, is serialized to a JSON string internally.
knowledge_sources: A VARIANT or STRING expression containing a JSON array of knowledge source configurations to search. See Knowledge source configuration. You can specify up to 10 knowledge sources.
instructions: An optional STRING expression of up to 4,000 characters. Natural-language instructions that guide query generation, metadata filter generation, and reranking. For example, 'Prefer official documentation over internal articles when both cover the same topic.'
options: An optional MAP<STRING, STRING>. Supported keys:
- 'version': The function version to use.
- 'generate_answer': 'true' (default) or 'false'. When 'true', the function synthesizes a grounded natural-language answer from the retrieved documents and returns it in the answer field. Set to 'false' to return documents only.

Knowledge source configuration

The knowledge_sources argument is a JSON array. Each element is a {type, config} envelope. The type field identifies how ai_search connects to the source and is separate from the customer-facing resource name. For an AI Search index, set type to the literal vector_search. The config field contains the source-specific configuration.

Key	Required	Description
`type`	Yes	The knowledge source type. Currently, only `vector_search` is supported.
`config`	Yes	An object containing the source-specific configuration. For `vector_search`, see AI Search index configuration.

Key	Required	Description
`type`	Yes	The knowledge source type. Currently, only `vector_search` is supported.
`config`	Yes	An object containing the source-specific configuration. For `vector_search`, see AI Search index configuration.

AI Search index configuration

For an AI Search index with type set to vector_search, config accepts the following keys:

Key	Required	Description
`index_name`	Yes	The Unity Catalog three-level name of the AI Search index, for example `catalog.schema.my_index`.
`text_col`	Yes	The column in the index that contains the document text returned as `page_content`.
`doc_uri_col`	Yes	The column in the index that contains the document URI returned as `doc_uri`.
`filter_columns`	No	A comma-separated string or JSON array of columns available for metadata filtering. When omitted, the list is derived from the index schema, excluding reserved, text, and document URI columns.

Key	Required	Description
`index_name`	Yes	The Unity Catalog three-level name of the AI Search index, for example `catalog.schema.my_index`.
`text_col`	Yes	The column in the index that contains the document text returned as `page_content`.
`doc_uri_col`	Yes	The column in the index that contains the document URI returned as `doc_uri`.
`filter_columns`	No	A comma-separated string or JSON array of columns available for metadata filtering. When omitted, the list is derived from the index schema, excluding reserved, text, and document URI columns.

The following example configures one AI Search index as a knowledge source:

JSON
[
  {
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }
]

To build an AI Search index from raw documents, use ai_parse_document and ai_prep_search to create search-ready chunks in a Delta table. Then create an AI Search index from that table. After the index is online, use its three-level name as index_name.

Returns

A VARIANT with the following schema:

JSON
{
  "document": [
    {
      "page_content": STRING,  // Text content of the retrieved chunk
      "doc_uri": STRING,       // URI of the source document
      "metadata": MAP          // Additional metadata from the index
    }
  ],
  "answer": STRING             // Grounded answer synthesized from the retrieved
                               // documents, or null
}

Field	Type	Description
`document`	`ARRAY`	Array of retrieved documents, ordered by relevance.
`document[].page_content`	`STRING`	Text content of the retrieved chunk.
`document[].doc_uri`	`STRING`	URI of the source document.
`document[].metadata`	`MAP`	Additional metadata from the index.
`answer`	`STRING`	A grounded natural-language answer synthesized from the retrieved documents. `null` when answer generation is disabled or when no documents are retrieved.

Field	Type	Description
`document`	`ARRAY`	Array of retrieved documents, ordered by relevance.
`document[].page_content`	`STRING`	Text content of the retrieved chunk.
`document[].doc_uri`	`STRING`	URI of the source document.
`document[].metadata`	`MAP`	Additional metadata from the index.
`answer`	`STRING`	A grounded natural-language answer synthesized from the retrieved documents. `null` when answer generation is disabled or when no documents are retrieved.

Examples

Basic search

The following example searches one AI Search index and returns ranked documents and a grounded answer:

SQL
SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }]')
) AS result;

Multi-source search with instructions

The following example searches two AI Search indexes and uses instructions to steer query generation and reranking:

SQL
SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.internal_kb", "text_col": "body", "doc_uri_col": "source_uri"}
    }
  ]'),
  'Focus on firewall rules and VPC/VNet configuration. Prefer official documentation over internal articles when both cover the same topic.'
) AS result;

Enrich a table with retrieval and a generated answer

The following example enriches each support ticket with relevant documentation and a suggested resolution. Because answer generation is on by default, the suggested resolution is available directly in the answer field — no separate generation step is required.

SQL
SELECT
  ticket_id,
  customer_description,
  ai_search(
    customer_description,
    PARSE_JSON('[{
      "type": "vector_search",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]'),
    'Find product documentation, known issues, and troubleshooting guides relevant to this support ticket.'
  ):answer::STRING AS suggested_resolution
FROM support.tickets.open_tickets;

To control the output format or use a specific model, set 'generate_answer' to 'false' and chain the retrieved documents into ai_query instead.

Limitations

ai_search currently supports AI Search indexes only. Set "type": "vector_search" for each knowledge source.
You can specify up to 10 knowledge sources per call.
The instructions argument is limited to 4,000 characters.

Requirements​

Syntax​

Arguments​

Knowledge source configuration​

AI Search index configuration​

Returns​

Examples​

Basic search​

Multi-source search with instructions​

Enrich a table with retrieval and a generated answer​

Limitations​

Related functions​