From 2ce15bfd004fd85d3cd6c9e265f672e360aa14ca Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Wed, 26 Nov 2025 11:40:41 -0800 Subject: [PATCH 01/12] Update auto-analyze.md --- .../stable/additional-features/auto-analyze.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/content/stable/additional-features/auto-analyze.md b/docs/content/stable/additional-features/auto-analyze.md index 633c439b2a4e..30c9b5d72c2c 100644 --- a/docs/content/stable/additional-features/auto-analyze.md +++ b/docs/content/stable/additional-features/auto-analyze.md @@ -22,17 +22,16 @@ Similar to [PostgreSQL autovacuum](https://www.postgresql.org/docs/current/routi ## Enable Auto Analyze -Before you can use the feature, you must enable it by setting `ysql_enable_auto_analyze_service` to true on all YB-Masters, and both `ysql_enable_auto_analyze_service` and `ysql_enable_table_mutation_counter` to true on all YB-TServers. +Auto analyze is automatically enabled on YugabyteDB clusters when CBO is enabled (CBO is automatically enabled when a YugabyteDB cluster is created with version >= 2025.2 through YugabyteDB Aeon, YugabyteDB Anywhere or yugabyted). If needed, you can explicitly enable or disable auto analyze by setting `ysql_enable_auto_analyze` on both yb-master and yb-tserver. -For example, to create a single-node [yugabyted](../../reference/configuration/yugabyted/) cluster with Auto Analyze enabled, use the following command: +For example, to create a single-node [yugabyted](../../reference/configuration/yugabyted/) cluster with Auto Analyze explicitly enabled, use the following command: ```sh ./bin/yugabyted start \ - --master_flags "ysql_enable_auto_analyze_service=true" \ - --tserver_flags "ysql_enable_auto_analyze_service=true,ysql_enable_table_mutation_counter=true" + --master_flags "ysql_enable_auto_analyze=true" \ + --tserver_flags "ysql_enable_auto_analyze=true" ``` -Enabling Auto Analyze on an existing cluster requires a rolling restart to set `ysql_enable_auto_analyze_service` and `ysql_enable_table_mutation_counter` to true. ## Configure Auto Analyze @@ -55,8 +54,6 @@ where `` is the current `reltuples` column value stored in the `pg_c On the other hand, `ysql_auto_analyze_scale_factor` is especially important for big tables. If a table has 1,000,000,000 rows, 10% (100,000,000 rows) would have to be mutated before ANALYZE runs. Set the scale factor to a lower value to allow for more frequent statistics collection for such large tables. -In addition, `ysql_auto_analyze_batch_size` controls the maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. The default is 10. Setting this flag to a larger value can potentially reduce the number of YSQL catalog cache refreshes if Auto Analyze decides to ANALYZE many tables in the same database at the same time. - For more information on flags used to configure the Auto Analyze service, refer to [Auto Analyze service flags](../../reference/configuration/yb-tserver/#auto-analyze-service-flags). ## Example From f46d033ba2bff5ed97653679713a739126db6f38 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Wed, 26 Nov 2025 12:11:56 -0800 Subject: [PATCH 02/12] Update auto-analyze.md --- .../additional-features/auto-analyze.md | 23 +++++-------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docs/content/stable/additional-features/auto-analyze.md b/docs/content/stable/additional-features/auto-analyze.md index 30c9b5d72c2c..1acf5e105d65 100644 --- a/docs/content/stable/additional-features/auto-analyze.md +++ b/docs/content/stable/additional-features/auto-analyze.md @@ -35,24 +35,13 @@ For example, to create a single-node [yugabyted](../../reference/configuration/y ## Configure Auto Analyze -You can control how frequently the service updates table statistics using the following YB-TServer flags: +The auto analyze service counts the number of mutations (INSERT, UPDATE, and DELETE) to a table and triggers ANALYZE on the table automatically when certain thresholds are reached. This behavior is determined by the following knobs. -- `ysql_auto_analyze_threshold` - the minimum number of mutations (INSERT, UPDATE, and DELETE) needed to run ANALYZE on a table. Default is 50. -- `ysql_auto_analyze_scale_factor` - a fraction that determines when enough mutations have been accumulated to run ANALYZE for a table. Default is 0.1. +A table needs to accumulate a minimum number of mutations before it is considered for ANALYZE. This minimum is the sum of + * A fraction of the table size - this is controlled by [ysql_auto_analyze_scale_factor](../reference/configuration/yb-tserver/#ysql-auto-analyze-scale-factor). This setting defaults to 0.1, which translates to 10% of the current table size. Current table size is determined by the [`reltuples`].(https://www.postgresql.org/docs/15/catalog-pg-class.html#:~:text=CREATE%20INDEX.-,reltuples,-float4) column value stored in the `pg_class` catalog entry for that table. + * A static count of [ysql_auto_analyze_threshold](../reference/configuration/yb-tserver/#ysql-auto-analyze-threshold) (default 50) mutations. This setting ensures that small tables are not aggressively ANALYZED because the scale factor requirement is easily met. -Increasing either of these flags reduces the frequency of statistics updates. - -If the total number of mutations for a table is greater than its analyze threshold, then the service runs ANALYZE on the table. The analyze threshold of a table is calculated as follows: - -```sh -analyze_threshold = ysql_auto_analyze_threshold + (ysql_auto_analyze_scale_factor * ) -``` - -where `` is the current `reltuples` column value stored in the `pg_class` catalog. - -`ysql_auto_analyze_threshold` is important for small tables. With default settings, if a table has 100 rows and 20 are mutated, ANALYZE won't run as the threshold is not met, even though 20% of the rows are mutated. - -On the other hand, `ysql_auto_analyze_scale_factor` is especially important for big tables. If a table has 1,000,000,000 rows, 10% (100,000,000 rows) would have to be mutated before ANALYZE runs. Set the scale factor to a lower value to allow for more frequent statistics collection for such large tables. +Separately, auto analyze also considers cooldown settings for a table so as to not trigger ANALYZE aggressively. After every run of ANALYZE on a table, a cooldown period is enforced before the next run of ANALYZE on that table, even if the mutation thresholds are met. The cooldown period starts from ysql_auto_analyze_min_cooldown_per_table (default: 10 secs) and exponentially increases to ysql_auto_analyze_max_cooldown_per_table (default: 24 hrs). Cooldown settings do not reset - so in most cases, it is expected that a table that changes frequently only gets ANALYZE'd once every ysql_auto_analyze_max_cooldown_per_table (default: 24 hrs). For more information on flags used to configure the Auto Analyze service, refer to [Auto Analyze service flags](../../reference/configuration/yb-tserver/#auto-analyze-service-flags). @@ -91,4 +80,4 @@ SELECT reltuples FROM pg_class WHERE relname = 'test'; ## Limitations -Because ANALYZE is a DDL statement, it can cause DDL conflicts when run concurrently with other DDL statements. As Auto Analyze runs ANALYZE in the background, you should turn off Auto Analyze if you want to execute DDL statements. You can do this by setting `ysql_enable_auto_analyze_service` to false on all YB-TServers at runtime. +ANALYZE is a technically considered a DDL statement (schema change) and normally conflicts with other [concurrent DDLs](../best-practices-operations/administration/#concurrent-ddl-during-a-ddl-operation). However, when run via the auto analyze service, ANALYZE can run concurrently with other DDL. In this case, ANALYZE is pre-empted by concurrent DDL and will be retried at a later point. However, when [transactional DDL](../explore/transactions/transactional-ddl/) is enabled (off by default), certain kinds of transactions that contain DDL may face a `kConflict` error when a background ANALYZE from the auto analyze service interrupts this transaction. In such cases, it is recommended to disable the auto analyze service explicitly and trigger ANAYZE manually. From 857b95f77404c7e2471d1688b174c0132bc5a90e Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Wed, 26 Nov 2025 13:52:23 -0800 Subject: [PATCH 03/12] Update yb-tserver.md --- .../reference/configuration/yb-tserver.md | 69 ++++++++++--------- 1 file changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index e3ccc7186497..1d1f3e8e2216 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -2131,7 +2131,7 @@ Default: `legacy_mode` Enables the YugabyteDB [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO). Options are `on`, `off`, `legacy_mode`, and `legacy_stats_mode`. -When enabling CBO, you must run ANALYZE on user tables to maintain up-to-date statistics. +When CBO is enabled through this gflag, auto analyze is also enabled automatically. If you disable auto analyze explicitly, you are responsible for periodically running ANALYZE on user tables to maintain up-to-date statistics. For information on using this parameter to configure CBO, refer to [Enable cost-based optimizer](../../../best-practices-operations/ysql-yb-enable-cbo/). @@ -2141,54 +2141,39 @@ For information on using this parameter to configure CBO, refer to [Enable cost- {{< note title="Note" >}} -To fully enable the Auto Analyze service, you need to enable `ysql_enable_auto_analyze_service` on all YB-Masters and YB-TServers, and `ysql_enable_table_mutation_counter` on all YB-TServers. +Auto analyze is automatically enabled by default when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled through gflags. To explicitly control the service, you can set the flag [ysql_enable_auto_analyze] {{< /note >}} See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service-flags). -##### --ysql_enable_auto_analyze_service - -{{% tags/wrap %}} -{{}} -{{}} -{{}} -Default: `false` -{{% /tags/wrap %}} +##### --ysql_enable_auto_analyze Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. -##### --ysql_enable_table_mutation_counter - -{{% tags/wrap %}} - +##### --ysql_auto_analyze_threshold -Default: `false` -{{% /tags/wrap %}} +Default: `50` -Enable per table mutation (INSERT, UPDATE, DELETE) counting. The Auto Analyze service runs ANALYZE when the number of mutations of a table exceeds the threshold determined by the [ysql_auto_analyze_threshold](#ysql-auto-analyze-threshold) and [ysql_auto_analyze_scale_factor](#ysql-auto-analyze-scale-factor) settings. +The minimum number of mutations needed to run ANALYZE on a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). -##### --ysql_auto_analyze_threshold +##### --ysql_auto_analyze_scale_factor -{{% tags/wrap %}} +Default: `0.1` -{{}} -Default: `50` -{{% /tags/wrap %}} +The fraction defining when sufficient mutations have been accumulated to run ANALYZE for a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). -The minimum number of mutations needed to run ANALYZE on a table. +##### --ysql_auto_analyze_min_cooldown_per_table -##### --ysql_auto_analyze_scale_factor +Default: `10000` (10 secs) -{{% tags/wrap %}} +The minimum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). -{{}} -Default: `0.1` -{{% /tags/wrap %}} +##### --ysql_auto_analyze_max_cooldown_per_table -The fraction defining when sufficient mutations have been accumulated to run ANALYZE for a table. +Default: `86400000` (24 hours) -ANALYZE runs when the mutation count exceeds `ysql_auto_analyze_scale_factor * + ysql_auto_analyze_threshold`, where table_size is the value of the `reltuples` column in the `pg_class` catalog. +The maximum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_batch_size @@ -2198,7 +2183,7 @@ ANALYZE runs when the mutation count exceeds `ysql_auto_analyze_scale_factor * < Default: `10` {{% /tags/wrap %}} -The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. +The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. ##### --ysql_cluster_level_mutation_persist_interval_ms @@ -2240,6 +2225,28 @@ Default: `5000` Timeout, in milliseconds, for the node-level mutation reporting RPC to the Auto Analyze service. + +##### --ysql_enable_auto_analyze_service (deprecated) + +{{% tags/wrap %}} +{{}} +{{}} +{{}} +Default: `false` +{{% /tags/wrap %}} + +Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. + +##### --ysql_enable_table_mutation_counter (deprecated) + +{{% tags/wrap %}} + + +Default: `false` +{{% /tags/wrap %}} + +Enable per table mutation (INSERT, UPDATE, DELETE) counting. The Auto Analyze service runs ANALYZE when the number of mutations of a table exceeds the threshold determined by the [ysql_auto_analyze_threshold](#ysql-auto-analyze-threshold) and [ysql_auto_analyze_scale_factor](#ysql-auto-analyze-scale-factor) settings. + ### Advisory lock flags To learn about advisory locks, see [Advisory locks](../../../architecture/transactions/concurrency-control/#advisory-locks). From 76a26ba010f3ce00b2035135f14c602837507768 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Wed, 26 Nov 2025 13:53:57 -0800 Subject: [PATCH 04/12] Update yb-master.md --- docs/content/stable/reference/configuration/yb-master.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 5edc06ec011c..64e8c03f96bc 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1062,7 +1062,13 @@ Default: `true` See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-service-flags). -##### ysql_enable_auto_analyze_service +Auto analyze is automatically enabled by default when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled through gflags. To explicitly control the service, you can set the flag [ysql_enable_auto_analyze]. + +##### ysql_enable_auto_analyze + +{{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. + +##### ysql_enable_auto_analyze_service (deprecated) {{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. From 444bb5d029505d8fea57bae1a28f6ec21e579813 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Wed, 26 Nov 2025 14:01:11 -0800 Subject: [PATCH 05/12] Update auto-analyze.md --- docs/content/stable/additional-features/auto-analyze.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/additional-features/auto-analyze.md b/docs/content/stable/additional-features/auto-analyze.md index 1acf5e105d65..8e7eaf39a97e 100644 --- a/docs/content/stable/additional-features/auto-analyze.md +++ b/docs/content/stable/additional-features/auto-analyze.md @@ -41,7 +41,7 @@ A table needs to accumulate a minimum number of mutations before it is considere * A fraction of the table size - this is controlled by [ysql_auto_analyze_scale_factor](../reference/configuration/yb-tserver/#ysql-auto-analyze-scale-factor). This setting defaults to 0.1, which translates to 10% of the current table size. Current table size is determined by the [`reltuples`].(https://www.postgresql.org/docs/15/catalog-pg-class.html#:~:text=CREATE%20INDEX.-,reltuples,-float4) column value stored in the `pg_class` catalog entry for that table. * A static count of [ysql_auto_analyze_threshold](../reference/configuration/yb-tserver/#ysql-auto-analyze-threshold) (default 50) mutations. This setting ensures that small tables are not aggressively ANALYZED because the scale factor requirement is easily met. -Separately, auto analyze also considers cooldown settings for a table so as to not trigger ANALYZE aggressively. After every run of ANALYZE on a table, a cooldown period is enforced before the next run of ANALYZE on that table, even if the mutation thresholds are met. The cooldown period starts from ysql_auto_analyze_min_cooldown_per_table (default: 10 secs) and exponentially increases to ysql_auto_analyze_max_cooldown_per_table (default: 24 hrs). Cooldown settings do not reset - so in most cases, it is expected that a table that changes frequently only gets ANALYZE'd once every ysql_auto_analyze_max_cooldown_per_table (default: 24 hrs). +Separately, auto analyze also considers cooldown settings for a table so as to not trigger ANALYZE aggressively. After every run of ANALYZE on a table, a cooldown period is enforced before the next run of ANALYZE on that table, even if the mutation thresholds are met. The cooldown period starts from [ysql_auto_analyze_min_cooldown_per_table](../reference/configuration/yb-tserver/#ysql_auto_analyze_min_cooldown_per_table) (default: 10 secs) and exponentially increases to [ysql_auto_analyze_max_cooldown_per_table](../reference/configuration/yb-tserver/#ysql_auto_analyze_max_cooldown_per_table) (default: 24 hrs). Cooldown values for a table do not reset - so in most cases, it is expected that, after a while, a frequently updated table only gets ANALYZE'd once every ysql_auto_analyze_max_cooldown_per_table period (default: 24 hrs). For more information on flags used to configure the Auto Analyze service, refer to [Auto Analyze service flags](../../reference/configuration/yb-tserver/#auto-analyze-service-flags). @@ -80,4 +80,4 @@ SELECT reltuples FROM pg_class WHERE relname = 'test'; ## Limitations -ANALYZE is a technically considered a DDL statement (schema change) and normally conflicts with other [concurrent DDLs](../best-practices-operations/administration/#concurrent-ddl-during-a-ddl-operation). However, when run via the auto analyze service, ANALYZE can run concurrently with other DDL. In this case, ANALYZE is pre-empted by concurrent DDL and will be retried at a later point. However, when [transactional DDL](../explore/transactions/transactional-ddl/) is enabled (off by default), certain kinds of transactions that contain DDL may face a `kConflict` error when a background ANALYZE from the auto analyze service interrupts this transaction. In such cases, it is recommended to disable the auto analyze service explicitly and trigger ANAYZE manually. +ANALYZE is technically considered a DDL statement (schema change) and normally conflicts with other [concurrent DDLs](../best-practices-operations/administration/#concurrent-ddl-during-a-ddl-operation). However, when run via the auto analyze service, ANALYZE can run concurrently with other DDL. In this case, ANALYZE is pre-empted by concurrent DDL and will be retried at a later point. However, when [transactional DDL](../explore/transactions/transactional-ddl/) is enabled (off by default), certain kinds of transactions that contain DDL may face a `kConflict` error when a background ANALYZE from the auto analyze service interrupts this transaction. In such cases, it is recommended to disable the auto analyze service explicitly and trigger ANALYZE manually. Issue {{}} tracks this scenario. From 9e889a69d83643c75f51ae5539e2581290e804c1 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Thu, 27 Nov 2025 11:23:12 -0500 Subject: [PATCH 06/12] edits and remove ea tags --- .../additional-features/auto-analyze.md | 20 ++++++++++--------- .../reference/configuration/yb-master.md | 6 +++--- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/content/stable/additional-features/auto-analyze.md b/docs/content/stable/additional-features/auto-analyze.md index 8e7eaf39a97e..f001208feadd 100644 --- a/docs/content/stable/additional-features/auto-analyze.md +++ b/docs/content/stable/additional-features/auto-analyze.md @@ -4,8 +4,6 @@ headerTitle: Auto Analyze service linkTitle: Auto Analyze description: Use the Auto Analyze service to keep table statistics up to date headcontent: Keep table statistics up to date automatically -tags: - feature: early-access menu: stable: identifier: auto-analyze @@ -22,7 +20,11 @@ Similar to [PostgreSQL autovacuum](https://www.postgresql.org/docs/current/routi ## Enable Auto Analyze -Auto analyze is automatically enabled on YugabyteDB clusters when CBO is enabled (CBO is automatically enabled when a YugabyteDB cluster is created with version >= 2025.2 through YugabyteDB Aeon, YugabyteDB Anywhere or yugabyted). If needed, you can explicitly enable or disable auto analyze by setting `ysql_enable_auto_analyze` on both yb-master and yb-tserver. +For new universes running v2025.2 or later, Auto Analyze is enabled by default when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. + +In addition, when upgrading a deployment to v2025.2 or later, if the universe has the cost-based optimizer enabled (`on`), YugabyteDB will enable Auto Analyze. + +You can explicitly enable or disable auto analyze by setting `ysql_enable_auto_analyze` on both yb-master and yb-tserver. For example, to create a single-node [yugabyted](../../reference/configuration/yugabyted/) cluster with Auto Analyze explicitly enabled, use the following command: @@ -32,16 +34,16 @@ For example, to create a single-node [yugabyted](../../reference/configuration/y --tserver_flags "ysql_enable_auto_analyze=true" ``` - ## Configure Auto Analyze -The auto analyze service counts the number of mutations (INSERT, UPDATE, and DELETE) to a table and triggers ANALYZE on the table automatically when certain thresholds are reached. This behavior is determined by the following knobs. +The auto analyze service counts the number of mutations (INSERT, UPDATE, and DELETE) to a table and triggers ANALYZE on the table automatically when certain thresholds are reached. You can configure this behavior using the following settings. + +A table needs to accumulate a minimum number of mutations before it is considered for ANALYZE. This minimum is the sum of: -A table needs to accumulate a minimum number of mutations before it is considered for ANALYZE. This minimum is the sum of - * A fraction of the table size - this is controlled by [ysql_auto_analyze_scale_factor](../reference/configuration/yb-tserver/#ysql-auto-analyze-scale-factor). This setting defaults to 0.1, which translates to 10% of the current table size. Current table size is determined by the [`reltuples`].(https://www.postgresql.org/docs/15/catalog-pg-class.html#:~:text=CREATE%20INDEX.-,reltuples,-float4) column value stored in the `pg_class` catalog entry for that table. - * A static count of [ysql_auto_analyze_threshold](../reference/configuration/yb-tserver/#ysql-auto-analyze-threshold) (default 50) mutations. This setting ensures that small tables are not aggressively ANALYZED because the scale factor requirement is easily met. +- A fraction of the table size. This is controlled by [ysql_auto_analyze_scale_factor](../../reference/configuration/yb-tserver/#ysql-auto-analyze-scale-factor). This setting defaults to 0.1, which translates to 10% of the current table size. Current table size is determined by the [reltuples](https://www.postgresql.org/docs/15/catalog-pg-class.html#:~:text=CREATE%20INDEX.-,reltuples,-float4) column value stored in the `pg_class` catalog entry for that table. +- A static count of [ysql_auto_analyze_threshold](../../reference/configuration/yb-tserver/#ysql-auto-analyze-threshold) (default 50) mutations. This setting ensures that small tables are not aggressively ANALYZED because the scale factor requirement is easily met. -Separately, auto analyze also considers cooldown settings for a table so as to not trigger ANALYZE aggressively. After every run of ANALYZE on a table, a cooldown period is enforced before the next run of ANALYZE on that table, even if the mutation thresholds are met. The cooldown period starts from [ysql_auto_analyze_min_cooldown_per_table](../reference/configuration/yb-tserver/#ysql_auto_analyze_min_cooldown_per_table) (default: 10 secs) and exponentially increases to [ysql_auto_analyze_max_cooldown_per_table](../reference/configuration/yb-tserver/#ysql_auto_analyze_max_cooldown_per_table) (default: 24 hrs). Cooldown values for a table do not reset - so in most cases, it is expected that, after a while, a frequently updated table only gets ANALYZE'd once every ysql_auto_analyze_max_cooldown_per_table period (default: 24 hrs). +Separately, Auto Analyze also considers cooldown settings for a table so as to not trigger ANALYZE aggressively. After every run of ANALYZE on a table, a cooldown period is enforced before the next run of ANALYZE on that table, even if the mutation thresholds are met. The cooldown period starts from [ysql_auto_analyze_min_cooldown_per_table](../../reference/configuration/yb-tserver/#ysql_auto_analyze_min_cooldown_per_table) (default: 10 seconds) and exponentially increases to [ysql_auto_analyze_max_cooldown_per_table](../../reference/configuration/yb-tserver/#ysql_auto_analyze_max_cooldown_per_table) (default: 24 hours). Cooldown values for a table do not reset. This means that in most cases, it is expected that, after a while, a frequently updated table is only analyzed once every `ysql_auto_analyze_max_cooldown_per_table` period. For more information on flags used to configure the Auto Analyze service, refer to [Auto Analyze service flags](../../reference/configuration/yb-tserver/#auto-analyze-service-flags). diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 64e8c03f96bc..5dfce1ab3334 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1058,7 +1058,7 @@ Default: `true` ## Auto Analyze service flags -{{}}To learn about the Auto Analyze service, see [Auto Analyze service](../../../additional-features/auto-analyze). +To learn about the Auto Analyze service, see [Auto Analyze service](../../../additional-features/auto-analyze). See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-service-flags). @@ -1066,11 +1066,11 @@ Auto analyze is automatically enabled by default when the [cost-based optimizer] ##### ysql_enable_auto_analyze -{{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. +Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. ##### ysql_enable_auto_analyze_service (deprecated) -{{}}Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. +Use ysql_enable_auto_analyze instead. Default: false From 63816f6593b753d2b50c598a4b7e3c4eb8f044ac Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Thu, 27 Nov 2025 13:26:46 -0500 Subject: [PATCH 07/12] format --- .../reference/configuration/yb-master.md | 10 +++-- .../reference/configuration/yb-tserver.md | 38 ++++++++++++++----- 2 files changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 5dfce1ab3334..1d990c441711 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1060,20 +1060,22 @@ Default: `true` To learn about the Auto Analyze service, see [Auto Analyze service](../../../additional-features/auto-analyze). -See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-service-flags). +Auto analyze is automatically enabled when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled by setting the [yb_enable_cbo](../tb-tserver/#yb_enable_cbo) flag to `on`. + +To explicitly control the service, you can set the `ysql_enable_auto_analyze` flag. -Auto analyze is automatically enabled by default when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled through gflags. To explicitly control the service, you can set the flag [ysql_enable_auto_analyze]. +See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-service-flags). ##### ysql_enable_auto_analyze Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. +Default: false + ##### ysql_enable_auto_analyze_service (deprecated) Use ysql_enable_auto_analyze instead. -Default: false - ## Advisory lock flags To learn about advisory locks, see [Advisory locks](../../../architecture/transactions/concurrency-control/#advisory-locks). diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index 1d1f3e8e2216..703bf4dea366 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -2131,47 +2131,69 @@ Default: `legacy_mode` Enables the YugabyteDB [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO). Options are `on`, `off`, `legacy_mode`, and `legacy_stats_mode`. -When CBO is enabled through this gflag, auto analyze is also enabled automatically. If you disable auto analyze explicitly, you are responsible for periodically running ANALYZE on user tables to maintain up-to-date statistics. +When CBO is enabled (set to `on`), [auto analyze](#auto-analyze-service-flags) is also enabled automatically. If you disable auto analyze explicitly, you are responsible for periodically running ANALYZE on user tables to maintain up-to-date statistics. For information on using this parameter to configure CBO, refer to [Enable cost-based optimizer](../../../best-practices-operations/ysql-yb-enable-cbo/). ### Auto Analyze service flags -{{}}To learn about the Auto Analyze service, see [Auto Analyze service](../../../additional-features/auto-analyze). +To learn about the Auto Analyze service, see [Auto Analyze service](../../../additional-features/auto-analyze). -{{< note title="Note" >}} +Auto analyze is automatically enabled when the [cost-based optimizer](../../../best-practices-operations/ysql-yb-enable-cbo/) (CBO) is enabled ([yb_enable_cbo](#yb_enable_cbo) is set to `on`). -Auto analyze is automatically enabled by default when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled through gflags. To explicitly control the service, you can set the flag [ysql_enable_auto_analyze] +In v2025.2 and later, CBO and Auto Analyze are enabled by default in new universes when you deploy using yugabyted, YugabyteDB Anywhere, or YugabyteDB Aeon. In addition, when upgrading a deployment to v2025.2 or later, if the universe has the cost-based optimizer enabled (`on`), YugabyteDB will enable Auto Analyze. -{{< /note >}} +To explicitly control the service, you can set the `ysql_enable_auto_analyze` flag. See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service-flags). ##### --ysql_enable_auto_analyze +{{% tags/wrap %}} +{{}} +{{}} +Default: `false` +{{% /tags/wrap %}} + Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. ##### --ysql_auto_analyze_threshold +{{% tags/wrap %}} + +{{}} Default: `50` +{{% /tags/wrap %}} The minimum number of mutations needed to run ANALYZE on a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_scale_factor +{{% tags/wrap %}} + +{{}} Default: `0.1` +{{% /tags/wrap %}} The fraction defining when sufficient mutations have been accumulated to run ANALYZE for a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_min_cooldown_per_table -Default: `10000` (10 secs) +{{% tags/wrap %}} + +{{}} +Default: `10000` (10 seconds) +{{% /tags/wrap %}} The minimum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_max_cooldown_per_table +{{% tags/wrap %}} + +{{}} Default: `86400000` (24 hours) +{{% /tags/wrap %}} The maximum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). @@ -2183,7 +2205,7 @@ The maximum duration (in milliseconds) for the cooldown period between successiv Default: `10` {{% /tags/wrap %}} -The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. +The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. ##### --ysql_cluster_level_mutation_persist_interval_ms @@ -2225,11 +2247,9 @@ Default: `5000` Timeout, in milliseconds, for the node-level mutation reporting RPC to the Auto Analyze service. - ##### --ysql_enable_auto_analyze_service (deprecated) {{% tags/wrap %}} -{{}} {{}} {{}} Default: `false` From 960225f9d0947994761353436de05b62ab150af4 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Mon, 1 Dec 2025 18:37:20 -0800 Subject: [PATCH 08/12] Update auto-analyze.md --- docs/content/stable/additional-features/auto-analyze.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/content/stable/additional-features/auto-analyze.md b/docs/content/stable/additional-features/auto-analyze.md index f001208feadd..03e6172569dd 100644 --- a/docs/content/stable/additional-features/auto-analyze.md +++ b/docs/content/stable/additional-features/auto-analyze.md @@ -24,13 +24,12 @@ For new universes running v2025.2 or later, Auto Analyze is enabled by default w In addition, when upgrading a deployment to v2025.2 or later, if the universe has the cost-based optimizer enabled (`on`), YugabyteDB will enable Auto Analyze. -You can explicitly enable or disable auto analyze by setting `ysql_enable_auto_analyze` on both yb-master and yb-tserver. +You can explicitly enable or disable auto analyze by setting `ysql_enable_auto_analyze` on all yb-tservers. For example, to create a single-node [yugabyted](../../reference/configuration/yugabyted/) cluster with Auto Analyze explicitly enabled, use the following command: ```sh ./bin/yugabyted start \ - --master_flags "ysql_enable_auto_analyze=true" \ --tserver_flags "ysql_enable_auto_analyze=true" ``` From 529e479141be3e1c424c37f9773e9075046ff973 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Mon, 1 Dec 2025 18:39:16 -0800 Subject: [PATCH 09/12] Update yb-master.md --- .../stable/reference/configuration/yb-master.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/content/stable/reference/configuration/yb-master.md b/docs/content/stable/reference/configuration/yb-master.md index 1d990c441711..1e9d3d10d145 100644 --- a/docs/content/stable/reference/configuration/yb-master.md +++ b/docs/content/stable/reference/configuration/yb-master.md @@ -1062,19 +1062,9 @@ To learn about the Auto Analyze service, see [Auto Analyze service](../../../add Auto analyze is automatically enabled when the [cost-based optimizer](../../../architecture/query-layer/planner-optimizer/) (CBO) is enabled by setting the [yb_enable_cbo](../tb-tserver/#yb_enable_cbo) flag to `on`. -To explicitly control the service, you can set the `ysql_enable_auto_analyze` flag. - -See also [Auto Analyze Service TServer flags](../yb-tserver/#auto-analyze-service-flags). - -##### ysql_enable_auto_analyze - -Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. - -Default: false - ##### ysql_enable_auto_analyze_service (deprecated) -Use ysql_enable_auto_analyze instead. +Use [ysql_enable_auto_analyze](../yb-tserver#ysql_enable_auto_analyze) on yb-tservers instead. ## Advisory lock flags From effbbe811fdf6739604131264d74de08174640cc Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Mon, 1 Dec 2025 18:45:10 -0800 Subject: [PATCH 10/12] Update yb-tserver.md --- .../reference/configuration/yb-tserver.md | 45 +++---------------- 1 file changed, 6 insertions(+), 39 deletions(-) diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index 703bf4dea366..3c5f6868799e 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -2149,101 +2149,68 @@ See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service- ##### --ysql_enable_auto_analyze -{{% tags/wrap %}} -{{}} -{{}} Default: `false` -{{% /tags/wrap %}} Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. ##### --ysql_auto_analyze_threshold -{{% tags/wrap %}} - -{{}} Default: `50` -{{% /tags/wrap %}} The minimum number of mutations needed to run ANALYZE on a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_scale_factor -{{% tags/wrap %}} - -{{}} Default: `0.1` -{{% /tags/wrap %}} The fraction defining when sufficient mutations have been accumulated to run ANALYZE for a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_min_cooldown_per_table -{{% tags/wrap %}} -{{}} Default: `10000` (10 seconds) -{{% /tags/wrap %}} The minimum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_max_cooldown_per_table -{{% tags/wrap %}} - -{{}} Default: `86400000` (24 hours) -{{% /tags/wrap %}} The maximum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). -##### --ysql_auto_analyze_batch_size +##### --ysql_auto_analyze_cooldown_per_table_scale_factor -{{% tags/wrap %}} +Default: `2` + +The exponential factor by which the per table cooldown period is scaled up each time from the value ysql_auto_analyze_min_cooldown_per_table to the value ysql_auto_analyze_max_cooldown_per_table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). + +##### --ysql_auto_analyze_batch_size -{{}} Default: `10` -{{% /tags/wrap %}} The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. ##### --ysql_cluster_level_mutation_persist_interval_ms -{{% tags/wrap %}} - -{{}} Default: `10000` -{{% /tags/wrap %}} Interval at which the reported node level table mutation counts are persisted to the underlying auto-analyze mutations table. ##### --ysql_cluster_level_mutation_persist_rpc_timeout_ms -{{% tags/wrap %}} - -{{}} Default: `10000` -{{% /tags/wrap %}} Timeout for the RPCs used to persist mutation counts in the auto-analyze mutations table. ##### --ysql_node_level_mutation_reporting_interval_ms -{{% tags/wrap %}} - -{{}} Default: `5000` -{{% /tags/wrap %}} Interval, in milliseconds, at which the node-level table mutation counts are sent to the Auto Analyze service, which tracks table mutation counts at the cluster level. ##### --ysql_node_level_mutation_reporting_timeout_ms -{{% tags/wrap %}} - -{{}} Default: `5000` -{{% /tags/wrap %}} Timeout, in milliseconds, for the node-level mutation reporting RPC to the Auto Analyze service. From 35ac7d650a3ef02f3edf4745ddbd17d75a995231 Mon Sep 17 00:00:00 2001 From: Sanketh I Date: Mon, 1 Dec 2025 18:49:19 -0800 Subject: [PATCH 11/12] Update yb-tserver.md --- docs/content/stable/reference/configuration/yb-tserver.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index 3c5f6868799e..a80af856251f 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -2145,8 +2145,6 @@ In v2025.2 and later, CBO and Auto Analyze are enabled by default in new univers To explicitly control the service, you can set the `ysql_enable_auto_analyze` flag. -See also [Auto Analyze Service Master flags](../yb-master/#auto-analyze-service-flags). - ##### --ysql_enable_auto_analyze Default: `false` From e7af7234ddcda5a9449f5a7b9fd930d242578c89 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 9 Dec 2025 00:23:57 -0500 Subject: [PATCH 12/12] format --- .../reference/configuration/yb-tserver.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/content/stable/reference/configuration/yb-tserver.md b/docs/content/stable/reference/configuration/yb-tserver.md index a80af856251f..fbdc59ded35b 100644 --- a/docs/content/stable/reference/configuration/yb-tserver.md +++ b/docs/content/stable/reference/configuration/yb-tserver.md @@ -2147,68 +2147,100 @@ To explicitly control the service, you can set the `ysql_enable_auto_analyze` fl ##### --ysql_enable_auto_analyze +{{% tags/wrap %}} + Default: `false` +{{% /tags/wrap %}} Enable the Auto Analyze service, which automatically runs ANALYZE to update table statistics for tables that have changed more than a configurable threshold. ##### --ysql_auto_analyze_threshold +{{% tags/wrap %}} + Default: `50` +{{% /tags/wrap %}} The minimum number of mutations needed to run ANALYZE on a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_scale_factor +{{% tags/wrap %}} + Default: `0.1` +{{% /tags/wrap %}} The fraction defining when sufficient mutations have been accumulated to run ANALYZE for a table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_min_cooldown_per_table +{{% tags/wrap %}} Default: `10000` (10 seconds) +{{% /tags/wrap %}} The minimum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_max_cooldown_per_table +{{% tags/wrap %}} + Default: `86400000` (24 hours) +{{% /tags/wrap %}} The maximum duration (in milliseconds) for the cooldown period between successive runs of ANALYZE on a specific table by the auto analyze service. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_cooldown_per_table_scale_factor +{{% tags/wrap %}} + Default: `2` +{{% /tags/wrap %}} The exponential factor by which the per table cooldown period is scaled up each time from the value ysql_auto_analyze_min_cooldown_per_table to the value ysql_auto_analyze_max_cooldown_per_table. For more details, see [Auto Analyze service](../../../additional-features/auto-analyze). ##### --ysql_auto_analyze_batch_size +{{% tags/wrap %}} + Default: `10` +{{% /tags/wrap %}} The maximum number of tables the Auto Analyze service tries to analyze in a single ANALYZE statement. ##### --ysql_cluster_level_mutation_persist_interval_ms +{{% tags/wrap %}} + Default: `10000` +{{% /tags/wrap %}} Interval at which the reported node level table mutation counts are persisted to the underlying auto-analyze mutations table. ##### --ysql_cluster_level_mutation_persist_rpc_timeout_ms +{{% tags/wrap %}} + Default: `10000` +{{% /tags/wrap %}} Timeout for the RPCs used to persist mutation counts in the auto-analyze mutations table. ##### --ysql_node_level_mutation_reporting_interval_ms +{{% tags/wrap %}} + Default: `5000` +{{% /tags/wrap %}} Interval, in milliseconds, at which the node-level table mutation counts are sent to the Auto Analyze service, which tracks table mutation counts at the cluster level. ##### --ysql_node_level_mutation_reporting_timeout_ms +{{% tags/wrap %}} + Default: `5000` +{{% /tags/wrap %}} Timeout, in milliseconds, for the node-level mutation reporting RPC to the Auto Analyze service.