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/kubernetes/current/docs/ai/tune-indexes.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/ai/tune-indexes.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/ai/tune-indexes.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/ai/tune-indexes.md.txt)
- [17.10.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.10.0/docs/ai/tune-indexes.md.txt)
- [17.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.9.0/docs/ai/tune-indexes.md.txt)
- [17.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.7.0/docs/ai/tune-indexes.md.txt)
- [17.5.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/17.5.0/docs/ai/tune-indexes.md.txt)
- [16.14.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.14.0/docs/ai/tune-indexes.md.txt)
- [16.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.13.0/docs/ai/tune-indexes.md.txt)
- [16.11.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.11.0/docs/ai/tune-indexes.md.txt)
- [16.9.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.9.0/docs/ai/tune-indexes.md.txt)
- [16.8.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.8.0/docs/ai/tune-indexes.md.txt)
- [16.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/16.3.0/docs/ai/tune-indexes.md.txt)
- [15.18.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.18.0/docs/ai/tune-indexes.md.txt)
- [15.17.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.17.0/docs/ai/tune-indexes.md.txt)
- [15.15.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.15.0/docs/ai/tune-indexes.md.txt)
- [15.13.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.13.0/docs/ai/tune-indexes.md.txt)
- [15.12.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.12.0/docs/ai/tune-indexes.md.txt)
- [15.7.1](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.1/docs/ai/tune-indexes.md.txt)
- [15.7.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/15.7.0/docs/ai/tune-indexes.md.txt)

<br />

This document describes how to tune your indexes to achieve faster query
performance and better recall in AlloyDB Omni.
<button value="scann" default="">ScaNN</button> <button value="ivf">IVF</button> <button value="ivfflat">IVFFlat</button> <button value="hnsw">HNSW</button>

> [!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 again using the `alloydb_scann` extension. This applies only to AlloyDB Omni.

## Before you begin

Before you build a `ScaNN` index, complete the following:

- Make sure that a table with your data is already created.
- To avoid issues while generating the index, make sure that the value you set for the `maintenance_work_mem` and the `shared_buffers` flag is less than total machine memory.
- To use four-level indexes, you must first enable the [Preview](https://cloud.google.com/products#product-launch-stages) feature for your instance. To enable the Preview feature, choose one of the following two methods:
  - Enable the [`scann.enable_preview_features`](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/reference/alloydb-flags.md.txt#scann.enable_preview_features) database flag.
  - Set the session-level [`scann.max_allowed_num_levels`](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/reference/alloydb-flags.md.txt#scann.max_allowed_num_levels) database flag to `3`. `sql
    SET scann.max_allowed_num_levels = 3;`

## Tune a `ScaNN` index

Use the following guidance to determine the number of levels needed for your ScaNN index:

- For 0 to 10 million rows: Choose a two-level index.
- For 10 million to 100 million rows:
  - To prioritize search recall, choose a two-level index.
  - To prioritize index build time, choose a three-level index.
- For 100 million to 1 billion rows:
  - To prioritize search recall, choose a three-level index.
  - To prioritize index build time, choose a four-level index (in [Preview](https://cloud.google.com/products#product-launch-stages)).
- For 1 billion to 10 billion rows: Choose a four-level index (in [Preview](https://cloud.google.com/products#product-launch-stages)).

Consider the following examples for two-level, three-level, and four-level `ScaNN` indexes that show how tuning parameters are set for a table with 1,000,000 rows:

### Two-level index

\`\`\`sql -- Setting num_leaves to 1000 as power(1000000, 1/2) for two-level index BEGIN; SET LOCAL maintenance_work_mem = '300MB'; CREATE INDEX my_scann_index ON my_table USING scann (vector_column cosine) WITH (num_leaves = 1000); END; \`\`\`

### Three-level index

\`\`\`sql -- Setting num_leaves to 10000 as power(1000000, 2/3) for three-level index BEGIN; SET LOCAL maintenance_work_mem = '3000MB'; CREATE INDEX my_scann_index ON my_table USING scann (vector_column cosine) WITH (num_leaves = 10000, max_num_levels = 2); END; \`\`\`

### Four-level index (Preview)

\`\`\`sql -- Setting num_leaves to 31623 as power(1000000, 3/4) for four-level index BEGIN; SET LOCAL maintenance_work_mem = '9300MB'; CREATE INDEX my_scann_index ON my_table USING scann (vector_column cosine) WITH (num_leaves = 31623, max_num_levels = 3); END; \`\`\`

### Handle DML invalidations due to acceleration with columnar engine

If you chose to [accelerate your vector searches with the columnar engine](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/accelerate-with-ce.md.txt), be aware that DML and DDL invalidations on the base tables can impact vector query performance. In case of high DML throughput, consider tuning the `google_columnar_engine.refresh_threshold_percentage` database flag or manually refreshing the index using the `google_columnar_engine_refresh_index` command.

## Analyze your queries

Use the `EXPLAIN ANALYZE` command to analyze your query insights as shown in the following example SQL query.

```sql
  EXPLAIN ANALYZE SELECT result_column
  FROM my_table
  ORDER BY EMBEDDING_COLUMN <=> embedding('text-embedding-005', 'What is a database?')::vector
  LIMIT 1;
```

The example response `QUERY PLAN` includes information such as the time taken, the number of rows scanned or returned, and the resources used.

    Limit  (cost=0.42..15.27 rows=1 width=32) (actual time=0.106..0.132 rows=1 loops=1)
      ->  Index Scan using my_scann_index on my_table  (cost=0.42..858027.93 rows=100000 width=32) (actual time=0.105..0.129 rows=1 loops=1)
            Order By: (embedding_column <=> embedding('text-embedding-005', 'What is a database?')::vector(768))
            Limit value: 1
    Planning Time: 0.354 ms
    Execution Time: 0.141 ms

## View vector index metrics

You can use the vector index metrics to review performance of your vector index,
identify areas for improvement, and tune your index based on the metrics, if
needed.

To view all vector index metrics, run the following SQL query, which uses the
`pg_stat_ann_indexes` view:

```sql
SELECT * FROM pg_stat_ann_indexes;
```

You see output similar to the following:

    -[ RECORD 1 ]---+---
    relid                  | 271236
    indexrelid             | 271242
    schemaname             | public
    relname                | t1
    indexrelname           | t1_ix1
    indextype              | scann
    indexconfig            | {num_leaves=100,max_num_levels=1,quantizer=SQ8}
    indexsize              | 832 kB
    indexscan              | 0
    insertcount            | 250
    deletecount            | 0
    updatecount            | 0
    partitioncount         | 100
    distribution           | {"average": 3.54, "maximum": 37, "minimum": 0, "outliers": [37, 12, 11, 10, 10, 9, 9, 9, 9, 9]}
    distributionpercentile |{"10": { "num_vectors": 0, "num_partitions": 0 }, "25": { "num_vectors": 0, "num_partitions": 30 }, "50": { "num_vectors": 3, "num_partitions": 30 }, "75": { "num_vectors": 5, "num_partitions": 19 }, "90": { "num_vectors": 7, "num_partitions": 11 }, "95": { "num_vectors": 9, "num_partitions": 5 }, "99": { "num_vectors": 12, "num_partitions": 4 }, "100": { "num_vectors": 37, "num_partitions": 1 }}

To view number of rows created at the time of index creation, run the following command:

```sql
SELECT * FROM pg_stat_ann_index_creation;
```

You see output similar to the following:

    -[ RECORD 1 ]---+---
    relid                         | 271236
    indexrelid                    | 271242
    schemaname                    | public
    relname                       | t1
    indexrelname                  | t1_ix1
    index_rows_at_creation_time   | 262144

For more information about the complete list of metrics, see [Vector index
metrics](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/reference/vector-index-metrics).

## What's next

- [Create a ScaNN index](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/create-scann-index.md.txt)
- [Best practices for tuning ScaNN indexes](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/best-practices-tuning-scann.md.txt)
- See [an example embedding workflow](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/ai/example-embeddings.md.txt).