代码片段

代码片段是可重用的 SQL 或原生查询片段。任何有权访问原生编辑器的用户都可以创建和编辑代码片段，这些代码片段随后可供所有原生查询作者使用。

例如，如果您经常编写涉及多个表的查询，可以将连接这些表的 SQL 代码保存为代码片段，以便您（以及您组织中的其他人）可以在多个问题中使用该代码。

您可以使用代码片段来定义标准化的 KPI 和筛选器，就像在查询构建器中使用指标和分段一样。例如，您可能希望存储计算收入的确切方法，或者什么构成活跃用户。

您还可以使用代码片段为 SQL 问题定义一组可重用的筛选器。

创建代码片段

在原生编辑器中

1. 通过点击右上角的 **+ 新建 > SQL 查询** 或 **+ 新建 > 原生查询** 来打开原生编辑器。

2. 编写一些 SQL 或原生代码，并突出显示您想要保存以供以后重用的代码部分。该部分不必是完整的查询。例如，您可以突出显示

   orders AS o
   LEFT JOIN products AS p ON o.product_id = p.id
   WHERE p.category = {{category}}
   

   在代码片段中，您可以使用

   • SQL 参数，例如 {{param}}，
   • 对其他代码片段的引用，例如 {{snippet: orders}}（Metabase 会检测并禁止循环引用），
   • 对已保存问题或模型的引用，例如 {{#123-orders-model}}。

3. 右键单击突出显示的部分，然后选择 **保存为代码片段** 来创建代码片段。

   

4. 命名并描述您的代码片段。代码片段名称必须唯一（即使是已归档代码片段的名称）。
5. 保存。

您也可以从“代码片段”侧边栏创建新代码片段

1. 通过点击右上角的 **+ 新建 > SQL 查询** 或 **+ 新建 > 原生查询** 来打开原生编辑器。
2. 通过点击编辑器窗口上方的 **代码片段** 按钮来打开“代码片段”侧边栏。
3. 输入您想要保存为可重用代码片段的代码。
4. 保存。

使用代码片段

您可以将已保存的代码片段插入到您的查询中，这将添加一个 {{snippet: }} 引用。

SELECT
  *
FROM
 {{snippet: orders and products}}

要将代码片段添加到您的原生代码中，请开始输入 {{snippet: }}，Metabase 将会提供可用代码片段的自动完成选项。

Metabase 对代码片段引用的空格敏感，因此您应该输入 {{snippet: Products}}，在 {{ 和 snippet 之间不加空格，在 : 和代码片段名称之间加一个空格。

当您执行查询时，Metabase 会在后台将代码片段引用替换为代码片段的 SQL。

您也可以直接从代码片段侧边栏中选择一个代码片段进行插入。

1. 通过点击编辑器窗口上方的 **代码片段** 按钮来打开代码片段侧边栏。
2. 搜索代码片段。请注意，搜索结果仅包含您有权查看的代码片段。
3. 将鼠标悬停在代码片段上，然后点击代码片段名称左侧的箭头将其插入到您的查询中。

如果您在代码片段中使用别名，则需要在更大的查询中引用这些别名。例如，如果一个代码片段将 products AS p 别名为 p，那么代码片段外部的代码将需要使用别名 p 来引用该表中的列（例如 p.column_name）。

预览带有代码片段的查询

Metabase 会将代码片段保留为引用，并且不会在 SQL 编辑器本身中显示完整的查询（已替换代码片段代码）。您可以点击编辑器上方的 **眼睛** 图标来查看 Metabase 将发送到数据库的完整查询。

编辑代码片段

编辑代码片段是同时修改多个问题的好方法。例如，如果您已将从表 X、Y 和 Z 中提取用户数据的 SQL 代码保存为名为 User Data 的代码片段，但您需要更改数据的提取方式（例如，通过添加来自另一个列或表的数据），您可以更新代码片段中的 SQL 代码，并且所有使用 User Data 代码片段的问题都将获得更新后的代码。

编辑代码片段

1. 通过点击编辑器窗口上方的 **代码片段** 图标来打开代码片段侧边栏。

2. 搜索代码片段。搜索结果仅包含您有权编辑的代码片段。

3. 点击代码片段名称右侧的 **向下箭头**，然后点击 **编辑**。

   您可以更改代码、代码片段名称和代码片段描述。

• 编辑代码片段名称。更改代码片段的名称将更新使用该代码片段的每个问题中的代码片段名称。重命名代码片段不会破坏任何引用该代码片段的现有问题，但会破坏其他引用该代码片段的代码片段。

• 编辑代码片段代码。在这里，我们必须提醒您，能力越大，责任越大。编辑代码片段时有一个主要的注意事项，值得特别说明：如果您编辑了代码片段并包含损坏的代码，那么您将破坏所有使用该代码片段的问题。在将代码保存到现有代码片段之前，请务必进行测试。

归档代码片段

归档代码片段可以帮助您整理过时或不太相关的代码片段。

当您归档代码片段时，该代码片段将不再显示在代码片段自动完成下拉菜单中，并且该代码片段也不会在侧边栏的代码片段列表中显示。归档代码片段不会影响任何已使用该代码片段的现有查询，因此您可以安全地归档代码片段而不会影响任何问题。

归档代码片段

1. 通过点击编辑器窗口上方的 **代码片段** 图标来打开代码片段侧边栏。
2. 搜索代码片段。
3. 点击代码片段名称右侧的 **向下箭头**，然后点击 **编辑**。
4. 点击 **归档**

您可以通过点击侧边栏左下角的归档按钮，从代码片段侧边栏菜单中访问已归档的代码片段。

虽然没有删除代码片段的方法，但您可以随时归档和取消归档代码片段。

两个代码片段不能共享相同的名称，因为即使代码片段已被归档，它可能仍在问题中活动。

代码片段中的 SQL 参数

您可以在代码片段中引用SQL 参数。例如，您可以保存一个包含如下 SQL 代码的代码片段：

 
WHERE
  {{created_at}}
AND category = {{category}}
GROUP BY {{time_grouping}}

当一个包含参数的代码片段被添加到 SQL 查询中时，Metabase 将显示该代码片段参数的小部件。

您将能够为来自代码片段的参数指定类型、关联的列和默认值，这些参数将在查询的“变量”侧边栏中进行设置。

代码片段参数的设置由查询定义，而不是代码片段本身，因此不同查询使用相同代码片段的设置不会共享。例如，如果您有一个代码片段，如下所示：

WHERE {{created_at}}

您可以将代码片段放入一个查询中，并将代码片段参数映射到 CREATED_AT 列，然后将该代码片段放入另一个查询中，并将相同的代码片段参数映射到不同的列，如 CANCELED_AT。

如果您有多个包含同名参数的代码片段，则使用这些代码片段的问题将只使用一个参数实例。例如，如果 {{snippet: 1}} 包含参数 {{var}}，而 {{snippet: 2}} 也包含参数 {{var}}，则该问题将仅显示一个 {{var}} 参数，并将其值用于两个代码片段。

跨问题共享参数

您还可以使用代码片段在多个 SQL 问题之间共享参数，包括相互依赖的问题（嵌套问题）。例如，您有一个问题“按日期排序的订单”，它使用 {{start_date}} 筛选订单。然后，您创建另一个问题，例如“按产品计算收入”，该问题使用“按日期排序的订单”的结果。为了在两个问题中继续使用相同的 {{start_date}} 参数，请将包含该参数的 SQL 代码从“按日期排序的订单”移动到代码片段中，并更新两个问题以引用该代码片段。现在，这两个问题都显示相同的参数，并且单个仪表板日期筛选器可以控制使用该代码片段的两个卡片。

代码片段权限

任何拥有至少一个已连接数据库的原生编辑器权限的用户都将能够查看代码片段侧边栏，并能够创建、编辑、归档或取消归档任何和所有代码片段 — 即使是打算与用户缺乏 SQL 编辑访问权限的数据库一起使用的代码片段。

某些计划包含用于将代码片段组织到文件夹和设置文件夹权限的附加功能。请参阅我们关于代码片段文件夹和权限的文档。

为什么使用代码片段？

代码片段适用于

• 标准化

  您的组织如何定义热门产品？是通过销量？还是通过平均评分大于 4 的评论？您可以定义热门产品的这些限定条件，并将其编码到代码片段 {{snippet: popular products}} 中，然后在每个使用该代码片段的问题中填充该代码。如果将来这个定义需要更改，只需更新代码片段的 SQL，更改就会传播到所有使用该代码片段的问题。

  与分段（命名筛选器或一组筛选器）和指标（命名计算）可以标准化您组织中的分析类似，代码片段提供了一种确保跨团队 SQL 正确性和一致性的方法。

• 效率

  您是否经常复制粘贴 SQL 代码？不想费力地记住哪个外键映射到哪个表？写一次复杂的连接，将其保存为代码片段，并在需要时调用该代码片段。

• 教育

  代码片段可以通过暴露您组织中的“标准 SQL”，或更高效或更复杂的查询，来提升 SQL 新手（甚至是有经验的分析师）的水平。阅读、复制和构建优质代码是提高技能的最佳方法之一。它还可以节省您组织的时间：人们可以复制代码片段的代码，修改它以获得不同的结果，然后将其保存为新的代码片段供他人使用。

了解更多

• 代码片段 vs 已保存问题 vs 视图.
• 如果您在使用 SQL 查询时遇到问题，请参阅 SQL 故障排除指南。