This is an automated email from the ASF dual-hosted git repository.
sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new 8ff5992ea52 IGNITE-27241 Add data staleness check to the statistic
manager (#7141)
8ff5992ea52 is described below
commit 8ff5992ea528b043f8988d468c7701537ca6e540
Author: jinxxxoid <[email protected]>
AuthorDate: Thu Dec 4 11:58:27 2025 +0400
IGNITE-27241 Add data staleness check to the statistic manager (#7141)
---
.../config/cluster-config.adoc | 6 +++++
docs/_docs/sql-tuning/sql-tuning.adoc | 26 ++++++++++++++++++++++
2 files changed, 32 insertions(+)
diff --git a/docs/_docs/administrators-guide/config/cluster-config.adoc
b/docs/_docs/administrators-guide/config/cluster-config.adoc
index 33426ad4104..581a8e3cef5 100644
--- a/docs/_docs/administrators-guide/config/cluster-config.adoc
+++ b/docs/_docs/administrators-guide/config/cluster-config.adoc
@@ -266,6 +266,10 @@ bin/ignite3 cluster config show > cluster-config.txt
{
"ignite" : {
"sql" : {
+ "createTable" : {
+ "minStaleRowsCount" : 500,
+ "staleRowsFraction" : 0.2
+ },
"planner" : {
"estimatedNumberOfQueries" : 1024,
"maxPlanningTimeMillis" : 15000
@@ -278,6 +282,8 @@ bin/ignite3 cluster config show > cluster-config.txt
[cols="1,1,3,1,1,2",opts="header", stripes=none]
|======
|Property|Default|Description|Changeable|Requires Restart|Acceptable Values
+|createTable.minStaleRowsCount|500|Number of updates since the last query plan
update required to automatically recreate query execution plan. Is overriden by
`WITH min stale rows` link:sql-reference/ddl#create-table[parameter]. | Yes |
no | 0 - Long.MAX_VALUE
+|createTable.staleRowsFraction|0.2|Fraction of the table that must change for
query execution plan to be recreated automatically. Is overriden by `WITH stale
rows fraction` link:sql-reference/ddl#create-table[parameter]| Yes | no | 0 - 1
|planner.estimatedNumberOfQueries|1024|The estimated number of unique queries
that are planned to be executed in the cluster in a certain period of time.
Used to optimize internal caches and processes. Optional.| Yes | Yes | 0 -
Integer.MAX_VALUE
|planner.maxPlanningTimeMillis|15000|Query planning timeout in milliseconds.
Plan optimization process stops when the timeout is reached. "0" means no
timeout.| Yes | Yes | 0 - Long.MAX_VALUE
|======
diff --git a/docs/_docs/sql-tuning/sql-tuning.adoc
b/docs/_docs/sql-tuning/sql-tuning.adoc
index 3c2caf90016..7fb30fd1ff9 100644
--- a/docs/_docs/sql-tuning/sql-tuning.adoc
+++ b/docs/_docs/sql-tuning/sql-tuning.adoc
@@ -389,3 +389,29 @@ To force the update earlier, you can use the `sql planner
invalidate-cache` CLI
----
sql planner invalidate-cache --tables=PUBLIC.Person
----
+
+== Plan Cache and Statistics Staleness
+
+Apache Ignite 3 caches SQL execution plans to avoid re-calculating them for
frequently executed queries. These plans depend on table statistics (row
counts, distribution, distinct values) and during rows modifications may become
inefficient and require re-calculation.
+
+Apache Ignite 3 tracks how many rows change and decides when a cached plan
should be re-calculated. When the modification level is high enough, it
refreshes the needed statistics and rebuilds the plan before execution.
+
+=== How Staleness Detection Works
+
+For each table, GridGain tracks the number of modifications and if such
modifications exceed a configurable threshold - statistics are considered stale
and:
+
+- Fresh statistics are automatically recollected
+
+- Cached plans are re-calculated using the updated statistics
+
+- The new plan replaces the outdated cached version
+
+This keeps plans aligned with actual data patterns, especially after bulk
loads or frequent updates.
+
+=== Configuring Staleness Thresholds
+
+Staleness thresholds can be configured in two ways:
+
+- Per-table settings via `CREATE TABLE`
link:https://ignite.apache.org/docs/ignite3/latest/sql-reference/ddl#create-table[syntax]
+
+- Cluster-wide parameters `sql.createTable.staleRowsFraction` and
`sql.createTable.minStaleRowsCount` in the configuration file
