From b5ee22ea612591add3d0a7bb1603e231499cedcd Mon Sep 17 00:00:00 2001
From: discord9 <55937128+discord9@users.noreply.github.com>
Date: Thu, 10 Sep 2026 20:28:43 +0800
Subject: [PATCH] docs(query): explain dynamic filter query controls

Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com>
---
 docs/how-to/query-dynamic-filter-options.md | 59 +++++++++++++++++++++
 src/query/src/dist_plan/merge_scan.rs       | 14 -----
 2 files changed, 59 insertions(+), 14 deletions(-)
 create mode 100644 docs/how-to/query-dynamic-filter-options.md

diff --git a/docs/how-to/query-dynamic-filter-options.md b/docs/how-to/query-dynamic-filter-options.md
new file mode 100644
index 0000000000..f2e4fcc32b
--- /dev/null
+++ b/docs/how-to/query-dynamic-filter-options.md
@@ -0,0 +1,59 @@
+# Configure Query Dynamic-Filter Pushdown
+
+Dynamic-filter pushdown can be controlled for an individual query or for a MySQL
+session. The available Boolean options are:
+
+- `enable_dynamic_filter_pushdown` (master switch)
+- `enable_aggregate_dynamic_filter_pushdown`
+- `enable_join_dynamic_filter_pushdown`
+- `enable_topk_dynamic_filter_pushdown`
+
+Values are resolved independently as: query hint, then session setting, then
+the DataFusion default. After resolution, setting the master switch to `false`
+disables every variant, even when a child option is `true`.
+
+## Per-query HTTP hint
+
+Send `x-greptime-hints` on every HTTP SQL request that needs an override. Its
+value is a comma-separated list of `name=value` pairs:
+
+```bash
+curl -G 'http://127.0.0.1:4000/v1/sql' \
+  -H 'x-greptime-hints: enable_dynamic_filter_pushdown=true, enable_topk_dynamic_filter_pushdown=false' \
+  --data-urlencode 'sql=SELECT * FROM my_table'
+```
+
+HTTP requests do not share a session setting. In particular, a `SET` sent in
+one HTTP request does not affect a later HTTP request; send the hint with each
+query that needs it. An invalid Boolean value in a query hint returns an error.
+
+## gRPC metadata hint
+
+For a gRPC request, put the same hint value in its outgoing metadata:
+
+```rust
+request.metadata_mut().insert(
+    "x-greptime-hints",
+    "enable_dynamic_filter_pushdown=true,enable_topk_dynamic_filter_pushdown=false"
+        .parse()?,
+);
+```
+
+## MySQL session setting
+
+On one MySQL connection, use Boolean literals with `SET`, then inspect a named
+option with `SHOW VARIABLES`:
+
+```sql
+SET enable_dynamic_filter_pushdown = true;
+SET enable_topk_dynamic_filter_pushdown = false;
+SHOW VARIABLES enable_dynamic_filter_pushdown;
+```
+
+A per-query hint overrides the corresponding MySQL session setting.
+
+## Deployment requirement
+
+Both the frontend (FE) and datanode (DN) must use versions that support these
+options. This requires no service TOML configuration change and no Protocol
+Buffers schema change.
diff --git a/src/query/src/dist_plan/merge_scan.rs b/src/query/src/dist_plan/merge_scan.rs
index 7ac31c961d..7b2b0f1209 100644
--- a/src/query/src/dist_plan/merge_scan.rs
+++ b/src/query/src/dist_plan/merge_scan.rs
@@ -2197,20 +2197,6 @@ mod tests {
         assert!(!optimizer.enable_topk_dynamic_filter_pushdown);
     }
 
-    #[test]
-    fn materialized_dynamic_filter_extensions_reject_invalid_value_on_dn() {
-        let dn_ctx = Arc::new(
-            QueryContextBuilder::default()
-                .set_extension(
-                    ENABLE_DYNAMIC_FILTER_PUSHDOWN.to_string(),
-                    "invalid".to_string(),
-                )
-                .build(),
-        );
-
-        assert!(DefaultPlanDecoder::new(SessionStateBuilder::new().build(), &dn_ctx).is_err());
-    }
-
     #[test]
     fn remote_dyn_filter_registry_cleanup_waits_for_last_query_scoped_stream_drop() {
         let registry_manager = Arc::new(DynFilterRegistryManager::default());