[superset] branch master updated: docs: add lost _filters param docs (#23316)

[vi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

villebro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git


The following commit(s) were added to refs/heads/master by this push:
     new eb3d5602c2 docs: add lost _filters param docs (#23316)
eb3d5602c2 is described below

commit eb3d5602c2a0dc7e280576e702540c6e86e83cee
Author: Ville Brofeldt <33...@users.noreply.github.com>
AuthorDate: Thu Mar 9 15:46:21 2023 +0200

    docs: add lost _filters param docs (#23316)
---
 docs/docs/installation/sql-templating.mdx | 47 +++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/docs/docs/installation/sql-templating.mdx b/docs/docs/installation/sql-templating.mdx
index 72c2c0a9ad..768c0e7a53 100644
--- a/docs/docs/installation/sql-templating.mdx
+++ b/docs/docs/installation/sql-templating.mdx
@@ -30,7 +30,9 @@ made available in the Jinja context:
 For example, to add a time range to a virtual dataset, you can write the following:
 
 ```sql
-SELECT * from tbl where dttm_col > '{{ from_dttm }}' and dttm_col < '{{ to_dttm }}'
+SELECT *
+FROM tbl
+WHERE dttm_col > '{{ from_dttm }}' and dttm_col < '{{ to_dttm }}'
 ```
 
 You can also use [Jinja's logic](https://jinja.palletsprojects.com/en/2.11.x/templates/#tests)
@@ -64,6 +66,41 @@ JINJA_CONTEXT_ADDONS = {
 }
 ```
 
+Default values for jinja templates can be specified via `Parameters` menu in the SQL Lab user interface.
+In the UI you can assign a set of parameters as JSON
+
+```json
+{
+  "my_table": "foo"
+}
+```
+The parameters become available in your SQL (example: `SELECT * FROM {{ my_table }}` ) by using Jinja templating syntax.
+SQL Lab template parameters are stored with the dataset as `TEMPLATE PARAMETERS`.
+
+There is a special ``_filters`` parameter which can be used to test filters used in the jinja template.
+
+```json
+{
+  "_filters": [
+    {
+      "col": "action_type",
+      "op": "IN",
+      "val": ["sell", "buy"]
+    }
+  ]
+}
+```
+
+```sql
+SELECT action, count(*) as times
+FROM logs
+WHERE action in {{ filter_values('action_type'))|where_in }}
+GROUP BY action
+```
+
+Note ``_filters`` is not stored with the dataset. It's only used within the SQL Lab UI.
+
+
 Besides default Jinja templating, SQL lab also supports self-defined template processor by setting
 the `CUSTOM_TEMPLATE_PROCESSORS` in your superset configuration. The values in this dictionary
 overwrite the default Jinja template processors of the specified database engine. The example below
@@ -174,7 +211,7 @@ Here's a concrete example:
 
 - You write the following query in SQL Lab:
 
-  ```
+  ```sql
   SELECT count(*)
   FROM ORDERS
   WHERE country_code = '{{ url_param('countrycode') }}'
@@ -185,7 +222,7 @@ Here's a concrete example:
   and your coworker in the USA the following SQL Lab URL `www.example.com/superset/sqllab?countrycode=US`
 - For your coworker in Spain, the SQL Lab query will be rendered as:
 
-  ```
+  ```sql
   SELECT count(*)
   FROM ORDERS
   WHERE country_code = 'ES'
@@ -193,7 +230,7 @@ Here's a concrete example:
 
 - For your coworker in the USA, the SQL Lab query will be rendered as:
 
-  ```
+  ```sql
   SELECT count(*)
   FROM ORDERS
   WHERE country_code = 'US'
@@ -222,7 +259,7 @@ This is useful if:
 
 Here's a concrete example:
 
-```
+```sql
 SELECT action, count(*) as times
 FROM logs
 WHERE