Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">18.4.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-index-query-vectors.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/containers/18.4.0/docs/ai/store-index-query-vectors.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/containers/18.3.0/docs/ai/store-index-query-vectors.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/containers/18.1.0/docs/ai/store-index-query-vectors.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/containers/17.10.0/docs/ai/store-index-query-vectors.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/containers/17.9.0/docs/ai/store-index-query-vectors.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/containers/17.7.0/docs/ai/store-index-query-vectors.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/containers/17.5.0/docs/ai/store-index-query-vectors.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/containers/16.14.0/docs/ai/store-index-query-vectors.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/containers/16.13.0/docs/ai/store-index-query-vectors.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/containers/16.11.0/docs/ai/store-index-query-vectors.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/containers/16.9.0/docs/ai/store-index-query-vectors.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/containers/16.8.0/docs/ai/store-index-query-vectors.md.txt)
- [16.3.0](https://docs.cloud.google.com/alloydb/omni/containers/16.3.0/docs/ai/store-index-query-vectors.md.txt)
- [15.18.0](https://docs.cloud.google.com/alloydb/omni/containers/15.18.0/docs/ai/store-index-query-vectors.md.txt)
- [15.17.0](https://docs.cloud.google.com/alloydb/omni/containers/15.17.0/docs/ai/store-index-query-vectors.md.txt)
- [15.15.0](https://docs.cloud.google.com/alloydb/omni/containers/15.15.0/docs/ai/store-index-query-vectors.md.txt)
- [15.13.0](https://docs.cloud.google.com/alloydb/omni/containers/15.13.0/docs/ai/store-index-query-vectors.md.txt)
- [15.12.0](https://docs.cloud.google.com/alloydb/omni/containers/15.12.0/docs/ai/store-index-query-vectors.md.txt)
- [15.7.1](https://docs.cloud.google.com/alloydb/omni/containers/15.7.1/docs/ai/store-index-query-vectors.md.txt)
- [15.7.0](https://docs.cloud.google.com/alloydb/omni/containers/15.7.0/docs/ai/store-index-query-vectors.md.txt)

<br />

This document shows you how to use stored embeddings to generate indexes and query
embeddings. For more information about storing embedding, see
[Store vector embeddings](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-embeddings.md.txt).

You can create `ScaNN`, `IVF`, `IVFFlat`, and `HNSW` indexes with AlloyDB.

> [!CAUTION]
> **Caution:** The `postgres_ann` extension is renamed to `alloydb_scann`. Before you upgrade to AlloyDB Omni, you must drop any indexes created using the older `postgres_ann` version. Next, upgrade AlloyDB Omni, and then [create the indexes](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-index-query-vectors.md.txt#create-index) again using the `alloydb_scann` extension. This applies only to AlloyDB Omni.

## Before you begin

Before you can start creating indexes, you must complete the following
prerequisites.

- [Embedding vectors are added to a table](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-embeddings.md.txt) in your
  AlloyDB database.

- The `vector` extension version `0.5.0` or later that is based on `pgvector`, extended by Google for
  AlloyDB is installed.

  ```sql
  CREATE EXTENSION IF NOT EXISTS vector;
  ```
- To generate `ScaNN` indexes, install the `alloydb_scann` extension in addition
  to the `vector` extension.

  ```sql
  CREATE EXTENSION IF NOT EXISTS alloydb_scann;
  ```

> [!NOTE]
> **Note:** The `alloydb_scann` extension can be used with PostgreSQL 14 and later compatible databases.

## Create an index

You can create one of the following index types for tables in your database.

> [!NOTE]
> **Note:** As the index names are shared across the database, create an index name unique to each table in your database.

<button value="scann" default="">ScaNN</button> <button value="ivf">IVF</button> <button value="ivfflat">IVFFlat</button> <button value="hnsw">HNSW</button>

### Create a `ScaNN` index

AlloyDB `alloydb_scann`, a
PostgreSQL extension developed by Google that implements a highly
efficient nearest-neighbor index powered by [the ScaNN
algorithm](https://github.com/google-research/google-research/blob/master/scann/docs/algorithms.md).

> [!IMPORTANT]
> **Important:** After you create the `ScaNN` index, you must [run the `ANALYZE` command](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-index-query-vectors.md.txt#analyze-indexed-table) to update statistics about your data.

The `ScaNN` index is a tree-based quantization index for approximate
nearest neighbor search. It provides lower index building time and smaller
memory footprint as compared to `HNSW`. In addition, it provides faster QPS in
comparison to `HNSW` based on the workload.

> [!NOTE]
> **Note:** Before you create an index, ensure that you add embedding vectors to a table in your AlloyDB database. If you try to generate a `ScaNN` index on an empty or partitioned table, then you might encounter some issues.

#### Two-level tree `ScaNN` index

To apply a two-level tree index using the ScaNN algorithm to a column
containing stored vector embeddings, run the following DDL query:

```sql
CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE);
```

Replace the following:

- `INDEX_NAME`: the name of the index you want to
  create---for example, `my-scann-index`. The index names are shared
  across your database. Ensure that each index name is unique to each
  table in your database.

- `TABLE`: the table to add the index to.

- `EMBEDDING_COLUMN`: the column that stores `vector`
  data.

- `DISTANCE_FUNCTION`: the distance function to use
  with this index. Choose one of the following:

  - **L2 distance:** `l2`

  - **Dot product:** `dot_product`

  - **Cosine distance:** `cosine`

- `NUM_LEAVES_VALUE`: the number of partitions to apply to
  this index. Set to any value between 1 and 100 million for PostgreSQL 17 and higher, or between 1 and 30 million for PostgreSQL 16 and lower. For more information
  about how to decide this value, see [Tune a `ScaNN` index](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/tune-indexes.md.txt).

#### Three-level tree `ScaNN` index

To create a three-level tree index using the ScaNN algorithm to a column
containing stored vector embeddings, run the following DDL query:

```sql
CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);
```

Replace the following:

- `MAX_NUM_LEVELS`: the maximum number of levels of the K-means clustering tree. Set to `1`(default) for two-level tree-based quantization and to `2` for three-level tree-based quantization.

> [!IMPORTANT]
> **Important:** To ensure optimal query performance after creating the ScaNN index, [run the `ANALYZE` command](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-index-query-vectors.md.txt#analyze-indexed-table) to update the statistics about your data.

After you create the index, you can run nearest-neighbor search queries that
make use of the index by following the instructions in [Make a nearest-neighbor
query with given text](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/store-index-query-vectors#query).

The index parameters must be set to strike a right balance between QPS and
recall. For more information about tuning the `ScaNN` index, see [Tune a `ScaNN`
index](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/tune-indexes).

To create this index on an embedding column that uses the `real[]` data type
instead of `vector`, cast the column into the `vector` data type:

```sql
CREATE INDEX INDEX_NAME ON TABLE
  USING scann (CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)) DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);
```

Replace `DIMENSIONS` with the dimensional width of the
embedding column. For more information about how to find the dimensions,
see the `vector_dims` function in [Vector
functions](https://github.com/pgvector/pgvector?tab=readme-ov-file#vector-functions).

To view the indexing progress, use the `pg_stat_progress_create_index` view:

```sql
SELECT * FROM pg_stat_progress_create_index;
```

The `phase` column shows the current state of your index creation, and the
`building index: tree training` phase disappears after the index is created.

To tune your index for a target recall and QPS balance, see [Tune a `ScaNN` index](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/tune-indexes.md.txt).

### Analyze your indexed table

After you create the `ScaNN` index, you must run the `ANALYZE` command to update statistics about your data.

```sql
ANALYZE TABLE;
```

### Build indexes in parallel

AlloyDB might automatically spawn multiple parallel workers, depending on your dataset and the type of index you choose to build your index faster.

The parallel index build is often triggered when you create a 3-level ScaNN
index or if your dataset exceeds 100M rows.

Although AlloyDB automatically optimizes the number of parallel workers, you can tune the parallel workers using the [`max_parallel_maintenance_workers`](https://www.postgresql.org/docs/15/runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS), [`max_parallel_workers`](https://www.postgresql.org/docs/15/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS), and the [`min_parallel_table_scan_size`](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-MIN-PARALLEL-TABLE-SCAN-SIZE) PostgreSQL query planning parameters.

> [!NOTE]
> **Note:** To avoid out-of-memory issues when you generate the index, make sure that the [`maintenance_work_mem`](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM) database flag (GUC) is set to a value less than total machine memory.

## Run a query

After you have stored and indexed embeddings in your database, you can start
querying using the [`pgvector` query
functionality](https://github.com/pgvector/pgvector#querying). You cannot run
bulk search queries using the `alloydb_scann` extension.

To find the nearest semantic neighbors for an embedding vector, you can run the
following example query, where you set the same distance function that you used
during the index creation.

```sql
  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY '[EMBEDDING]'
    LIMIT ROW_COUNT;
```

Replace the following:

- `TABLE`: the table containing the embedding to compare the
  text to.

- `EMBEDDING_COLUMN`: the column containing the stored
  embeddings.

- `DISTANCE_FUNCTION_QUERY`: the distance function to use with this
  query. Choose one of the following based on the distance function used
  while creating the index:

  - **L2 distance:** `<->`

  - **Inner product:** `<#>`

  - **Cosine distance:** `<=>`

- `EMBEDDING`: the embedding vector you want to find the nearest stored
  semantic neighbors of.

- `ROW_COUNT`: the number of rows to return.

  Specify `1` if you want only the single best match.

For more information about other query examples, see
[Querying](https://github.com/pgvector/pgvector?tab=readme-ov-file#querying).

You can use also use the [`embedding()`](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/work-with-embeddings.md.txt) function to translate the
text into a vector. You apply the vector to one of the
`pgvector` nearest-neighbor operator, `<->` for L2 distance, to find the database rows with the
most semantically similar embeddings.

Because `embedding()` returns a `real` array, you must explicitly cast the
`embedding()` call to `vector` in order to use these values with `pgvector`
operators.

```sql
  CREATE EXTENSION IF NOT EXISTS google_ml_integration;
  CREATE EXTENSION IF NOT EXISTS vector;

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT;
```

Replace the following:


- `MODEL_ID`: the ID of the model to query.

  If you are using the Vertex AI
  Model Garden, then specify
  `text-embedding-005` as the model ID. These are the cloud-based models that
  AlloyDB can use for text embeddings. For more information, see
  [Text embeddings](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/text-embeddings-api.md.txt).
- Optional: `VERSION_TAG`: the version tag of the model to
  query. Prepend the tag with `@`.

  If you are using one of the `text-embedding` English models with
  Vertex AI, then specify one of the version tags---for example, `text-embedding-005`,
  listed in [Model versions](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/text-embeddings-api.md.txt#model_versions).

  Google strongly recommends that you always specify the version
  tag. If you don't specify the version tag, then AlloyDB always
  uses the latest model version, which might lead to unexpected results.

<br />

- `TEXT`: the text to translate into a vector embedding.

## What's next

- See [an example embedding workflow](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/example-embeddings.md.txt).
- [Tune vector query performance](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/ai/tune-indexes.md.txt).
- See [vector index metrics](https://docs.cloud.google.com/alloydb/omni/containers/current/docs/reference/vector-index-metrics.md.txt).