Index

View as Markdown

An AI Search index — a searchable collection of vectors and metadata hosted on an AI Search endpoint. Indexes are children of endpoints; customers create, get, list, and delete them. The {index} segment of the resource name is the index's Unity Catalog table name.

Get an AI Search indexGET /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}List AI Search indexesGET /api/2.0/ai-search/{parent=workspaces/*/endpoints/*}/indexesCreate an AI Search indexPOST /api/2.0/ai-search/{parent=workspaces/*/endpoints/*}/indexesDelete an AI Search indexDELETE /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}Query an AI Search indexPOST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:queryRemove data from an AI Search indexPOST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:removeDataScan an AI Search indexPOST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:scanSynchronize an AI Search indexPOST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:syncUpsert data into an AI Search indexPOST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:upsertData

Index object

An AI Search index — a searchable collection of vectors and metadata hosted on an AI Search endpoint. Indexes are children of endpoints; customers create, get, list, and delete them. The {index} segment of the resource name is the index's Unity Catalog table name.

namestringPublic PreviewIDImmutable

Name of the AI Search index. Server-assigned full resource path (workspaces/{workspace}/endpoints/{endpoint}/indexes/{index}) on output, where {index} is the index's Unity Catalog table name. On create, the user-supplied UC table name is conveyed via CreateIndexRequest.index_id; the server composes the full name and returns it on the response.

Example: main.default.docs_index

endpointstringPublic PreviewOutput only

Name of the endpoint associated with the index. Ignored on create — the endpoint is taken from CreateIndexRequest.parent; populated only on output.

Example: docs-endpoint

primary_keystringPublic PreviewImmutable

Primary key of the index. Set on create and immutable thereafter.

index_typestringPublic PreviewImmutable

Type of index. Required on create and immutable thereafter.

Values:

• DELTA_SYNC
• DIRECT_ACCESS

direct_access_index_specobjectPublic PreviewImmutable

Specification for a Direct Access index. Set when index_type is DIRECT_ACCESS.

Show child attributesHide child attributes

embedding_vector_columnsarray of objectPublic Preview

The columns that contain the embedding vectors.

Show child attributesHide child attributes

namestringPublic Preview

Name of the column.

embedding_dimensionint32Public Preview

Dimension of the embedding vector.

schema_jsonstringPublic Preview

The schema of the index in JSON format. Supported types are integer, long, float, double, boolean, string, date, timestamp. Supported types for vector columns: array<float>, array<double>.

embedding_source_columnsarray of objectPublic Preview

The columns that contain the embedding source.

Show child attributesHide child attributes

namestringPublic Preview

Name of the source column.

embedding_model_endpointstringPublic Preview

Name of the embedding model endpoint, used by default for both ingestion and querying.

model_endpoint_name_for_querystringPublic Preview

Name of the embedding model endpoint which, if specified, is used for querying (not ingestion).

delta_sync_index_specobjectPublic PreviewImmutable

Specification for a Delta Sync index. Set when index_type is DELTA_SYNC.

Show child attributesHide child attributes

source_tablestringPublic Preview

The full name of the source Delta table.

embedding_source_columnsarray of objectPublic Preview

The columns that contain the embedding source.

Show child attributesHide child attributes

namestringPublic Preview

Name of the source column.

embedding_model_endpointstringPublic Preview

Name of the embedding model endpoint, used by default for both ingestion and querying.

model_endpoint_name_for_querystringPublic Preview

Name of the embedding model endpoint which, if specified, is used for querying (not ingestion).

embedding_vector_columnsarray of objectPublic Preview

The columns that contain the embedding vectors.

Show child attributesHide child attributes

namestringPublic Preview

Name of the column.

embedding_dimensionint32Public Preview

Dimension of the embedding vector.

embedding_writeback_tablestringPublic Preview

[Optional] Name of the Delta table to sync the index contents and computed embeddings to.

columns_to_syncarray of stringPublic Preview

[Optional] Select the columns to sync with the index. If left blank, all columns from the source table are synced. The primary key column and embedding source or vector column are always synced.

pipeline_idstringPublic PreviewOutput only

The ID of the pipeline that is used to sync the index.

pipeline_typestringPublic Preview

Pipeline execution mode. Required on create — the backend rejects an unset value. Storage Optimized endpoints accept only TRIGGERED; Standard endpoints accept both. No explicit stage — a REQUIRED field staged below its service would be dropped from combined specs while remaining in required, tripping the OpenAPI required-vs-properties consistency check. The field inherits the service's launch stage.

Values:

• PIPELINE_TYPE_UNSPECIFIED
• TRIGGERED
• CONTINUOUS

statusobjectPublic PreviewOutput only

Current status of the index.

Show child attributesHide child attributes

messagestringPublic PreviewOutput only

Human-readable detail about the index's current state.

indexed_row_countint64Public PreviewOutput only

Number of rows indexed.

readybooleanPublic PreviewOutput only

Whether the index is ready for search.

index_urlstringPublic PreviewOutput only

Index API URL used to perform operations on the index.

creatorstringPublic PreviewOutput only

Creator of the index.

Example: john@example.com

index_subtypestringPublic PreviewImmutable

The subtype of the index. Set on create and immutable thereafter.

Values:

• VECTOR
• FULL_TEXT
• HYBRID

View as Markdown

The Index object

{
  "name": "main.default.docs_index",
  "endpoint": "docs-endpoint",
  "primary_key": "string",
  "index_type": "DELTA_SYNC",
  "direct_access_index_spec": {
    "embedding_vector_columns": [
      {}
    ],
    "schema_json": "string",
    "embedding_source_columns": [
      {}
    ]
  },
  "delta_sync_index_spec": {
    "source_table": "string",
    "embedding_source_columns": [
      {}
    ],
    "embedding_vector_columns": [
      {}
    ],
    "embedding_writeback_table": "string",
    "columns_to_sync": [
      "string"
    ],
    "pipeline_id": "string",
    "pipeline_type": "TRIGGERED"
  },
  "status": {
    "message": "string",
    "indexed_row_count": 0,
    "ready": true,
    "index_url": "string"
  },
  "creator": "john@example.com",
  "index_subtype": "VECTOR"
}

Get an AI Search index Public Preview

GET /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}

Get details for a single AI Search index.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

Response

Returns the Index object.

View as Markdown

Response

{
  "name": "main.default.docs_index",
  "endpoint": "docs-endpoint",
  "primary_key": "string",
  "index_type": "DELTA_SYNC",
  "direct_access_index_spec": {
    "embedding_vector_columns": [
      {}
    ],
    "schema_json": "string",
    "embedding_source_columns": [
      {}
    ]
  },
  "delta_sync_index_spec": {
    "source_table": "string",
    "embedding_source_columns": [
      {}
    ],
    "embedding_vector_columns": [
      {}
    ],
    "embedding_writeback_table": "string",
    "columns_to_sync": [
      "string"
    ],
    "pipeline_id": "string",
    "pipeline_type": "TRIGGERED"
  },
  "status": {
    "message": "string",
    "indexed_row_count": 0,
    "ready": true,
    "index_url": "string"
  },
  "creator": "john@example.com",
  "index_subtype": "VECTOR"
}

List AI Search indexes Public Preview

GET /api/2.0/ai-search/{parent=workspaces/*/endpoints/*}/indexes

List AI Search indexes on an endpoint.

API scopes: ai-search

Parameters

parentstringRequiredpath

The Endpoint that owns this collection of indexes. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}

page_sizeint32query

Best-effort upper bound on the number of results to return. Honored as an upper bound by the shim: page_size only narrows the legacy backend's response, never widens it, so the practical cap is min(page_size, legacy_fixed_page_size).

page_tokenstringquery

Page token from a previous response. If not provided, returns the first page.

Response

Returns a list of Index objects.

View as Markdown

Response

{
  "indexes": [
    {
      "name": "main.default.docs_index",
      "endpoint": "docs-endpoint",
      "primary_key": "string",
      "index_type": "DELTA_SYNC",
      "direct_access_index_spec": {},
      "delta_sync_index_spec": {},
      "status": {},
      "creator": "john@example.com",
      "index_subtype": "VECTOR"
    }
  ],
  "next_page_token": "string"
}

Create an AI Search index Public Preview

POST /api/2.0/ai-search/{parent=workspaces/*/endpoints/*}/indexes

Create a new AI Search index.

API scopes: ai-search

Parameters

parentstringRequiredpath

The Endpoint where this Index will be created. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}

index_idstringquery

The user-supplied Unity Catalog table name for the Index, per AIP-133. The server composes the full Index.name as {parent}/indexes/{index_id}. AIP-133 does not list index_id as a fields-may-be-required entry, so we annotate it OPTIONAL on the wire; the server still rejects empty values with INVALID_PARAMETER_VALUE.

Request body

The Index resource to create. Fields other than index.name carry the desired configuration; index.name is server-assigned from parent and index_id.

namestringIDImmutable

Name of the AI Search index. Server-assigned full resource path (workspaces/{workspace}/endpoints/{endpoint}/indexes/{index}) on output, where {index} is the index's Unity Catalog table name. On create, the user-supplied UC table name is conveyed via CreateIndexRequest.index_id; the server composes the full name and returns it on the response.

Example: main.default.docs_index

primary_keystringRequiredImmutable

Primary key of the index. Set on create and immutable thereafter.

index_typestringRequiredImmutable

Type of index. Required on create and immutable thereafter.

Values:

• DELTA_SYNC
• DIRECT_ACCESS

direct_access_index_specobjectImmutable

Specification for a Direct Access index. Set when index_type is DIRECT_ACCESS.

Show child attributesHide child attributes

embedding_vector_columnsarray of object

The columns that contain the embedding vectors.

Show child attributesHide child attributes

namestring

Name of the column.

embedding_dimensionint32

Dimension of the embedding vector.

schema_jsonstring

The schema of the index in JSON format. Supported types are integer, long, float, double, boolean, string, date, timestamp. Supported types for vector columns: array<float>, array<double>.

embedding_source_columnsarray of object

The columns that contain the embedding source.

Show child attributesHide child attributes

namestring

Name of the source column.

embedding_model_endpointstring

Name of the embedding model endpoint, used by default for both ingestion and querying.

model_endpoint_name_for_querystring

Name of the embedding model endpoint which, if specified, is used for querying (not ingestion).

delta_sync_index_specobjectImmutable

Specification for a Delta Sync index. Set when index_type is DELTA_SYNC.

Show child attributesHide child attributes

source_tablestring

The full name of the source Delta table.

embedding_source_columnsarray of object

The columns that contain the embedding source.

Show child attributesHide child attributes

namestring

Name of the source column.

embedding_model_endpointstring

Name of the embedding model endpoint, used by default for both ingestion and querying.

model_endpoint_name_for_querystring

Name of the embedding model endpoint which, if specified, is used for querying (not ingestion).

embedding_vector_columnsarray of object

The columns that contain the embedding vectors.

Show child attributesHide child attributes

namestring

Name of the column.

embedding_dimensionint32

Dimension of the embedding vector.

embedding_writeback_tablestring

[Optional] Name of the Delta table to sync the index contents and computed embeddings to.

columns_to_syncarray of string

[Optional] Select the columns to sync with the index. If left blank, all columns from the source table are synced. The primary key column and embedding source or vector column are always synced.

pipeline_typestringRequired

Pipeline execution mode. Required on create — the backend rejects an unset value. Storage Optimized endpoints accept only TRIGGERED; Standard endpoints accept both. No explicit stage — a REQUIRED field staged below its service would be dropped from combined specs while remaining in required, tripping the OpenAPI required-vs-properties consistency check. The field inherits the service's launch stage.

Values:

• PIPELINE_TYPE_UNSPECIFIED
• TRIGGERED
• CONTINUOUS

index_subtypestringImmutable

The subtype of the index. Set on create and immutable thereafter.

Values:

• VECTOR
• FULL_TEXT
• HYBRID

Response

Returns the Index object.

View as Markdown

Request

{
  "name": "main.default.docs_index",
  "primary_key": "string",
  "index_type": "DELTA_SYNC",
  "direct_access_index_spec": {
    "embedding_vector_columns": [
      {}
    ],
    "schema_json": "string",
    "embedding_source_columns": [
      {}
    ]
  },
  "delta_sync_index_spec": {
    "source_table": "string",
    "embedding_source_columns": [
      {}
    ],
    "embedding_vector_columns": [
      {}
    ],
    "embedding_writeback_table": "string",
    "columns_to_sync": [
      "string"
    ],
    "pipeline_type": "TRIGGERED"
  },
  "index_subtype": "VECTOR"
}

Response

{
  "name": "main.default.docs_index",
  "endpoint": "docs-endpoint",
  "primary_key": "string",
  "index_type": "DELTA_SYNC",
  "direct_access_index_spec": {
    "embedding_vector_columns": [
      {}
    ],
    "schema_json": "string",
    "embedding_source_columns": [
      {}
    ]
  },
  "delta_sync_index_spec": {
    "source_table": "string",
    "embedding_source_columns": [
      {}
    ],
    "embedding_vector_columns": [
      {}
    ],
    "embedding_writeback_table": "string",
    "columns_to_sync": [
      "string"
    ],
    "pipeline_id": "string",
    "pipeline_type": "TRIGGERED"
  },
  "status": {
    "message": "string",
    "indexed_row_count": 0,
    "ready": true,
    "index_url": "string"
  },
  "creator": "john@example.com",
  "index_subtype": "VECTOR"
}

Delete an AI Search index Public Preview

DELETE /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}

Delete an AI Search index.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index to delete. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

View as Markdown

Response

{}

Query an AI Search index Public Preview

POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:query

Query (search) an AI Search index. Read-only, so a read-scoped token may invoke it.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index to query. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

Request body

columnsarray of stringRequired

Column names to include in each result row.

query_vectorarray of floatdouble

Query vector. Required for Direct Access indexes and Delta Sync indexes with self-managed vectors.

query_textstring

Query text. Required for Delta Sync indexes that compute embeddings from a model endpoint.

filters_jsonstring

JSON string describing query filters (e.g. {"id >": 5}).

score_thresholdfloatdouble

Score threshold for the approximate nearest-neighbor search. Defaults to 0.0.

query_typestring

Query type: ANN, HYBRID, or FULL_TEXT. Defaults to ANN.

columns_to_rerankarray of string

Columns whose values are sent to the reranker.

rerankerobject

If set, results are reranked before being returned.

Show child attributesHide child attributes

modelstring

Reranker identifier: "databricks_reranker" for the base model, or a Model Serving endpoint name when model_type is MODEL_TYPE_FINETUNED.

parametersobject

Parameters controlling reranking.

Show child attributesHide child attributes

columns_to_rerankarray of string

Columns whose values are concatenated and sent to the reranker.

model_typestring

Discriminator for how model is interpreted.

Values:

• MODEL_TYPE_UNSPECIFIED
• MODEL_TYPE_BASE
• MODEL_TYPE_FINETUNED

query_columnsarray of string

Text columns to search for query_text. When empty, all text columns are searched.

sort_columnsarray of string

Sort clauses, e.g. ["rating DESC", "price ASC"]. Overrides relevance ordering.

facetsarray of string

Facets to compute over the matched results (e.g. "category TOP 5").

max_resultsint32

Maximum number of results to return (the legacy num_results). Defaults to 10. Prefer page_size; when both are set, page_size takes precedence.

Response

manifestobjectOutput only

Metadata describing the result columns.

Show child attributesHide child attributes

column_countint32Output only

Number of columns in the result set.

columnsarray of objectOutput only

Information about each column in the result set.

Show child attributesHide child attributes

namestringOutput only

Name of the column.

type_textstringOutput only

Data type of the column (e.g., "string", "int", "array<float>").

facet_column_countint32Output only

Number of columns in the facet result.

facet_columnsarray of objectOutput only

Information about each facet column.

Show child attributesHide child attributes

namestringOutput only

Name of the column.

type_textstringOutput only

Data type of the column (e.g., "string", "int", "array<float>").

resultobjectOutput only

The matched result rows.

Show child attributesHide child attributes

row_countint32Output only

Number of rows in the result set.

data_arrayarray of array of objectOutput only

Result rows; each row is a list of column values aligned with the manifest columns.

facet_resultobjectOutput only

Facet aggregation rows, when facets were requested.

Show child attributesHide child attributes

facet_row_countint32Output only

Number of facet rows returned.

facet_arrayarray of array of objectOutput only

Facet rows; each row is [facet_column_name, value_or_range, count].

View as Markdown

Request

{
  "columns": [
    "string"
  ],
  "query_vector": [
    0
  ],
  "query_text": "string",
  "filters_json": "string",
  "score_threshold": 0,
  "query_type": "string",
  "columns_to_rerank": [
    "string"
  ],
  "reranker": {
    "model": "string",
    "parameters": {},
    "model_type": "MODEL_TYPE_BASE"
  },
  "query_columns": [
    "string"
  ],
  "sort_columns": [
    "string"
  ],
  "facets": [
    "string"
  ],
  "max_results": 0
}

Response

{
  "manifest": {
    "column_count": 0,
    "columns": [
      {}
    ],
    "facet_column_count": 0,
    "facet_columns": [
      {}
    ]
  },
  "result": {
    "row_count": 0,
    "data_array": [
      []
    ]
  },
  "facet_result": {
    "facet_row_count": 0,
    "facet_array": [
      []
    ]
  }
}

Remove data from an AI Search index Public Preview

POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:removeData

Remove rows by primary key from a Direct Access AI Search index.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index. Must be a Direct Access index. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

Request body

primary_keysarray of stringRequired

Primary keys of the rows to remove.

Response

statusstringOutput only

Overall status of the delete.

Values:

• SUCCESS
• PARTIAL_SUCCESS
• FAILURE

resultobjectOutput only

Per-row outcome of the delete.

Show child attributesHide child attributes

success_row_countint64Output only

Count of rows processed successfully.

failed_primary_keysarray of stringOutput only

Primary keys of rows that failed to process.

View as Markdown

Request

{
  "primary_keys": [
    "string"
  ]
}

Response

{
  "status": "SUCCESS",
  "result": {
    "success_row_count": 0,
    "failed_primary_keys": [
      "string"
    ]
  }
}

Scan an AI Search index Public Preview

POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:scan

Scan (paginate over) the rows of an AI Search index.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index to scan. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

Request body

page_sizeint32

Maximum number of rows to return in this page.

page_tokenstring

Page token from a previous response; if unset, scanning starts from the beginning.

Response

dataarray of objectOutput only

The rows in this page, each a struct of column name to value.

next_page_tokenstringOutput only

Token for the next page; empty when the scan is exhausted.

View as Markdown

Request

{
  "page_size": 0,
  "page_token": "string"
}

Response

{
  "data": [
    {}
  ],
  "next_page_token": "string"
}

Synchronize an AI Search index Public Preview

POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:sync

Synchronize a Delta Sync AI Search index with its source Delta table. Applies only to Delta Sync indexes; Direct Access indexes are written via the data-plane upsert path.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index to synchronize. Must be a Delta Sync index. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

View as Markdown

Response

{}

Upsert data into an AI Search index Public Preview

POST /api/2.0/ai-search/{name=workspaces/*/endpoints/*/indexes/*}:upsertData

Upsert rows into a Direct Access AI Search index.

API scopes: ai-search

Parameters

namestringRequiredpath

Full resource name of the index. Must be a Direct Access index. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}/indexes/{index_id}

Request body

inputs_jsonstringRequired

JSON document describing the rows to upsert.

Response

statusstringOutput only

Overall status of the upsert.

Values:

• SUCCESS
• PARTIAL_SUCCESS
• FAILURE

resultobjectOutput only

Per-row outcome of the upsert.

Show child attributesHide child attributes

success_row_countint64Output only

Count of rows processed successfully.

failed_primary_keysarray of stringOutput only

Primary keys of rows that failed to process.

View as Markdown

Request

{
  "inputs_json": "string"
}

Response

{
  "status": "SUCCESS",
  "result": {
    "success_row_count": 0,
    "failed_primary_keys": [
      "string"
    ]
  }
}