Metabase 表变量Table Variables在 SQL 编辑器中动态指定查询表【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读表变量Table variables是 Metabase 原生 SQL 编辑器提供的一种特殊模板标签它允许你在 SQL 查询中用{{变量名}}占位符替代真实表名运行查询时由 Metabase 自动替换为所选表的 schema 与表名。本文基于 docs/questions/native-editor/table-variables.md 完整讲解表变量的添加方式、类型配置、Emit table alias变量名别名两种引用模式、与 SQL 片段snippets的组合玩法及已知限制并结合当前仓库源码说明其底层实现原理帮助你写出一次编写、多表复用的通用 SQL 模板。表变量是什么表变量Table variable是 SQL 参数SQL parameters的一种变量类型。在原生 SQL 查询中你可以在通常书写表名的地方使用双花括号占位符例如{{table}}。当运行查询时Metabase 会把该占位符替换为你在变量侧栏中选定的表的 schema 与表名。这一点与普通的文本/数字变量有本质区别普通变量替换的是值如某个筛选条件的具体取值而表变量替换的是表本身也就是查询所作用的数据源。从源码结构看表变量在 Metabase 的模板标签template tag体系中被建模为一种独立的标签类型:table。在 src/metabase/lib/schema/template_tag.cljc 中模板标签的合法:type枚举为:snippet :card :dimension :number :text :date :boolean :temporal-unit :table其中:table就是表变量对应的类型。而该文件对表变量标签::source-table的定义明确包含三个关键字段:table-id映射到的目标表 ID必填:emit-alias可选布尔值是否发出变量名作为别名:source-filters可选针对表变量的源过滤条件。表变量 vs 其他 SQL 变量变量类型占位符示例作用文档字段筛选变量{{created_at}}生成智能筛选器日期选择、下拉等需映射到查询中的字段field-filters.md基础变量{{category}}文本、数字、日期等简单值输入basic-sql-parameters.md时间分组参数{{unit}}让用户切换按日/周/月/年分组time-grouping-parameters.md表变量{{table}}选择要查询哪张表替换表名本文向查询中添加表变量第一步写出占位符在原生 SQL 编辑器中凡是写表名的地方都可以使用双花括号占位符SELECT COUNT(*) FROM {{table}}表变量可以出现在任何表名可出现的位置包括FROM子句与JOIN子句。例如在下面的查询中{{table}}和{{products_table}}分别替换两张表SELECT t.*, p.title FROM {{table}} AS t JOIN {{products_table}} AS p ON t.product_id p.id第二步将变量类型设置为 Table添加{{变量名}}占位符之后Variables变量侧栏会自动出现此时需要完成以下配置打开Variables侧栏添加变量后会自动弹出。将变量类型改为Table。在Table to map to要映射到的表下从表选择器中选择一张表必填项未选择前会显示 required 标记。根据你希望在查询中引用该表变量的方式切换Emit table alias开关具体见下文引用表变量的两种方式。运行查询时Metabase 会把{{table}}替换为所选表的 schema 与表名。如果想预览 Metabase 实际执行的完整 SQL可以点击编辑器上方的眼睛eye图标——该预览会展示变量替换后的真实语句便于排查替换是否符合预期。从源码看表映射与别名开关正是前端 TableMappingSelect.tsx 组件负责渲染的界面它展示了Table to map to选择器SchemaAndTableDataSelector缺省时标红显示(required)并提供一个 Switch 开关开关默认值为tag[emit-alias] ?? true其文案为Use variable name as alias将变量名用作别名提示语为你可以在查询的其他部分用变量名引用此表。由此可见Emit table alias 在默认情况下是开启的。引用表变量的两种方式表变量被替换进 SQL 后查询中其他部分要引用这张表有两种写法区别在于Emit table alias开关的状态。方式一使用变量名引用Emit table alias 开启如果你希望在查询的其余部分直接使用变量名来引用该表需要将Emit table alias切换为开启on。此时 Metabase 会以变量名作为表别名发出查询形如SELECT var_name.id, p.title FROM {{var_name}} JOIN products as p on var_name.product_id p.id这里的{{var_name}}被替换为schema.table_name AS var_name等价语义因此后续var_name.id、var_name.product_id都能正确解析。方式二自行指定别名Emit table alias 关闭如果你希望自己手动指定别名则需要将Emit table alias切换为关闭off并在查询中手动添加别名。适合的场景是你已经有一条带既有别名体系的长查询只想把其中一张表换成表变量而不想改动其余引用。此时查询形如SELECT o.id, p.title FROM {{var_name}} as o JOIN products as p on o.product_id p.id此时{{var_name}}仅被替换为schema.table_name不带任何别名因此你需要手动书写as o并在后续用o.id、o.product_id引用它。两种方式的对比Emit table alias 开启Emit table alias 关闭替换结果表名 变量名别名仅表名后续引用直接用变量名如var_name.id手动别名如o.id典型场景新查询、希望少写别名已有长查询、只想换表这一行为在后端有明确的代码依据在 src/metabase/query_processor/parameters/values.clj 中:table标签的解析实现会读取:table-id、:source-filters、:emit-alias与:name并调用lib/parsed-referenced-table-query-param第一个参数是目标表 ID第二个参数是源过滤条件第三个参数则是在emit-alias为真时传入变量名(when emit-alias name)——这正是开启别名即发出变量名这一行为的实现来源。表变量 × SQL 片段Snippets一次编写多表复用表变量最有价值的用法是与 SQL 片段snippets组合使用你可以把一段通用的 SQL 写成片段然后在多个问题question中复用每个问题把其中的表变量映射到不同的表。具体操作如下。1. 创建包含表变量的片段假设创建一个名为 row count 的 SQL 片段内容为SELECT COUNT(*) FROM {{table}}创建方式在原生编辑器中选中代码右键选择Save as snippet或打开 Snippet 侧栏新建并命名片段名必须唯一即使已归档的片段也占用名称参见 snippets.md。2. 在问题中插入片段在另一个 SQL 问题中插入该片段引用{{snippet: row count}}注意 Metabase 对片段引用的空白敏感{{snippet:与snippet之间不能有空格而冒号与片段名之间需要有一个空格。3. 为每个问题映射不同的表在每个问题中打开 Variables 侧栏将{{table}}映射到不同的数据库表即可。同一个 row count 片段可以在问题 A 中统计Products表的行数在问题 B 中统计Orders表的行数无需重写 SQL。背后的机制是片段参数的设置由问题question决定而非片段本身决定参见 snippets.md 中的 Values for snippet parameters are defined by the question, not the snippet。因此同一片段在不同问题中可以映射到完全不同的表各问题的映射互不干扰。从模板标签的建模上片段引用{{snippet: row count}}本身是一种:snippet类型的模板标签见 template_tag.cljc含:snippet-name与:snippet-id而片段内部展开后出现的{{table}}则会作为独立的:table标签参与解析。两者组合就实现了通用片段 每问题换表的复用能力。表变量的限制根据官方文档与当前仓库实现表变量目前存在以下限制规划使用方式时需要特别注意不能作为仪表板筛选参数表变量无法连接到仪表板筛选器dashboard filter组件。表变量必须直接在每个问题上单独设置。这一点与字段筛选变量形成鲜明对比——字段筛选变量可以连接到仪表板筛选器见 sql-parameters.md 中的将 SQL 问题连接到仪表板筛选器。仅限 SQL 查询表变量只在原生 SQL 查询中可用不适用于查询构建器query builder。没有输入组件不存在让用户自行输入表名的输入框。你必须在变量侧栏中通过表选择器选定表也就是说表变量面向的是由提问者预先固定表的模板场景而非终端用户自由选表。暂不支持 transforms表变量还不能用于 Data Studio 的 transforms转换。另外可以补充一个与安全模型相关的注意点表变量在映射时通过:table-id指向具体表见 template_tag.cljc 的::source-table定义并且支持可选的:source-filters允许的操作符限定为: : : : : :!见 allowed-source-filter-ops后端解析时会校验这些操作符的合法性见 values.clj。实战小结要把表变量用好记住以下要点占位符写在哪写在表名出现的位置FROM、JOIN使用双花括号{{名称}}。配置三件事类型选 Table、映射目标表必填、决定 Emit table alias 开关。引用方式二选一开 Emit table alias 用变量名引用关掉则手动写别名。复用靠片段把通用 SQL 存成片段用{{snippet: 名称}}插入每个问题分别映射不同表。预览验证用编辑器上方的眼睛图标预览变量替换后的完整 SQL确认 schema、表名与别名正确。牢记限制不能接仪表板筛选器、仅限 SQL 查询、无输入框、暂不支持 transforms。进一步阅读SQL parametersSQL 参数总览SnippetsSQL 片段Field filters字段筛选变量SQL troubleshooting guideSQL 故障排查指南【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Metabase 表变量（Table Variables）：在 SQL 编辑器中动态指定查询表
Metabase 表变量Table Variables在 SQL 编辑器中动态指定查询表【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase导读表变量Table variables是 Metabase 原生 SQL 编辑器提供的一种特殊模板标签它允许你在 SQL 查询中用{{变量名}}占位符替代真实表名运行查询时由 Metabase 自动替换为所选表的 schema 与表名。本文基于 docs/questions/native-editor/table-variables.md 完整讲解表变量的添加方式、类型配置、Emit table alias变量名别名两种引用模式、与 SQL 片段snippets的组合玩法及已知限制并结合当前仓库源码说明其底层实现原理帮助你写出一次编写、多表复用的通用 SQL 模板。表变量是什么表变量Table variable是 SQL 参数SQL parameters的一种变量类型。在原生 SQL 查询中你可以在通常书写表名的地方使用双花括号占位符例如{{table}}。当运行查询时Metabase 会把该占位符替换为你在变量侧栏中选定的表的 schema 与表名。这一点与普通的文本/数字变量有本质区别普通变量替换的是值如某个筛选条件的具体取值而表变量替换的是表本身也就是查询所作用的数据源。从源码结构看表变量在 Metabase 的模板标签template tag体系中被建模为一种独立的标签类型:table。在 src/metabase/lib/schema/template_tag.cljc 中模板标签的合法:type枚举为:snippet :card :dimension :number :text :date :boolean :temporal-unit :table其中:table就是表变量对应的类型。而该文件对表变量标签::source-table的定义明确包含三个关键字段:table-id映射到的目标表 ID必填:emit-alias可选布尔值是否发出变量名作为别名:source-filters可选针对表变量的源过滤条件。表变量 vs 其他 SQL 变量变量类型占位符示例作用文档字段筛选变量{{created_at}}生成智能筛选器日期选择、下拉等需映射到查询中的字段field-filters.md基础变量{{category}}文本、数字、日期等简单值输入basic-sql-parameters.md时间分组参数{{unit}}让用户切换按日/周/月/年分组time-grouping-parameters.md表变量{{table}}选择要查询哪张表替换表名本文向查询中添加表变量第一步写出占位符在原生 SQL 编辑器中凡是写表名的地方都可以使用双花括号占位符SELECT COUNT(*) FROM {{table}}表变量可以出现在任何表名可出现的位置包括FROM子句与JOIN子句。例如在下面的查询中{{table}}和{{products_table}}分别替换两张表SELECT t.*, p.title FROM {{table}} AS t JOIN {{products_table}} AS p ON t.product_id p.id第二步将变量类型设置为 Table添加{{变量名}}占位符之后Variables变量侧栏会自动出现此时需要完成以下配置打开Variables侧栏添加变量后会自动弹出。将变量类型改为Table。在Table to map to要映射到的表下从表选择器中选择一张表必填项未选择前会显示 required 标记。根据你希望在查询中引用该表变量的方式切换Emit table alias开关具体见下文引用表变量的两种方式。运行查询时Metabase 会把{{table}}替换为所选表的 schema 与表名。如果想预览 Metabase 实际执行的完整 SQL可以点击编辑器上方的眼睛eye图标——该预览会展示变量替换后的真实语句便于排查替换是否符合预期。从源码看表映射与别名开关正是前端 TableMappingSelect.tsx 组件负责渲染的界面它展示了Table to map to选择器SchemaAndTableDataSelector缺省时标红显示(required)并提供一个 Switch 开关开关默认值为tag[emit-alias] ?? true其文案为Use variable name as alias将变量名用作别名提示语为你可以在查询的其他部分用变量名引用此表。由此可见Emit table alias 在默认情况下是开启的。引用表变量的两种方式表变量被替换进 SQL 后查询中其他部分要引用这张表有两种写法区别在于Emit table alias开关的状态。方式一使用变量名引用Emit table alias 开启如果你希望在查询的其余部分直接使用变量名来引用该表需要将Emit table alias切换为开启on。此时 Metabase 会以变量名作为表别名发出查询形如SELECT var_name.id, p.title FROM {{var_name}} JOIN products as p on var_name.product_id p.id这里的{{var_name}}被替换为schema.table_name AS var_name等价语义因此后续var_name.id、var_name.product_id都能正确解析。方式二自行指定别名Emit table alias 关闭如果你希望自己手动指定别名则需要将Emit table alias切换为关闭off并在查询中手动添加别名。适合的场景是你已经有一条带既有别名体系的长查询只想把其中一张表换成表变量而不想改动其余引用。此时查询形如SELECT o.id, p.title FROM {{var_name}} as o JOIN products as p on o.product_id p.id此时{{var_name}}仅被替换为schema.table_name不带任何别名因此你需要手动书写as o并在后续用o.id、o.product_id引用它。两种方式的对比Emit table alias 开启Emit table alias 关闭替换结果表名 变量名别名仅表名后续引用直接用变量名如var_name.id手动别名如o.id典型场景新查询、希望少写别名已有长查询、只想换表这一行为在后端有明确的代码依据在 src/metabase/query_processor/parameters/values.clj 中:table标签的解析实现会读取:table-id、:source-filters、:emit-alias与:name并调用lib/parsed-referenced-table-query-param第一个参数是目标表 ID第二个参数是源过滤条件第三个参数则是在emit-alias为真时传入变量名(when emit-alias name)——这正是开启别名即发出变量名这一行为的实现来源。表变量 × SQL 片段Snippets一次编写多表复用表变量最有价值的用法是与 SQL 片段snippets组合使用你可以把一段通用的 SQL 写成片段然后在多个问题question中复用每个问题把其中的表变量映射到不同的表。具体操作如下。1. 创建包含表变量的片段假设创建一个名为 row count 的 SQL 片段内容为SELECT COUNT(*) FROM {{table}}创建方式在原生编辑器中选中代码右键选择Save as snippet或打开 Snippet 侧栏新建并命名片段名必须唯一即使已归档的片段也占用名称参见 snippets.md。2. 在问题中插入片段在另一个 SQL 问题中插入该片段引用{{snippet: row count}}注意 Metabase 对片段引用的空白敏感{{snippet:与snippet之间不能有空格而冒号与片段名之间需要有一个空格。3. 为每个问题映射不同的表在每个问题中打开 Variables 侧栏将{{table}}映射到不同的数据库表即可。同一个 row count 片段可以在问题 A 中统计Products表的行数在问题 B 中统计Orders表的行数无需重写 SQL。背后的机制是片段参数的设置由问题question决定而非片段本身决定参见 snippets.md 中的 Values for snippet parameters are defined by the question, not the snippet。因此同一片段在不同问题中可以映射到完全不同的表各问题的映射互不干扰。从模板标签的建模上片段引用{{snippet: row count}}本身是一种:snippet类型的模板标签见 template_tag.cljc含:snippet-name与:snippet-id而片段内部展开后出现的{{table}}则会作为独立的:table标签参与解析。两者组合就实现了通用片段 每问题换表的复用能力。表变量的限制根据官方文档与当前仓库实现表变量目前存在以下限制规划使用方式时需要特别注意不能作为仪表板筛选参数表变量无法连接到仪表板筛选器dashboard filter组件。表变量必须直接在每个问题上单独设置。这一点与字段筛选变量形成鲜明对比——字段筛选变量可以连接到仪表板筛选器见 sql-parameters.md 中的将 SQL 问题连接到仪表板筛选器。仅限 SQL 查询表变量只在原生 SQL 查询中可用不适用于查询构建器query builder。没有输入组件不存在让用户自行输入表名的输入框。你必须在变量侧栏中通过表选择器选定表也就是说表变量面向的是由提问者预先固定表的模板场景而非终端用户自由选表。暂不支持 transforms表变量还不能用于 Data Studio 的 transforms转换。另外可以补充一个与安全模型相关的注意点表变量在映射时通过:table-id指向具体表见 template_tag.cljc 的::source-table定义并且支持可选的:source-filters允许的操作符限定为: : : : : :!见 allowed-source-filter-ops后端解析时会校验这些操作符的合法性见 values.clj。实战小结要把表变量用好记住以下要点占位符写在哪写在表名出现的位置FROM、JOIN使用双花括号{{名称}}。配置三件事类型选 Table、映射目标表必填、决定 Emit table alias 开关。引用方式二选一开 Emit table alias 用变量名引用关掉则手动写别名。复用靠片段把通用 SQL 存成片段用{{snippet: 名称}}插入每个问题分别映射不同表。预览验证用编辑器上方的眼睛图标预览变量替换后的完整 SQL确认 schema、表名与别名正确。牢记限制不能接仪表板筛选器、仅限 SQL 查询、无输入框、暂不支持 transforms。进一步阅读SQL parametersSQL 参数总览SnippetsSQL 片段Field filters字段筛选变量SQL troubleshooting guideSQL 故障排查指南【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考