[GitHub] [superset] villebro commented on a change in pull request #15019: docs: jinja

[GitBox <gi...@apache.org>]

villebro commented on a change in pull request #15019:
URL: https://github.com/apache/superset/pull/15019#discussion_r647396170



##########
File path: docs/src/pages/docs/installation/sql_templating.mdx
##########
@@ -87,3 +87,144 @@ FEATURE_FLAGS = {
 
 The available validators and names can be found in
 [sql_validators](https://github.com/apache/superset/tree/master/superset/sql_validators).
+
+### Available Macros
+
+In this section, we'll walkthrough the  pre-defined Jinja macros in Superset.
+
+**Current Username**
+
+The `{{ current_username() }}` macro returns the username of the currently logged in user.
+
+**Current User ID**
+
+The `{{ current_uer_id()}}` macro returns the user_id of the currently logged in user.
+
+**Custom URL Parameters**
+
+The `{{ url_param('custom_variable') }}` macro lets you define arbitrary URL
+parameters and reference them in your SQL code.
+
+Here's a concrete example:
+
+- You write the following query in SQL Lab:
+
+    ```
+    SELECT count(*)
+    FROM ORDERS
+    WHERE country_code = '{{ url_param('countrycode') }}'
+    ```
+
+- You're hosting Superset at the domain www.example.com and you send your
+coworker in Spain the following SQL Lab URL `www.example.com/superset/sqllab?countrycode=ES`
+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:
+
+    ```
+    SELECT count(*)
+    FROM ORDERS
+    WHERE country_code = 'ES'
+    ```
+
+- For your coworker in the USA, the SQL Lab query will be rendered as:
+
+    ```
+    SELECT count(*)
+    FROM ORDERS
+    WHERE country_code = 'US'
+    ```
+
+**Skipping Cache**
+
+If you have enabled caching, you will need to chain the `{{ cache_key_wrapper() }}`
+function to avoid retrieving the
+same current_username or current_user_id for different users.
+
+Here's an example:
+
+- Skip cache when retrieving current user_id:  `{{ cache_key_wrapper(current_user_id()) }}`
+- Skip cache when retrieving current username: `{{ cache_key_wrapper(current_username()) }}`

Review comment:
       `cache_key_wrapper` is nowadays applied by default to `current_user_id` and `current_username` (it can be disabled by calling them with `add_to_cache_keys=False`). See here for more context: https://github.com/apache/superset/blob/efd70077014cbed62e493372d33a2af5237eaadf/superset/jinja_context.py#L105-L131
   
   `cache_key_wrapper` is therefore only needed when it's necessary to wrap your own custom function return values into the cache key. See here for more context: https://github.com/apache/superset/blob/efd70077014cbed62e493372d33a2af5237eaadf/superset/jinja_context.py#L133-L148




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org