From 36b2aae7a22d954a5ad16ac4a68f6977a272165b Mon Sep 17 00:00:00 2001
From: Abdullah <89297042+AzazelSensei@users.noreply.github.com>
Date: Sat, 5 Sep 2026 02:22:15 +0000
Subject: [PATCH] Docs: add Calcite settings examples #4806

Show how to change the Calcite plugin settings and fix the
v3 engine and join doc links.

Signed-off-by: Abdullah <89297042+AzazelSensei@users.noreply.github.com>
---
 docs/user/admin/settings.rst | 151 ++++++++++++++++++++++++++++++++++-
 1 file changed, 149 insertions(+), 2 deletions(-)

diff --git a/docs/user/admin/settings.rst b/docs/user/admin/settings.rst
index cad2b77cbba..be095cc4795 100644
--- a/docs/user/admin/settings.rst
+++ b/docs/user/admin/settings.rst
@@ -1024,8 +1024,35 @@ You can enable Calcite as new query optimizer and execution engine to all coming
 3. This setting is node scope.
 4. This setting can be updated dynamically.
 
-Check `introduce v3 engine <../../../dev/intro-v3-engine.md>`_ for more details.
-Check `join doc <../../ppl/cmd/join.rst>`_ for example.
+Check `introduce v3 engine <../../dev/intro-v3-engine.md>`_ for more details.
+Check `join doc <../ppl/cmd/join.md>`_ for example.
+
+Example
+-------
+
+You can update the setting with a new value like this.
+
+SQL query::
+
+	>> curl -H 'Content-Type: application/json' -X PUT localhost:9200/_plugins/_query/settings -d '{
+	  "transient" : {
+	    "plugins.calcite.enabled" : "true"
+	  }
+	}'
+
+Result set::
+
+	{
+	  "acknowledged" : true,
+	  "persistent" : { },
+	  "transient" : {
+	    "plugins" : {
+	      "calcite" : {
+	        "enabled" : "true"
+	      }
+	    }
+	  }
+	}
 
 plugins.calcite.fallback.allowed
 ================================
@@ -1043,6 +1070,35 @@ If Calcite is enabled, you can use this setting to decide whether to allow fallb
 2. This setting is node scope.
 3. This setting can be updated dynamically.
 
+Example
+-------
+
+You can update the setting with a new value like this.
+
+SQL query::
+
+	>> curl -H 'Content-Type: application/json' -X PUT localhost:9200/_plugins/_query/settings -d '{
+	  "transient" : {
+	    "plugins.calcite.fallback.allowed" : "true"
+	  }
+	}'
+
+Result set::
+
+	{
+	  "acknowledged" : true,
+	  "persistent" : { },
+	  "transient" : {
+	    "plugins" : {
+	      "calcite" : {
+	        "fallback" : {
+	          "allowed" : "true"
+	        }
+	      }
+	    }
+	  }
+	}
+
 plugins.calcite.pushdown.enabled
 ================================
 
@@ -1059,6 +1115,35 @@ If Calcite is enabled, you can use this setting to decide whether to enable the
 2. This setting is node scope.
 3. This setting can be updated dynamically.
 
+Example
+-------
+
+You can update the setting with a new value like this.
+
+SQL query::
+
+	>> curl -H 'Content-Type: application/json' -X PUT localhost:9200/_plugins/_query/settings -d '{
+	  "transient" : {
+	    "plugins.calcite.pushdown.enabled" : "false"
+	  }
+	}'
+
+Result set::
+
+	{
+	  "acknowledged" : true,
+	  "persistent" : { },
+	  "transient" : {
+	    "plugins" : {
+	      "calcite" : {
+	        "pushdown" : {
+	          "enabled" : "false"
+	        }
+	      }
+	    }
+	  }
+	}
+
 plugins.calcite.pushdown.rowcount.estimation.factor
 ===================================================
 
@@ -1075,6 +1160,39 @@ If Calcite pushdown optimization is enabled, this setting is used to estimate th
 2. This setting is node scope.
 3. This setting can be updated dynamically.
 
+Example
+-------
+
+You can update the setting with a new value like this.
+
+SQL query::
+
+	>> curl -H 'Content-Type: application/json' -X PUT localhost:9200/_plugins/_query/settings -d '{
+	  "transient" : {
+	    "plugins.calcite.pushdown.rowcount.estimation.factor" : "0.5"
+	  }
+	}'
+
+Result set::
+
+	{
+	  "acknowledged" : true,
+	  "persistent" : { },
+	  "transient" : {
+	    "plugins" : {
+	      "calcite" : {
+	        "pushdown" : {
+	          "rowcount" : {
+	            "estimation" : {
+	              "factor" : "0.5"
+	            }
+	          }
+	        }
+	      }
+	    }
+	  }
+	}
+
 plugins.calcite.all_join_types.allowed
 ======================================
 
@@ -1090,3 +1208,32 @@ Join types ``inner``, ``left``, ``outer`` (alias of ``left``), ``semi`` and ``an
 1. The default value is false since 3.3.0.
 2. This setting is node scope.
 3. This setting can be updated dynamically.
+
+Example
+-------
+
+You can update the setting with a new value like this.
+
+SQL query::
+
+	>> curl -H 'Content-Type: application/json' -X PUT localhost:9200/_plugins/_query/settings -d '{
+	  "transient" : {
+	    "plugins.calcite.all_join_types.allowed" : "true"
+	  }
+	}'
+
+Result set::
+
+	{
+	  "acknowledged" : true,
+	  "persistent" : { },
+	  "transient" : {
+	    "plugins" : {
+	      "calcite" : {
+	        "all_join_types" : {
+	          "allowed" : "true"
+	        }
+	      }
+	    }
+	  }
+	}