The usability metrics include metrics that help you understand the state of
index utilization with metrics, such as index configuration and number of index
scans.
Metric name
Data type
Description
relid
OID
Unique identifier of the table that contains the vector index
indexrelid
OID
Unique identifier of the vector index
schemaname
NAME
Name of the schema that owns the index
relname
NAME
Name of the table that contains the index
indexrelname
NAME
Name of the index
indextype
NAME
Type of the index. This value is always set to scann
indexconfig
TEXT[]
Configuration, such as leaves count and quantizer, defined for the index when it was created
indexsize
TEXT
Size of the index
indexscan
BIGINT
Number of index scans initiated on the index
Tuning metrics
Tuning metrics provide insights into your current index optimization, allowing you to apply recommendations for faster query performance.
Metric name
Data type
Description
insertcount
BIGINT
Number of insert operations on the index. This metric also includes the number of rows that existed before the index was created.
updatecount
BIGINT
Number of update operations on the index. This metric doesn't take into account any HOT updates.
deletecount
BIGINT
Number of delete operations on the index.
distribution
JSONB
Vector distributions across all partitions for the index.
The following fields show the distribution:
maximum (INT8): Maximum number of vectors across all partitions.
minimum (INT8): Minimum number of vectors across all partitions.
average (FLOAT) : Average number of vectors across all partitions.
outliers (INT8[]): Top outliers across all partitions. This value shows the top 20 outliers.
Note: Due to the inherent characteristics of the K-means clustering algorithm, there will always be some degree of variance in the distribution of vectors across partitions, even when the index is initially created.
distributionpercentile
JSONB
Vector index distribution helps you understand the distribution of vectors between partitions of your ScaNN index. The partitions are created based on num_leaves value defined during index creation.
Vector index distribution contains buckets for 10, 25, 50, 75, 90, 95, 99, and 100th percentiles. Each bucket contains the following values:
Number of vectors present in the partition at the specified percentile.
Number of partitions that have vectors within the range defined by the current and previous percentiles.
Note: Due to the inherent characteristics of the K-means clustering algorithm, there is always some degree of variance in the distribution of vectors across partitions, even when the index is initially created.
Tuning recommendation based on the metrics
Mutation
The insertcount, updatecount,
and deletecount metrics together show the changes or mutations in
the vector for the index.
The index is created with a specific number of vectors and partitions. When operations such as insert, update, or delete are performed on the vector index, it only affects the initial set of partitions where the vectors reside. Consequently, the number of vectors in each partition fluctuates over time, potentially impacting recall, QPS, or both.
If you encounter slowness or accuracy issues such as low QPS or poor recall, in your ANN search queries over time, then consider reviewing these metrics. A high number of mutations relative to the total number of vectors could indicate the need for reindexing.
Distribution
The distribution metric shows the vector distributions across all partitions.
When you create an index, it is created with a specific number of vectors and fixed partitions. The partitioning process and subsequent distribution occurs based on this consideration. If additional vectors are added, they are partitioned among the existing partitions, resulting in a different distribution compared to the distribution when the index was created. Since the final distribution does not consider all vectors simultaneously, the recall, QPS, or both might be affected.
If you observe a gradual decline in the performance of your ANN search queries, such as slower response times or reduced accuracy in the results (measured by QPS or recall), then consider checking this metric and reindexing.
Distribution percentile
The distributionpercentile metric, is a vector index distribution in the pg_stat_ann_indexes view that helps you understand the distribution of vectors between partitions of your ScaNN index. The partitions are created based on num_leaves value defined during index creation.
When you create an alloydb_scann index on the initial set of rows by setting num_leaves, the index can change the distribution of vectors across the partitions due to data operations (skew mutations), or the number of vectors might increase significantly. These changes can lead to degradation of QPS, recall, or both. The vector index distribution can give you signals if the mutation causes a change in the index distribution. This information can help you determine if a reindex is required, or if a change in search time configurations can help improve query performance.
In a vector index, the distribution of vectors across partitions is rarely perfectly even. Such imbalance is referred to as a non-uniform distribution. A certain degree of non-uniformity is often expected and doesn't mean you need to reindex. A non-uniform distribution has the following characteristics:
The variance of the number of vectors is low. Variance can be calculated as
The number of partitions with 0 vectors is low, and might be less than 30% of partitions.
The variance of the number of partitions is low.
$ variance _{p} = abs(p_{num\_partitions} - num\_leaves * (p_{percentile} - p-1_{percentile})) $ where "p" is a vector index distribution bucket.
The number of vectors at any percentile is
$< 8 x (\frac{num\_rows\ during\ index\ creation\ time}{ num\_leaves})$
When these conditions aren't satisfied, REINDEX might be required based on how much QPS and recall are affected.
The following scenarios, while less common than non-uniform distribution, can occur:
Approximate Uniform Index: When most of the partitions have the same number of non-zero vectors and the variance of the number of vectors is low, it is an approximate uniform index. REINDEX is required if the number vectors in each partition are $> 8 * average vector$ at index_creation_time.
Sparse Index: A sparse index also occurs where > 50% of the partitions are empty. For example, sparse index is created when multiple deletions occur on a table. This scenario causes the vectors to be concentrated in a small number of partitions, which increases the number of vectors in each partition. When this happens, drop the index and recreate it.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003epg_stat_ann_indexes\u003c/code\u003e view provides metrics for vector indexes generated in AlloyDB Omni, accessible after installing the \u003ccode\u003ealloydb_scann\u003c/code\u003e extension.\u003c/p\u003e\n"],["\u003cp\u003eUsability metrics, such as \u003ccode\u003eindexconfig\u003c/code\u003e and \u003ccode\u003eindexscan\u003c/code\u003e, help to understand the current state of index utilization, including index configuration and scan frequency.\u003c/p\u003e\n"],["\u003cp\u003eTuning metrics, including \u003ccode\u003einsertcount\u003c/code\u003e, \u003ccode\u003eupdatecount\u003c/code\u003e, \u003ccode\u003edeletecount\u003c/code\u003e, and \u003ccode\u003edistribution\u003c/code\u003e, offer insights into index optimization and potential performance issues.\u003c/p\u003e\n"],["\u003cp\u003eHigh mutation rates, indicated by \u003ccode\u003einsertcount\u003c/code\u003e, \u003ccode\u003eupdatecount\u003c/code\u003e, and \u003ccode\u003edeletecount\u003c/code\u003e, or significant vector distribution variance, shown by the \u003ccode\u003edistribution\u003c/code\u003e metric, may suggest a need to reindex to improve query performance.\u003c/p\u003e\n"]]],[],null,["# Vector index metrics\n\nSelect a documentation version: 15.7.1keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/reference/vector-index-metrics)\n- [16.8.0](/alloydb/omni/16.8.0/docs/reference/vector-index-metrics)\n- [16.3.0](/alloydb/omni/16.3.0/docs/reference/vector-index-metrics)\n- [15.12.0](/alloydb/omni/15.12.0/docs/reference/vector-index-metrics)\n- [15.7.1](/alloydb/omni/15.7.1/docs/reference/vector-index-metrics)\n- [15.7.0](/alloydb/omni/15.7.0/docs/reference/vector-index-metrics)\n\n\u003cbr /\u003e\n\nThis page lists the metrics related to the vector indexes that you generate in AlloyDB Omni. You can view these metrics using the `pg_stat_ann_indexes` view that is available when you install [the `alloydb_scann` extension](/alloydb/omni/15.7.1/docs/ai/store-index-query-vectors).\n\n\u003cbr /\u003e\n\nFor more information about viewing the metrics, see [View vector index metrics](/alloydb/omni/15.7.1/docs/ai/tune-indexes#vector-index-metrics).\n\nUsability metrics\n-----------------\n\nThe usability metrics include metrics that help you understand the state of\nindex utilization with metrics, such as index configuration and number of index\nscans.\n\nTuning metrics\n--------------\n\nTuning metrics provide insights into your current index optimization, allowing you to apply recommendations for faster query performance.\n\n### Tuning recommendation based on the metrics\n\nMutation\n: The `insertcount`, `updatecount`,\n and `deletecount` metrics together show the changes or mutations in\n the vector for the index.\n: The index is created with a specific number of vectors and partitions. When operations such as insert, update, or delete are performed on the vector index, it only affects the initial set of partitions where the vectors reside. Consequently, the number of vectors in each partition fluctuates over time, potentially impacting recall, QPS, or both.\n: If you encounter slowness or accuracy issues such as low QPS or poor recall, in your ANN search queries over time, then consider reviewing these metrics. A high number of mutations relative to the total number of vectors could indicate the need for reindexing.\n\nDistribution\n: The `distribution` metric shows the vector distributions across all partitions.\n: When you create an index, it is created with a specific number of vectors and fixed partitions. The partitioning process and subsequent distribution occurs based on this consideration. If additional vectors are added, they are partitioned among the existing partitions, resulting in a different distribution compared to the distribution when the index was created. Since the final distribution does not consider all vectors simultaneously, the recall, QPS, or both might be affected.\n: If you observe a gradual decline in the performance of your ANN search queries, such as slower response times or reduced accuracy in the results (measured by QPS or recall), then consider checking this metric and reindexing.\n\nDistribution percentile\n: The `distributionpercentile` metric, is a vector index distribution in the `pg_stat_ann_indexes` view that helps you understand the distribution of vectors between partitions of your ScaNN index. The partitions are created based on `num_leaves` value defined during index creation.\n: When you create an `alloydb_scann` index on the initial set of rows by setting `num_leaves`, the index can change the distribution of vectors across the partitions due to data operations (skew mutations), or the number of vectors might increase significantly. These changes can lead to degradation of QPS, recall, or both. The vector index distribution can give you signals if the mutation causes a change in the index distribution. This information can help you determine if a reindex is required, or if a change in search time configurations can help improve query performance.\n: In a vector index, the distribution of vectors across partitions is rarely perfectly even. Such imbalance is referred to as a *non-uniform distribution* . A certain degree of non-uniformity is often expected and doesn't mean you need to reindex. A non-uniform distribution has the following characteristics: \n\n - The variance of the number of vectors is low. Variance can be calculated as \n $(P100(num\\\\_vectors) - p10(num\\\\_vectors))\\*(\\\\frac{num\\\\_leaves}{total\\\\_num\\\\_row})$\n - The number of partitions with 0 vectors is low, and might be less than 30% of partitions.\n - The variance of the number of partitions is low. \n $ variance _{p} = abs(p_{num\\\\_partitions} - num\\\\_leaves \\* (p_{percentile} - p-1_{percentile})) $ where \"p\" is a vector index distribution bucket.\n - The number of vectors at any percentile is \n $\\\u003c 8 x (\\\\frac{num\\\\_rows\\\\ during\\\\ index\\\\ creation\\\\ time}{ num\\\\_leaves})$\n\n When these conditions aren't satisfied, `REINDEX` might be required based on how much QPS and recall are affected.\n: The following scenarios, while less common than non-uniform distribution, can occur: \n\n - **Approximate Uniform Index:** When most of the partitions have the same number of non-zero vectors and the variance of the number of vectors is low, it is an approximate uniform index. `REINDEX` is required if the number vectors in each partition are $\\\u003e 8 \\* average vector$ at `index_creation_time`.\n - **Sparse Index:** A sparse index also occurs where \\\u003e 50% of the partitions are empty. For example, sparse index is created when multiple deletions occur on a table. This scenario causes the vectors to be concentrated in a small number of partitions, which increases the number of vectors in each partition. When this happens, drop the index and recreate it."]]
