Best practices for tuning ScaNN indexes in AlloyDB for PostgreSQL
Stay organized with collections
Save and categorize content based on your preferences.
The recommended parameters for the ScaNN index differ depending on
whether you choose to build a two-level or a three-level tree index. This page
provides recommendations about how to tune AlloyDB for PostgreSQL index
parameters for optimal balance between recall and QPS.
To apply recommendations to help you find the optimal values of num_leaves and num_leaves_to_search for your dataset,
follow these recommended steps:
To create the ScaNN index optimized for the following cases set the num_leaves parameter to the following value, where rows is the number of rows in the indexed table:
balanced index build time and quality set num_leaves to sqrt(rows).
quality set num_leaves to rows/100.
Run your test queries, increasing the value of scann.num_of_leaves_to_search, until you achieve your target recall range–for example, 95%. For more information about analyzing your queries, see Analyze your queries.
Take note of the ratio between scann.num_leaves_to_search and
num_leaves that will be used in subsequent steps. This ratio provides an approximation around the dataset that will
help you achieve your target recall.
If you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of scann.pre_reordering_num_neighbors. The default value is set to the value 500 * K where K is the limit that you set in your query.
If your QPS is too low after your queries achieve a target recall, then follow these steps:
Recreate the index, increasing the value of num_leaves and scann.num_leaves_to_search according to the following guidance:
Set num_leaves to a larger factor of the square root of your row count. For example, if the index has num_leaves set to the square root of your row count, try setting it to double the square root. If the value
is already double, then try setting it to triple the square root.
Increase scann.num_leaves_to_search as needed to maintain its ratio with num_leaves,
which you noted in Step 3.
Set num_leaves to a value less than or equal to the row count divided by 100.
Run the test queries again.
While you're running the test queries, experiment with reducing scann.num_leaves_to_search, finding a value that increases QPS while keeping your recall high. Try different values of scann.num_leaves_to_search
without rebuilding the index.
Repeat Step 4 until both the QPS and the recall range have reached acceptable values.
Three-level tree index
In addition to the recommendations for the two-level tree ScaNN index, use the following guidance.
To apply recommendations to find the optimal value of num_leaves and max_num_levels index parameters, follow these steps:
Create the ScaNN index with the following num_leaves and max_num_levels combinations based on your performance goals:
balance index build time & quality: Set max_num_levels as 2 and num_leaves as power(rows, ⅔).
optimize for quality: Set max_num_levels as 2 and num_leaves as rows/100.
Run your test queries. For more information about analyzing queries, see Analyze your queries.
Take note of the ratio between scann.num_leaves_to_search and num_leaves that will be used in subsequent steps. This ratio provides an approximation around the dataset that will help you achieve your target recall.
If you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of scann.pre_reordering_num_neighbors. The default value is set to the value 500 * K where K is the limit that you set in your query.
If your QPS is too low after your queries achieve a target recall, then follow these steps:
Recreate the index, increasing the value of num_leaves and scann.num_leaves_to_search according to the following guidance:
Set num_leaves to a larger factor of the power(rows, ⅔). For example, if the index has num_leaves set to the power(rows, ⅔), try setting it to double the power(rows, ⅔). If the value is already double, then try setting it to triple the power(rows, ⅔).
Increase scann.num_leaves_to_search as needed to maintain its ratio with num_leaves, which you noted in Step 3.
Set num_leaves to a value less than or equal to rows/100.
Run the test queries again. While you're running the test queries, experiment with reducing scann.num_leaves_to_search, finding a value that increases QPS while keeping your recall high. Try different values of scann.num_leaves_to_search without rebuilding the index.
Repeat Step 4 until both the QPS and the recall range have reached acceptable values.
Index maintenance
If your table is prone to frequent updates or insertions, then we recommend periodically reindexing the existing ScaNN index in order to improve the recall accuracy.
You can monitor index metrics to view changes in vector distributions or vector mutations since the index was built, and then reindex accordingly. For more information about metrics, see View Vector index metrics.
[[["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-26 UTC."],[[["\u003cp\u003eThe optimal \u003ccode\u003eScaNN\u003c/code\u003e index parameters depend on whether you're building a two-level or three-level tree index, with adjustments needed for balanced build time, quality, or high-dimensional vectors.\u003c/p\u003e\n"],["\u003cp\u003eFor two-level tree indexes, set \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003esqrt(rows)\u003c/code\u003e for a balanced index or \u003ccode\u003erows/100\u003c/code\u003e for higher quality, then adjust \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e to reach your target recall, and tune both together to increase QPS if needed.\u003c/p\u003e\n"],["\u003cp\u003eFor three-level tree indexes, set \u003ccode\u003emax_num_levels\u003c/code\u003e to \u003ccode\u003e2\u003c/code\u003e and \u003ccode\u003enum_leaves\u003c/code\u003e to \u003ccode\u003epower(rows, ⅔)\u003c/code\u003e for balanced performance or \u003ccode\u003erows/100\u003c/code\u003e for high quality, and then tune \u003ccode\u003enum_leaves\u003c/code\u003e and \u003ccode\u003escann.num_leaves_to_search\u003c/code\u003e to achieve better recall and QPS.\u003c/p\u003e\n"],["\u003cp\u003eIf working with high-dimension vectors, tuning \u003ccode\u003escann.pre_reordering_num_neighbors\u003c/code\u003e can help improve recall.\u003c/p\u003e\n"],["\u003cp\u003ePeriodically reindexing the existing \u003ccode\u003eScaNN\u003c/code\u003e index is recommended for tables with frequent updates or insertions to improve the recall accuracy.\u003c/p\u003e\n"]]],[],null,["# Best practices for tuning ScaNN indexes in AlloyDB for PostgreSQL\n\nThe recommended parameters for the `ScaNN` index differ depending on\nwhether you choose to build a two-level or a three-level tree index. This page\nprovides recommendations about how to tune AlloyDB for PostgreSQL index\nparameters for optimal balance between recall and QPS.\n\nScaNN index creation\n--------------------\n\nFor more information view the [ScaNN Index reference](/alloydb/docs/reference/ai/scann-index-reference).\n\n### Two-level tree index\n\nTo apply recommendations to help you find the optimal values of `num_leaves` and `num_leaves_to_search` for your dataset,\nfollow these recommended steps:\n\n1. To create the `ScaNN` index optimized for the following cases set the `num_leaves` parameter to the following value, where rows is the number of rows in the indexed table:\n - **balanced index build time and quality** set `num_leaves` to `sqrt(rows)`.\n - **quality** set num_leaves to rows/100.\n2. Run your test queries, increasing the value of `scann.num_of_leaves_to_search`, until you achieve your target recall range--for example, 95%. For more information about analyzing your queries, see [Analyze your queries](/alloydb/docs/ai/tune-indexes?resource=scann#explain-analyze).\n3. Take note of the ratio between `scann.num_leaves_to_search` and `num_leaves` that will be used in subsequent steps. This ratio provides an approximation around the dataset that will help you achieve your target recall. \n\n If you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of `scann.pre_reordering_num_neighbors`. The default value is set to the value `500 * K` where `K` is the limit that you set in your query.\n4. If your QPS is too low after your queries achieve a target recall, then follow these steps:\n 1. Recreate the index, increasing the value of `num_leaves` and `scann.num_leaves_to_search` according to the following guidance:\n - Set `num_leaves` to a larger factor of the square root of your row count. For example, if the index has `num_leaves` set to the square root of your row count, try setting it to double the square root. If the value is already double, then try setting it to triple the square root.\n - Increase `scann.num_leaves_to_search` as needed to maintain its ratio with `num_leaves`, which you noted in Step 3.\n - Set `num_leaves` to a value less than or equal to the row count divided by 100.\n 2. Run the test queries again. While you're running the test queries, experiment with reducing `scann.num_leaves_to_search`, finding a value that increases QPS while keeping your recall high. Try different values of `scann.num_leaves_to_search` without rebuilding the index.\n5. Repeat Step 4 until both the QPS and the recall range have reached acceptable values.\n\n### Three-level tree index\n\nIn addition to the recommendations for the two-level tree `ScaNN` index, use the following guidance.\n\nTo apply recommendations to find the optimal value of `num_leaves` and `max_num_levels` index parameters, follow these steps:\n\n1. Create the `ScaNN` index with the following `num_leaves` and `max_num_levels` combinations based on your performance goals:\n\n - **balance index build time \\& quality** : Set `max_num_levels` as `2` and `num_leaves` as `power(rows, ⅔)`.\n - **optimize for quality** : Set `max_num_levels` as `2` and `num_leaves` as `rows/100`.\n2. Run your test queries. For more information about analyzing queries, see [Analyze your queries](/alloydb/docs/ai/tune-indexes?resource=scann#explain-analyze).\n\n3. Take note of the ratio between `scann.num_leaves_to_search` and `num_leaves` that will be used in subsequent steps. This ratio provides an approximation around the dataset that will help you achieve your target recall.\n\nIf you are working with high dimension vectors (500 dimensions or higher) and want to improve recall, then try tuning the value of `scann.pre_reordering_num_neighbors`. The default value is set to the value `500 * K` where `K` is the limit that you set in your query.\n\n1. If your QPS is too low after your queries achieve a target recall, then follow these steps:\n\n - Recreate the index, increasing the value of `num_leaves` and `scann.num_leaves_to_search` according to the following guidance:\n - Set `num_leaves` to a larger factor of the `power(rows, ⅔)`. For example, if the index has `num_leaves` set to the `power(rows, ⅔)`, try setting it to double the `power(rows, ⅔)`. If the value is already double, then try setting it to triple the `power(rows, ⅔)`.\n - Increase `scann.num_leaves_to_search` as needed to maintain its ratio with `num_leaves`, which you noted in Step 3.\n - Set `num_leaves` to a value less than or equal to `rows/100`.\n - Run the test queries again. While you're running the test queries, experiment with reducing `scann.num_leaves_to_search`, finding a value that increases QPS while keeping your recall high. Try different values of `scann.num_leaves_to_search` without rebuilding the index.\n2. Repeat Step 4 until both the QPS and the recall range have reached acceptable values.\n\nIndex maintenance\n-----------------\n\nIf your table is prone to frequent updates or insertions, then we recommend periodically reindexing the existing `ScaNN` index in order to improve the recall accuracy.\nYou can monitor index metrics to view changes in vector distributions or vector mutations since the index was built, and then reindex accordingly. For more information about metrics, see [View Vector index metrics](/alloydb/docs/reference/vector-index-metrics).\n\nWhat's next\n-----------\n\n- [Get started with vector embeddings using AlloyDB AI](https://codelabs.developers.google.com/alloydb-ai-embedding#0)."]]
