This page documents AlloyDB Omni version 18.1.0 using the container orchestrator deployment option. Choose a different deployment option .

Tune vector query performance in AlloyDB Omni

Select a documentation version:

This document describes how to tune your indexes to achieve faster query performance and better recall in 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 feature for your instance. To enable the Preview feature, choose one of the following two methods:
- Enable the scann.enable_preview_features database flag.
- Set the session-level 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 ).
For 1 billion to 10 billion rows: Choose a four-level index (in Preview ).

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

  SET 
  
 LOCAL 
  
 scann 
 . 
 num_leaves_to_search 
  
 = 
  
 1 
 ; 
 SET 
  
 LOCAL 
  
 scann 
 . 
 pre_reordering_num_neighbors 
 = 
 50 
 ; 
 CREATE 
  
 INDEX 
  
 my 
 - 
 scann 
 - 
 index 
  
 ON 
  
 my 
 - 
 table 
  
 USING 
  
 scann 
  
 ( 
 vector_column 
  
 cosine 
 ) 
  
 WITH 
  
 ( 
 num_leaves 
  
 = 
  
 [ 
 power 
 ( 
 1000000 
 , 
  
 1 
 / 
 2 
 )]);

Three-level index

  SET 
  
 LOCAL 
  
 scann 
 . 
 num_leaves_to_search 
  
 = 
  
 10 
 ; 
 SET 
  
 LOCAL 
  
 scann 
 . 
 pre_reordering_num_neighbors 
 = 
 50 
 ; 
 CREATE 
  
 INDEX 
  
 my 
 - 
 scann 
 - 
 index 
  
 ON 
  
 my 
 - 
 table 
  
 USING 
  
 scann 
  
 ( 
 vector_column 
  
 cosine 
 ) 
  
 WITH 
  
 ( 
 num_leaves 
  
 = 
  
 [ 
 power 
 ( 
 1000000 
 , 
  
 2 
 / 
 3 
 )], 
  
 max_num_levels 
  
 = 
  
 2 
 );

Four-level index

(in Preview )

  SET 
  
 LOCAL 
  
 scann 
 . 
 num_leaves_to_search 
  
 = 
  
 100 
 ; 
 SET 
  
 LOCAL 
  
 scann 
 . 
 pre_reordering_num_neighbors 
 = 
 50 
 ; 
 CREATE 
  
 INDEX 
  
 my 
 - 
 scann 
 - 
 index 
  
 ON 
  
 my 
 - 
 table 
  
 USING 
  
 scann 
  
 ( 
 vector_column 
  
 cosine 
 ) 
  
 WITH 
  
 ( 
 num_leaves 
  
 = 
  
 [ 
 power 
 ( 
 1000000 
 , 
  
 3 
 / 
 4 
 )], 
  
 max_num_levels 
  
 = 
  
 3 
 );

Handle DML invalidations due to acceleration with columnar engine

If you chose to accelerate your vector searches with the columnar engine , 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.

   
 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:

  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:

  SELECT 
  
 * 
  
 FROM 
  
 pg_stat_ann_index_creation 
 ;