Skip to main content

Index

View as Markdown

VectorIndex object​

An AI Search index stores vectors and metadata on an endpoint and serves vector similarity, full-text and hybrid search queries over them. A Delta Sync index is kept in sync with a source table, with embeddings either computed by Databricks from a text column or supplied by you in a vector column; a Direct Vector Access index holds rows that you write through the upsert and delete data APIs. See https://docs.databricks.com/aws/en/ai-search/create-ai-search for how to choose between them.

namestring

Three-level Unity Catalog name of the index.

Example: main_catalog.docs.en_wiki_index

endpoint_namestring

Name of the endpoint that serves the index.

primary_keystring

Name of the column that uniquely identifies each row of the index.

index_typestring

Type of the index, which determines whether delta_sync_index_spec or direct_access_index_spec describes it.

Values:

  • DELTA_SYNC
  • DIRECT_ACCESS
direct_access_index_specobject

Specification of a Direct Vector Access index. Present only when index_type is DIRECT_ACCESS.

Show child attributesHide child attributes
embedding_vector_columnsarray of object

The column that holds the embedding vectors you write to the index. Exactly one column must be specified, and schema_json must declare it as array<float> or array<double>.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

schema_jsonstring

JSON object that maps each column name of the index to its type, serialized to a string. The primary key and the embedding vector column must be present. Supported types are integer, long, float, double, boolean, string, date, timestamp. Supported types for vector column: array<float>, array<double>.

embedding_source_columnsarray of object

Embedding source configuration used to embed query_text when the index is queried with text, naming the embedding model endpoint to use. The index stores the vectors you supply through upsert; this setting never computes embeddings for them.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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_specobject

Specification of a Delta Sync index. Present only when index_type is DELTA_SYNC.

Show child attributesHide child attributes
source_tablestring

Three-level Unity Catalog name of the source table that the index is synced from.

Example: main_catalog.docs.en_wiki

embedding_source_columnsarray of object

The source table column whose text Databricks embeds, together with the embedding model endpoint to use. Set this for an index with Databricks-managed embeddings. Exactly one of embedding_source_columns or embedding_vector_columns must be specified unless the index subtype is FULL_TEXT, and only one column is supported.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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 source table column that contains precomputed embedding vectors. Set this instead of embedding_source_columns for an index with self-managed embeddings.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

pipeline_typestring

Pipeline execution mode.

  • TRIGGERED: If the pipeline uses the triggered execution mode, the system stops processing after successfully refreshing the source table in the pipeline once, ensuring the table is updated based on the data available when the update started.
  • CONTINUOUS: If the pipeline uses continuous execution, the pipeline processes new data as it arrives in the source table to keep vector index fresh.

Values:

  • TRIGGERED
  • CONTINUOUS
pipeline_idstring

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

embedding_writeback_tablestring

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

columns_to_syncarray of string

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

columns_to_indexarray of string

[Optional] Alias for columns_to_sync. Select the columns to include in the vector index. If you leave this field blank, all columns from the source table are included. The primary key column and embedding source column or embedding vector column are always included. Only one of columns_to_sync or columns_to_index may be specified.

statusobject

Current status of the index, including whether it is ready to serve queries and how many rows it holds.

Show child attributesHide child attributes
detailed_statestring

Lifecycle and ingestion state. An online index can still have a failed update.

Values:

Show 15 possible values
  • PROVISIONING
  • PROVISIONING_ENDPOINT
  • PROVISIONING_INDEX
  • PROVISIONING_PIPELINE_RESOURCES
  • PROVISIONING_INITIAL_SNAPSHOT
  • ONLINE
  • ONLINE_CONTINUOUS_UPDATE
  • ONLINE_TRIGGERED_UPDATE
  • ONLINE_NO_PENDING_UPDATE
  • ONLINE_DIRECT_ACCESS
  • OFFLINE
  • OFFLINE_FAILED
  • ONLINE_PIPELINE_FAILED
  • ONLINE_UPDATING_PIPELINE_RESOURCES
  • DOWNLOADING
messagestring

Human-readable description of the current status.

indexed_row_countint64

Number of rows indexed

failed_statusobject

Failure details, when available, for OFFLINE_FAILED or ONLINE_PIPELINE_FAILED.

Show child attributesHide child attributes
error_messagestring

Error message, when available.

last_processed_commit_versionint64

Last source Delta table version fully processed while the index is still queryable.

last_processed_commit_timestampstring

[Standard endpoint] timestamp when the last processed commit was committed to the source table. [Storage Optimized endpoint] timestamp when the last processed commit was processed by the pipeline.

error_codestring

Error code associated with the error message, when available.

readyboolean

Whether the index can serve queries. This does not mean the latest update succeeded or that all source-table changes have been indexed; check detailed_state for update failures.

index_urlstring

Index API Url to be used to perform operations on the index

creatorstring

The user who created the index.

index_subtypestringBeta

Subtype of the index. A HYBRID index supports vector similarity, full-text and hybrid queries; a FULL_TEXT index has no embeddings and supports only full-text queries.

Values:

  • VECTOR
  • FULL_TEXT
  • HYBRID

Get an index GA​

GET /api/2.0/vector-search/indexes/{name}

Get an index.

API scopes: vector-search

Parameters​

namestringRequiredpath

Three-level Unity Catalog name of the index.

ensure_reranker_compatiblebooleanquery

If true, the URL returned for the index is guaranteed to be compatible with the reranker. Currently this means we return the CP URL regardless of how the index is being accessed. If not set or set to false, the URL may still be compatible with the reranker depending on what URL we return.

Response​

Returns the VectorIndex object.

List indexes GA​

GET /api/2.0/vector-search/indexes

List all indexes in the given endpoint.

API scopes: vector-search

Parameters​

endpoint_namestringRequiredquery

Name of the endpoint whose indexes to list.

page_tokenstringquery

Page token returned by a previous call, used to get the next page of results.

Response​

vector_indexesarray of object

Indexes served by the endpoint. Each entry is a summary without the index specification and status; use Get an index to retrieve them.

Show child attributesHide child attributes
namestring

Three-level Unity Catalog name of the index.

Example: main_catalog.docs.en_wiki_index

endpoint_namestring

Name of the endpoint that serves the index.

primary_keystring

Name of the column that uniquely identifies each row of the index.

index_typestring

Type of the index, which determines whether delta_sync_index_spec or direct_access_index_spec describes it.

Values:

  • DELTA_SYNC
  • DIRECT_ACCESS
direct_access_index_specobject

Specification of a Direct Vector Access index. Present only when index_type is DIRECT_ACCESS.

Show child attributesHide child attributes
embedding_vector_columnsarray of object

The column that holds the embedding vectors you write to the index. Exactly one column must be specified, and schema_json must declare it as array<float> or array<double>.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

schema_jsonstring

JSON object that maps each column name of the index to its type, serialized to a string. The primary key and the embedding vector column must be present. Supported types are integer, long, float, double, boolean, string, date, timestamp. Supported types for vector column: array<float>, array<double>.

embedding_source_columnsarray of object

Embedding source configuration used to embed query_text when the index is queried with text, naming the embedding model endpoint to use. The index stores the vectors you supply through upsert; this setting never computes embeddings for them.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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_specobject

Specification of a Delta Sync index. Present only when index_type is DELTA_SYNC.

Show child attributesHide child attributes
source_tablestring

Three-level Unity Catalog name of the source table that the index is synced from.

Example: main_catalog.docs.en_wiki

embedding_source_columnsarray of object

The source table column whose text Databricks embeds, together with the embedding model endpoint to use. Set this for an index with Databricks-managed embeddings. Exactly one of embedding_source_columns or embedding_vector_columns must be specified unless the index subtype is FULL_TEXT, and only one column is supported.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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 source table column that contains precomputed embedding vectors. Set this instead of embedding_source_columns for an index with self-managed embeddings.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

pipeline_typestring

Pipeline execution mode.

  • TRIGGERED: If the pipeline uses the triggered execution mode, the system stops processing after successfully refreshing the source table in the pipeline once, ensuring the table is updated based on the data available when the update started.
  • CONTINUOUS: If the pipeline uses continuous execution, the pipeline processes new data as it arrives in the source table to keep vector index fresh.

Values:

  • TRIGGERED
  • CONTINUOUS
pipeline_idstring

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

embedding_writeback_tablestring

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

columns_to_syncarray of string

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

columns_to_indexarray of string

[Optional] Alias for columns_to_sync. Select the columns to include in the vector index. If you leave this field blank, all columns from the source table are included. The primary key column and embedding source column or embedding vector column are always included. Only one of columns_to_sync or columns_to_index may be specified.

statusobject

Current status of the index, including whether it is ready to serve queries and how many rows it holds.

Show child attributesHide child attributes
detailed_statestring

Lifecycle and ingestion state. An online index can still have a failed update.

Values:

Show 15 possible values
  • PROVISIONING
  • PROVISIONING_ENDPOINT
  • PROVISIONING_INDEX
  • PROVISIONING_PIPELINE_RESOURCES
  • PROVISIONING_INITIAL_SNAPSHOT
  • ONLINE
  • ONLINE_CONTINUOUS_UPDATE
  • ONLINE_TRIGGERED_UPDATE
  • ONLINE_NO_PENDING_UPDATE
  • ONLINE_DIRECT_ACCESS
  • OFFLINE
  • OFFLINE_FAILED
  • ONLINE_PIPELINE_FAILED
  • ONLINE_UPDATING_PIPELINE_RESOURCES
  • DOWNLOADING
messagestring

Human-readable description of the current status.

indexed_row_countint64

Number of rows indexed

failed_statusobject

Failure details, when available, for OFFLINE_FAILED or ONLINE_PIPELINE_FAILED.

Show child attributesHide child attributes
error_messagestring

Error message, when available.

last_processed_commit_versionint64

Last source Delta table version fully processed while the index is still queryable.

last_processed_commit_timestampstring

[Standard endpoint] timestamp when the last processed commit was committed to the source table. [Storage Optimized endpoint] timestamp when the last processed commit was processed by the pipeline.

error_codestring

Error code associated with the error message, when available.

readyboolean

Whether the index can serve queries. This does not mean the latest update succeeded or that all source-table changes have been indexed; check detailed_state for update failures.

index_urlstring

Index API Url to be used to perform operations on the index

creatorstring

The user who created the index.

index_subtypestringBeta

Subtype of the index. A HYBRID index supports vector similarity, full-text and hybrid queries; a FULL_TEXT index has no embeddings and supports only full-text queries.

Values:

  • VECTOR
  • FULL_TEXT
  • HYBRID
next_page_tokenstring

A token that can be used to get the next page of results. If not present, there are no more results to show.

Create an index GA​

POST /api/2.0/vector-search/indexes

Create a new index on an endpoint. Creating a Delta Sync index also creates the pipeline that populates it from the source table; a Direct Vector Access index starts empty and is populated through Upsert data into an index.

API scopes: vector-search

Request body​

namestringRequired

Three-level Unity Catalog name of the index to create.

endpoint_namestringRequired

Name of the endpoint to be used for serving the index

primary_keystringRequired

Name of the column that uniquely identifies each row. For a Delta Sync index it is a column of the source table; for a Direct Vector Access index it must be declared in schema_json. It cannot be the embedding source or embedding vector column.

index_typestringRequired

Type of index to create, which determines which spec field is required.

Values:

  • DELTA_SYNC
  • DIRECT_ACCESS
direct_access_index_specobject

Specification for Direct Vector Access Index. Required if index_type is DIRECT_ACCESS.

Show child attributesHide child attributes
embedding_vector_columnsarray of object

The column that holds the embedding vectors you write to the index. Exactly one column must be specified, and schema_json must declare it as array<float> or array<double>.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

schema_jsonstring

JSON object that maps each column name of the index to its type, serialized to a string. The primary key and the embedding vector column must be present. Supported types are integer, long, float, double, boolean, string, date, timestamp. Supported types for vector column: array<float>, array<double>.

embedding_source_columnsarray of object

Embedding source configuration used to embed query_text when the index is queried with text, naming the embedding model endpoint to use. The index stores the vectors you supply through upsert; this setting never computes embeddings for them.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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_specobject

Specification for Delta Sync Index. Required if index_type is DELTA_SYNC.

Show child attributesHide child attributes
source_tablestring

Three-level Unity Catalog name of the source table that the index is synced from.

Example: main_catalog.docs.en_wiki

embedding_source_columnsarray of object

The source table column whose text Databricks embeds, together with the embedding model endpoint to use. Set this for an index with Databricks-managed embeddings. Exactly one of embedding_source_columns or embedding_vector_columns must be specified unless the index subtype is FULL_TEXT, and only one column is supported.

Show child attributesHide child attributes
namestring

Name of the column that contains the text to embed.

embedding_model_endpoint_namestring

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 source table column that contains precomputed embedding vectors. Set this instead of embedding_source_columns for an index with self-managed embeddings.

Show child attributesHide child attributes
namestring

Name of the column that contains the embedding vectors.

embedding_dimensionint32

Dimension of the embedding vector

pipeline_typestring

Pipeline execution mode.

  • TRIGGERED: If the pipeline uses the triggered execution mode, the system stops processing after successfully refreshing the source table in the pipeline once, ensuring the table is updated based on the data available when the update started.
  • CONTINUOUS: If the pipeline uses continuous execution, the pipeline processes new data as it arrives in the source table to keep vector index fresh.

Values:

  • TRIGGERED
  • CONTINUOUS
pipeline_idstring

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

embedding_writeback_tablestring

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

columns_to_syncarray of string

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

columns_to_indexarray of string

[Optional] Alias for columns_to_sync. Select the columns to include in the vector index. If you leave this field blank, all columns from the source table are included. The primary key column and embedding source column or embedding vector column are always included. Only one of columns_to_sync or columns_to_index may be specified.

index_subtypestringBeta

The subtype of the index. Use HYBRID or FULL_TEXT. VECTOR is not supported.

Values:

  • VECTOR
  • FULL_TEXT
  • HYBRID

Response​

Returns the VectorIndex object.

Delete an index GA​

DELETE /api/2.0/vector-search/indexes/{name}

Delete an index and the data it holds. The source table of a Delta Sync index is not affected.

API scopes: vector-search

Parameters​

namestringRequiredpath

Three-level Unity Catalog name of the index.

Delete data from index GA​

DELETE /api/2.0/vector-search/indexes/{name}/delete-data

Delete rows from a Direct Vector Access index by primary key. The response reports how many rows were deleted and the primary keys of the rows that failed.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index where data is to be deleted. Must be a Direct Vector Access Index.

primary_keysarray of stringRequiredquery

Primary keys of the rows to delete. At least one key is required.

Response​

statusstring

Status of the delete operation.

Values:

  • SUCCESS
  • PARTIAL_SUCCESS
  • FAILURE
resultobject

Result of the upsert or delete operation.

Show child attributesHide child attributes
success_row_countint64

Count of successfully processed rows.

failed_primary_keysarray of string

List of primary keys for rows that failed to process.

Query an index GA​

POST /api/2.0/vector-search/indexes/{name}/query

Query an index with a vector, text, or both, and return the requested columns of the best-matching rows.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index to query.

Request body​

num_resultsint32

Maximum number of results to return. It must be greater than 0 and defaults to 10. By default, a HYBRID query can return at most 200 results.

columnsarray of stringRequired

Names of the columns to return for each result. At least one column is required, and only columns that are part of the index can be returned.

filters_jsonstring

Filters to apply to the results, as a JSON object serialized to a string. Each key is a column name, optionally followed by a space and an operator, and each value is the value or list of values to compare the column against. A key without an operator matches the value exactly, or any of the listed values. Supported operators are NOT, <, <=, >, >=, OR and LIKE; see https://docs.databricks.com/aws/en/ai-search/query-ai-search for their semantics. This field is not supported on storage-optimized endpoints.

query_vectorarray of floatdouble

Embedding vector to search for. Use it for an index whose embeddings you compute yourself: a Direct Vector Access index or a Delta Sync index with embedding_vector_columns. A HYBRID query on a Delta Sync index with embedding_vector_columns, or on a Direct Vector Access index without embedding_source_columns, requires both query_vector and query_text. A Direct Vector Access index with embedding_source_columns can be queried with query_text alone.

query_textstring

Text to search for. Use it for an index with Databricks-managed embeddings, which embeds the text with the index's embedding model endpoint, and for FULL_TEXT queries on any index. A HYBRID query on an index with managed embeddings requires only query_text.

score_thresholdfloatdouble

Threshold for the approximate nearest neighbor search. Defaults to 0.0.

query_typestring

The query type to use. Choices are ANN and HYBRID and FULL_TEXT. Defaults to ANN.

rerankerobject

If set, the top 50 results are reranked with the Databricks Reranker model before returning the num_results results to the user. The setting columns_to_rerank selects which columns are used for reranking. For each datapoint, the columns selected are concatenated before being sent to the reranking model. See https://docs.databricks.com/aws/en/vector-search/query-vector-search#rerank for more information.

Show child attributesHide child attributes
modelstring

Reranker identifier:

  • When model_type=BASE/UNSPECIFIED: must be "databricks_reranker".
  • When model_type=FINETUNED: the Model Serving endpoint name hosting a finetuned reranker.
parametersobject

Parameters that control how the reranker processes the query results.

Show child attributesHide child attributes
columns_to_rerankarray of string

Names of the columns whose values are sent to the reranker. List the most relevant column first, since the order affects the ranking.

query_columnsarray of stringBeta

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

sort_columnsarray of stringBeta

Sort results by column values instead of the default relevance ordering. Each clause has the form "<column> ASC" or "<column> DESC", for example ["rating DESC", "price ASC"].

facetsarray of stringBeta

Facets to compute over the matched results. Each entry has one of these forms: "<column>" - top 10 distinct values by count "<column> TOP <n>" - top n distinct values, where n > 0 "<column> BUCKETS [[from,to],...]" - inclusive numeric ranges TOP and BUCKETS are case-insensitive. A column may appear at most once.

Response​

manifestobject

Metadata about the result set.

Show child attributesHide child attributes
column_countint32

Number of columns in the result set.

columnsarray of object

Information about each column in the result set.

Show child attributesHide child attributes
namestring

Name of the column.

type_textstring

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

facet_column_countint32Beta

Number of columns in facet_result.

facet_columnsarray of objectBeta

Information about each column in facet_result.

Show child attributesHide child attributes
namestring

Name of the column.

type_textstring

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

resultobject

Data returned in the query result.

Show child attributesHide child attributes
row_countint32

Number of rows in the result set.

data_arrayarray of array of object

Data rows returned in the query.

next_page_tokenstring

[Optional] Token that can be used in QueryVectorIndexNextPage API to get next page of results. If more than 1000 results satisfy the query, they are returned in groups of 1000. Empty value means no more results. The maximum number of results that can be returned is 10,000.

facet_resultobjectBeta

Facet aggregation rows returned by a query.

Show child attributesHide child attributes
facet_row_countint32Beta

Number of facet rows returned.

facet_arrayarray of array of objectBeta

Facet rows. Each row is [facet_column_name, value_or_range, count].

Query next page GA​

POST /api/2.0/vector-search/indexes/{name}/query-next-page

Use next_page_token returned from previous QueryVectorIndex or QueryVectorIndexNextPage request to fetch next page of results.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index to query.

Request body​

endpoint_namestring

Name of the endpoint that serves the index.

page_tokenstring

Page token returned from previous QueryVectorIndex or QueryVectorIndexNextPage API.

Response​

manifestobject

Metadata about the result set.

Show child attributesHide child attributes
column_countint32

Number of columns in the result set.

columnsarray of object

Information about each column in the result set.

Show child attributesHide child attributes
namestring

Name of the column.

type_textstring

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

facet_column_countint32Beta

Number of columns in facet_result.

facet_columnsarray of objectBeta

Information about each column in facet_result.

Show child attributesHide child attributes
namestring

Name of the column.

type_textstring

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

resultobject

Data returned in the query result.

Show child attributesHide child attributes
row_countint32

Number of rows in the result set.

data_arrayarray of array of object

Data rows returned in the query.

next_page_tokenstring

[Optional] Token that can be used in QueryVectorIndexNextPage API to get next page of results. If more than 1000 results satisfy the query, they are returned in groups of 1000. Empty value means no more results. The maximum number of results that can be returned is 10,000.

facet_resultobjectBeta

Facet aggregation rows returned by a query.

Show child attributesHide child attributes
facet_row_countint32Beta

Number of facet rows returned.

facet_arrayarray of array of objectBeta

Facet rows. Each row is [facet_column_name, value_or_range, count].

Scan an index GA​

POST /api/2.0/vector-search/indexes/{name}/scan

Scan an index and return the first num_results rows after the exclusive last_primary_key. Repeat the call with the returned last_primary_key to read the whole index.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index to scan.

Request body​

num_resultsint32

Number of results to return. Defaults to 10.

last_primary_keystring

Primary key of the last entry returned in the previous scan.

Response​

dataarray of object

List of data entries

Show child attributesHide child attributes
fieldsarray of object

Data entry, corresponding to a row in a vector index.

Show child attributesHide child attributes
keystring

Column name.

valueobject

Column value, nullable.

Show child attributesHide child attributes
number_valuedouble
string_valuestring
bool_valueboolean
list_valueobject
last_primary_keystring

Primary key of the last entry.

Synchronize an index GA​

POST /api/2.0/vector-search/indexes/{name}/sync

Start a sync of a Delta Sync index with a TRIGGERED pipeline from its source table. An index with a CONTINUOUS pipeline syncs automatically and rejects manual syncs.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index to synchronize. Must be a Delta Sync Index.

Upsert data into an index GA​

POST /api/2.0/vector-search/indexes/{name}/upsert-data

Insert rows into a Direct Vector Access index, replacing existing rows that have the same primary key. The response reports how many rows succeeded and the primary keys of the rows that failed.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the vector index where data is to be upserted. Must be a Direct Vector Access Index.

Request body​

inputs_jsonstringRequired

Rows to upsert, as a JSON array of objects serialized to a string. Each object maps column names from schema_json to values and must include the primary key. A row whose primary key already exists in the index is replaced.

Response​

statusstring

Status of the upsert operation.

Values:

  • SUCCESS
  • PARTIAL_SUCCESS
  • FAILURE
resultobject

Result of the upsert or delete operation.

Show child attributesHide child attributes
success_row_countint64

Count of successfully processed rows.

failed_primary_keysarray of string

List of primary keys for rows that failed to process.

Retrieve user-visible metrics for an endpoint GA​

POST /api/2.0/vector-search/endpoints/{name}/metrics

Retrieve time series of usage and health metrics for an endpoint and its indexes, such as request counts, request latency percentiles and endpoint utilization.

API scopes: vector-search

Parameters​

namestringRequiredpath

Name of the endpoint whose metrics to retrieve.

Request body​

start_timestring

Start of the time range. Required. Must be within the last 169 hours.

end_timestring

End of the time range. Defaults to the current time. Must be later than start_time.

granularity_in_secondsint32

Requested interval between data points, in seconds. Defaults to 60, which is also the minimum. The server may return a finer or coarser interval: 60 seconds only for time ranges of 1 hour or less, otherwise 300 seconds or more. Read the interval from the returned timestamps.

Example: 300

metricsarray of object

Metrics to retrieve. Each entry names a metric and optionally narrows it with labels or a percentile. An unknown metric name fails the whole request, and an empty list returns no series.

Show child attributesHide child attributes
namestring

Metric name. Supported metrics include: EndpointHealthStatus, EndpointConcurrency, IndexRequestCount, IndexRequestLatency, IndexRequestErrorSourceCount, IndexRequestGuidanceCount, IndexRequestGuidancePeakRate, IndexIngestedRows, and IndexEmbeddedRows. An unknown name is rejected with an error that lists the available metric names.

Example: IndexRequestLatency

labelsarray of object

Labels that restrict the metric to matching series, for example to a single index. Endpoint-level metrics do not accept labels.

Show child attributesHide child attributes
namestring

Label name, such as error_source, failure_cause, operation, request_path, query_type, response_code, or index_name. Supported labels depend on the metric.

Example: index_name

valuestring

Label value, as an RE2 regular expression. The label also splits the result by its values, so .+ returns one series per value. Some labels, such as operation, accept only .+, .*, or listed values joined by |.

percentiledouble

Percentile for latency metrics, such as IndexRequestLatency, which require it. One of 0.5, 0.75, 0.9, 0.95, or 0.99.

Example: 0.95

page_tokenstring

Not used. The response returns all data points in one page.

Response​

metric_valuesarray of object

One time series for each requested metric and each combination of label values it was broken down by.

Show child attributesHide child attributes
metricobject

The metric this time series was computed for, including the labels that identify the series.

Show child attributesHide child attributes
namestring

Metric name. Supported metrics include: EndpointHealthStatus, EndpointConcurrency, IndexRequestCount, IndexRequestLatency, IndexRequestErrorSourceCount, IndexRequestGuidanceCount, IndexRequestGuidancePeakRate, IndexIngestedRows, and IndexEmbeddedRows. An unknown name is rejected with an error that lists the available metric names.

Example: IndexRequestLatency

labelsarray of object

Labels that restrict the metric to matching series, for example to a single index. Endpoint-level metrics do not accept labels.

Show child attributesHide child attributes
namestring

Label name, such as error_source, failure_cause, operation, request_path, query_type, response_code, or index_name. Supported labels depend on the metric.

Example: index_name

valuestring

Label value, as an RE2 regular expression. The label also splits the result by its values, so .+ returns one series per value. Some labels, such as operation, accept only .+, .*, or listed values joined by |.

percentiledouble

Percentile for latency metrics, such as IndexRequestLatency, which require it. One of 0.5, 0.75, 0.9, 0.95, or 0.99.

Example: 0.95

valuesarray of object

Each entry is one data point of the time series.

Show child attributesHide child attributes
timestampint64

Timestamp of the metric value, in seconds since the Unix epoch.

valuedouble

Value of the metric at timestamp.

next_page_tokenstring

Not set. The response returns all data points in one page.