VECTOR_INDEXES view

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To provide feedback or request support for this feature, send email to [e-mail].

The INFORMATION_SCHEMA.VECTOR_INDEXES view contains one row for each vector index in a dataset.

Required permissions

To see vector index metadata, you need the bigquery.tables.get or bigquery.tables.list Identity and Access Management (IAM) permission on the table with the index. Each of the following predefined IAM roles includes at least one of these permissions:

• roles/bigquery.admin
• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.dataViewer
• roles/bigquery.metadataViewer
• roles/bigquery.user

For more information about BigQuery permissions, see Access control with IAM.

Schema

When you query the INFORMATION_SCHEMA.VECTOR_INDEXES view, the query results contain one row for each vector index in a dataset.

The INFORMATION_SCHEMA.VECTOR_INDEXES view has the following schema:

Column name	Data type	Value
index_catalog	STRING	The name of the project that contains the dataset.
index_schema	STRING	The name of the dataset that contains the index.
table_name	STRING	The name of the table that the index is created on.
index_name	STRING	The name of the vector index.
index_status	STRING	The status of the index: ACTIVE, PENDING DISABLEMENT, TEMPORARILY DISABLED, or PERMANENTLY DISABLED. ACTIVE means that the index is usable or being created. Refer to the coverage_percentage to see the progress of index creation. PENDING DISABLEMENT means that the total size of indexed tables exceeds your organization's limit; the index is queued for deletion. While in this state, the index is usable in vector search queries and you are charged for the vector index storage. TEMPORARILY DISABLED means that either the total size of indexed tables exceeds your organization's limit, or the indexed table is smaller than 10 MB. While in this state, the index isn't used in vector search queries and you aren't charged for the vector index storage. PERMANENTLY DISABLED means that there is an incompatible schema change on the indexed table.
creation_time	TIMESTAMP	The time the index was created.
last_modification_time	TIMESTAMP	The last time the index configuration was modified. For example, deleting an indexed column.
last_refresh_time	TIMESTAMP	The last time the table data was indexed. A NULL value means the index is not yet available.
disable_time	TIMESTAMP	The time the status of the index was set to DISABLED. The value is NULL if the index status is not DISABLED.
disable_reason	STRING	The reason the index was disabled. NULL if the index status is not DISABLED.
DDL	STRING	The data definition language (DDL) statement used to create the index.
coverage_percentage	INTEGER	The approximate percentage of table data that has been indexed. 0% means the index is not usable in a VECTOR_SEARCH query, even if some data has already been indexed.
unindexed_row_count	INTEGER	The number of rows in the table that have not been indexed.
total_logical_bytes	INTEGER	The number of billable logical bytes for the index.
total_storage_bytes	INTEGER	The number of billable storage bytes for the index.

Scope and syntax

Queries against this view must have a dataset qualifier. The following table explains the region scope for this view:

View Name	Resource scope	Region scope
[PROJECT_ID.]DATASET_ID.INFORMATION_SCHEMA.VECTOR_INDEXES	Dataset level	Dataset location

Replace the following:

• Optional: PROJECT_ID: the ID of your Google Cloud project. If not specified, the default project is used.
• DATASET_ID: the ID of your dataset. For more information, see Dataset qualifier.

Note: You must specify the location to query the INFORMATION_SCHEMA views and the location of the query execution must match the region of the INFORMATION_SCHEMA view.

Example

-- Returns metadata for vector indexes in a single dataset.
SELECT * FROM myDataset.INFORMATION_SCHEMA.VECTOR_INDEXES;

Example

The following example shows all active vector indexes on tables in the dataset my_dataset, located in the project my_project. It includes their names, the DDL statements used to create them, and their coverage percentage. If an indexed base table is less than 10 MB, then its index is not populated, in which case the coverage_percentage value is 0.

SELECT table_name, index_name, ddl, coverage_percentage
FROM my_project.my_dataset.INFORMATION_SCHEMA.VECTOR_INDEXES
WHERE index_status = 'ACTIVE';

The result is similar to the following:

+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| table_name  | index_name  | ddl                                                                                           | coverage_percentage |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| small_table | myindex1    | CREATE VECTOR INDEX `myindex1` ON `my_project.my_dataset.small_table`(embeddings)             | 100                 |
|             |             | OPTIONS (distance_type = 'EUCLIDEAN', index_type = 'IVF', ivf_options = '{"numLists": 3}')    |                     |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+
| large_table | myindex2    | CREATE VECTOR INDEX `myindex2` ON `my_project.my_dataset.large_table`(vectors)                |  42                 |
|             |             | OPTIONS (distance_type = 'EUCLIDEAN', index_type = 'IVF', ivf_options = '{"numLists": 12}')   |                     |
+-------------+-------------+-----------------------------------------------------------------------------------------------+---------------------+