| {"version":3,"sources":["webpack:///./src/pages/docs/installation/sql_templating.mdx"],"names":["_frontmatter","layoutProps","MDXLayout","DefaultLayout","MDXContent","components","props","mdxType","parentName","isMDXComponent"],"mappings":"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","file":"component---src-pages-docs-installation-sql-templating-mdx-176fbef389eef74e8b00.js","sourcesContent":["import * as React from 'react'\n /* @jsx mdx */\nimport { mdx } from '@mdx-js/react';\n/* @jsxRuntime classic */\n\n/* @jsx mdx */\n\nimport DefaultLayout from \"/home/runner/work/superset/superset/docs/node_modules/gatsby-theme-docz/src/base/Layout.js\";\nexport const _frontmatter = {};\nconst layoutProps = {\n _frontmatter\n};\nconst MDXLayout = DefaultLayout;\nexport default function MDXContent({\n components,\n ...props\n}) {\n return <MDXLayout {...layoutProps} {...props} components={components} mdxType=\"MDXLayout\">\n\n\n <h2 {...{\n \"id\": \"sql-templating\"\n }}>{`SQL Templating`}</h2>\n <h3 {...{\n \"id\": \"jinja-templates\"\n }}>{`Jinja Templates`}</h3>\n <p>{`SQL Lab supports `}<a parentName=\"p\" {...{\n \"href\": \"https://jinja.palletsprojects.com/en/2.11.x/\"\n }}>{`Jinja templating`}</a>{` in queries. You'll\nneed to to overload the default Jinja context in your environment by defining the\nJINJA_CONTEXT_ADDONS in your superset configuration (`}<inlineCode parentName=\"p\">{`superset_config.py`}</inlineCode>{`). Objects referenced in\nthis dictionary are made available for users to use in their SQL code.`}</p>\n <pre><code parentName=\"pre\" {...{\n \"className\": \"language-python\"\n }}>{`JINJA_CONTEXT_ADDONS = {\n 'my_crazy_macro': lambda x: x*2,\n}\n`}</code></pre>\n <p>{`Besides default Jinja templating, SQL lab also supports self-defined template processor by setting\nthe `}<inlineCode parentName=\"p\">{`CUSTOM_TEMPLATE_PROCESSORS`}</inlineCode>{` in your superset configuration. The values in this dictionary\noverwrite the default Jinja template processors of the specified database engine. The example below\nconfigures a custom presto template processor which implements its own logic of processing macro\ntemplate with regex parsing. It uses the `}<inlineCode parentName=\"p\">{`$`}</inlineCode>{` style macro instead of `}<inlineCode parentName=\"p\">{`{{ }}`}</inlineCode>{` style in Jinja\ntemplating.`}</p>\n <p>{`By configuring it with `}<inlineCode parentName=\"p\">{`CUSTOM_TEMPLATE_PROCESSORS`}</inlineCode>{`, a SQL template on a presto database is\nprocessed by the custom one rather than the default one.`}</p>\n <pre><code parentName=\"pre\" {...{\n \"className\": \"language-python\"\n }}>{`def DATE(\n ts: datetime, day_offset: SupportsInt = 0, hour_offset: SupportsInt = 0\n) -> str:\n \"\"\"Current day as a string.\"\"\"\n day_offset, hour_offset = int(day_offset), int(hour_offset)\n offset_day = (ts + timedelta(days=day_offset, hours=hour_offset)).date()\n return str(offset_day)\n\nclass CustomPrestoTemplateProcessor(PrestoTemplateProcessor):\n \"\"\"A custom presto template processor.\"\"\"\n\n engine = \"presto\"\n\n def process_template(self, sql: str, **kwargs) -> str:\n \"\"\"Processes a sql template with $ style macro using regex.\"\"\"\n # Add custom macros functions.\n macros = {\n \"DATE\": partial(DATE, datetime.utcnow())\n } # type: Dict[str, Any]\n # Update with macros defined in context and kwargs.\n macros.update(self.context)\n macros.update(kwargs)\n\n def replacer(match):\n \"\"\"Expand $ style macros with corresponding function calls.\"\"\"\n macro_name, args_str = match.groups()\n args = [a.strip() for a in args_str.split(\",\")]\n if args == [\"\"]:\n args = []\n f = macros[macro_name[1:]]\n return f(*args)\n\n macro_names = [\"$\" + name for name in macros.keys()]\n pattern = r\"(%s)\\\\s*\\\\(([^()]*)\\\\)\" % \"|\".join(map(re.escape, macro_names))\n return re.sub(pattern, replacer, sql)\n\nCUSTOM_TEMPLATE_PROCESSORS = {\n CustomPrestoTemplateProcessor.engine: CustomPrestoTemplateProcessor\n}\n`}</code></pre>\n <p>{`SQL Lab also includes a live query validation feature with pluggable backends. You can configure\nwhich validation implementation is used with which database engine by adding a block like the\nfollowing to your configuration file:`}</p>\n <pre><code parentName=\"pre\" {...{\n \"className\": \"language-python\"\n }}>{`FEATURE_FLAGS = {\n 'SQL_VALIDATORS_BY_ENGINE': {\n 'presto': 'PrestoDBSQLValidator',\n }\n}\n`}</code></pre>\n <p>{`The available validators and names can be found in\n`}<a parentName=\"p\" {...{\n \"href\": \"https://github.com/apache/superset/tree/master/superset/sql_validators\"\n }}>{`sql_validators`}</a>{`.`}</p>\n <h3 {...{\n \"id\": \"available-macros\"\n }}>{`Available Macros`}</h3>\n <p>{`In this section, we'll walkthrough the pre-defined Jinja macros in Superset.`}</p>\n <p><strong parentName=\"p\">{`Current Username`}</strong></p>\n <p>{`The `}<inlineCode parentName=\"p\">{`{{ current_username() }}`}</inlineCode>{` macro returns the username of the currently logged in user.`}</p>\n <p>{`If you have caching enabled in your Superset configuration, then by defaul the the `}<inlineCode parentName=\"p\">{`username`}</inlineCode>{` value will be used\nby Superset when calculating the cache key. A cache key is a unique identifer that determines if there's a\ncache hit in the future and Superset can retrieve cached data.`}</p>\n <p>{`You can disable the inclusion of the `}<inlineCode parentName=\"p\">{`username`}</inlineCode>{` value in the calculation of the\ncache key by adding the following parameter to your Jinja code:`}</p>\n <pre><code parentName=\"pre\" {...{}}>{`{{ current_username(add_to_cache_keys=False) }}\n`}</code></pre>\n <p><strong parentName=\"p\">{`Current User ID`}</strong></p>\n <p>{`The `}<inlineCode parentName=\"p\">{`{{ current_user_id()}}`}</inlineCode>{` macro returns the user_id of the currently logged in user.`}</p>\n <p>{`If you have caching enabled in your Superset configuration, then by defaul the the `}<inlineCode parentName=\"p\">{`user_id`}</inlineCode>{` value will be used\nby Superset when calculating the cache key. A cache key is a unique identifer that determines if there's a\ncache hit in the future and Superset can retrieve cached data.`}</p>\n <p>{`You can disable the inclusion of the `}<inlineCode parentName=\"p\">{`user_id`}</inlineCode>{` value in the calculation of the\ncache key by adding the following parameter to your Jinja code:`}</p>\n <pre><code parentName=\"pre\" {...{}}>{`{{ current_user_id(add_to_cache_keys=False) }}\n`}</code></pre>\n <p><strong parentName=\"p\">{`Custom URL Parameters`}</strong></p>\n <p>{`The `}<inlineCode parentName=\"p\">{`{{ url_param('custom_variable') }}`}</inlineCode>{` macro lets you define arbitrary URL\nparameters and reference them in your SQL code.`}</p>\n <p>{`Here's a concrete example:`}</p>\n <ul>\n <li parentName=\"ul\">\n <p parentName=\"li\">{`You write the following query in SQL Lab:`}</p>\n <pre parentName=\"li\"><code parentName=\"pre\" {...{}}>{`SELECT count(*)\nFROM ORDERS\nWHERE country_code = '{{ url_param('countrycode') }}'\n`}</code></pre>\n </li>\n <li parentName=\"ul\">\n <p parentName=\"li\">{`You're hosting Superset at the domain `}<a parentName=\"p\" {...{\n \"href\": \"http://www.example.com\"\n }}>{`www.example.com`}</a>{` and you send your\ncoworker in Spain the following SQL Lab URL `}<inlineCode parentName=\"p\">{`www.example.com/superset/sqllab?countrycode=ES`}</inlineCode>{`\nand your coworker in the USA the following SQL Lab URL `}<inlineCode parentName=\"p\">{`www.example.com/superset/sqllab?countrycode=US`}</inlineCode></p>\n </li>\n <li parentName=\"ul\">\n <p parentName=\"li\">{`For your coworker in Spain, the SQL Lab query will be rendered as:`}</p>\n <pre parentName=\"li\"><code parentName=\"pre\" {...{}}>{`SELECT count(*)\nFROM ORDERS\nWHERE country_code = 'ES'\n`}</code></pre>\n </li>\n <li parentName=\"ul\">\n <p parentName=\"li\">{`For your coworker in the USA, the SQL Lab query will be rendered as:`}</p>\n <pre parentName=\"li\"><code parentName=\"pre\" {...{}}>{`SELECT count(*)\nFROM ORDERS\nWHERE country_code = 'US'\n`}</code></pre>\n </li>\n </ul>\n <p><strong parentName=\"p\">{`Explicitly Including Values in Cache Key`}</strong></p>\n <p>{`The `}<inlineCode parentName=\"p\">{`{{ cache_key_wrapper() }}`}</inlineCode>{` function explicitly instructs Superset to add a value to the\naccumulated list of values used in the the calculation of the cache key.`}</p>\n <p>{`This function is only needed when you want to wrap your own custom function return values\nin the cache key. You can gain more context\n`}<a parentName=\"p\" {...{\n \"href\": \"https://github.com/apache/superset/blob/efd70077014cbed62e493372d33a2af5237eaadf/superset/jinja_context.py#L133-L148\"\n }}>{`here`}</a>{`.`}</p>\n <p>{`Note that this function powers the caching of the `}<inlineCode parentName=\"p\">{`user_id`}</inlineCode>{` and `}<inlineCode parentName=\"p\">{`username`}</inlineCode>{` values\nin the `}<inlineCode parentName=\"p\">{`current_user_id()`}</inlineCode>{` and `}<inlineCode parentName=\"p\">{`current_username()`}</inlineCode>{` function calls (if you have caching enabled).`}</p>\n <p><strong parentName=\"p\">{`Filter Values`}</strong></p>\n <p>{`You can retrieve the value for a specific filter as a list using `}<inlineCode parentName=\"p\">{`{{ filter_values() }}`}</inlineCode>{`.`}</p>\n <p>{`This is useful if:`}</p>\n <ul>\n <li parentName=\"ul\">{`you want to use a filter component to filter a query where the name of filter component column doesn't match the one in the select statement`}</li>\n <li parentName=\"ul\">{`you want to have the ability for filter inside the main query for speed purposes`}</li>\n </ul>\n <p>{`Here's a concrete example:`}</p>\n <pre><code parentName=\"pre\" {...{}}>{`SELECT action, count(*) as times\nFROM logs\nWHERE\n action in ({{ \"'\" + \"','\".join(filter_values('action_type')) + \"'\" }})\nGROUP BY action\n`}</code></pre>\n <p>{`You can use thisfeature to reference the start & end datetimes from a time filter using:`}</p>\n <ul>\n <li parentName=\"ul\"><inlineCode parentName=\"li\">{`{{ from_dttm }}`}</inlineCode>{`: start datetime value`}</li>\n <li parentName=\"ul\"><inlineCode parentName=\"li\">{`{{ to_dttm }}`}</inlineCode>{`: end datetime value`}</li>\n </ul>\n <p><strong parentName=\"p\">{`Filters for a Specific Column`}</strong></p>\n <p>{`The `}<inlineCode parentName=\"p\">{`{{ get_filters() }}`}</inlineCode>{` macro returns the filters applied to a given column. In addition to\nreturning the values (similar to how `}<inlineCode parentName=\"p\">{`filter_values()`}</inlineCode>{` does), the `}<inlineCode parentName=\"p\">{`get_filters()`}</inlineCode>{` macro\nreturns the operator specified in the Explore UI.`}</p>\n <p>{` This is useful if:`}</p>\n <ul>\n <li parentName=\"ul\">{`you want to handle more than the IN operator in your SQL clause`}</li>\n <li parentName=\"ul\">{`you want to handle generating custom SQL conditions for a filter`}</li>\n <li parentName=\"ul\">{`you want to have the ability to filter inside the main query for speed purposes`}</li>\n </ul>\n <p>{`Here's a concrete example:`}</p>\n <pre><code parentName=\"pre\" {...{}}>{` WITH RECURSIVE\n superiors(employee_id, manager_id, full_name, level, lineage) AS (\n SELECT\n employee_id,\n manager_id,\n full_name,\n 1 as level,\n employee_id as lineage\n FROM\n employees\n WHERE\n 1=1\n\n {# Render a blank line #}\n {%- for filter in get_filters('full_name', remove_filter=True) -%}\n\n {%- if filter.get('op') == 'IN' -%}\n AND\n full_name IN ( {{ \"'\" + \"', '\".join(filter.get('val')) + \"'\" }} )\n {%- endif -%}\n\n {%- if filter.get('op') == 'LIKE' -%}\n AND\n full_name LIKE {{ \"'\" + filter.get('val') + \"'\" }}\n {%- endif -%}\n\n {%- endfor -%}\n UNION ALL\n SELECT\n e.employee_id,\n e.manager_id,\n e.full_name,\n s.level + 1 as level,\n s.lineage\n FROM\n employees e,\n superiors s\n WHERE s.manager_id = e.employee_id\n )\n\n SELECT\n employee_id, manager_id, full_name, level, lineage\n FROM\n superiors\n order by lineage, level\n`}</code></pre>\n\n </MDXLayout>;\n}\n;\nMDXContent.isMDXComponent = true;\n "],"sourceRoot":""} |