在仪表板和工作表中筛选查询结果

您可以使用系统筛选器（面向 Snowflake 中的所有角色提供）在仪表板和 SQL 工作表中筛选查询结果，也可以使用管理员创建的自定义筛选器。

创建自定义筛选器

借助自定义筛选器，您无需直接编辑查询即可更改查询的结果。

筛选器以解析为子查询或值列表的特殊关键字实施，用于执行查询。因此，在 SQL 查询中使用筛选器时有一些限制。请参阅 在 SQL 查询中指定筛选器。

备注

创建自定义筛选器后，您账户中的任何人都可以查看和使用该筛选器。自定义筛选器具有相关角色，但该角色不会限制筛选器的可见性。

授予创建自定义筛选器的权限

要让用户创建自定义筛选器，具有 ACCOUNTADMIN 角色的用户必须向授予该用户的角色授予相关权限。您只能使用 Snowsight 授予角色创建自定义筛选器的能力。

要授予角色为账户创建自定义筛选器的权限，请执行以下操作：

  1. 登录 Snowsight。

  2. 选择 Projects » Worksheets 打开工作表列表并打开工作表，或选择 Projects » Dashboards 打开仪表板列表并打开仪表板。

  3. 选择 显示或隐藏筛选器，如果在工作表中，选择 Manage Filters。

  4. 在显示的对话框中，选择 Edit Permission。

  5. 在 Filter Permissions 对话框中，选择您要为其授予筛选器创建能力的角色。

  6. 选择 Save。

创建自定义筛选器

您必须使用 Snowsight 创建筛选器，并且您必须使用具有权限的角色来创建自定义筛选器。

要创建自定义筛选器，请执行以下操作：

  1. 登录 Snowsight。

  2. 选择 Projects » Worksheets 打开工作表列表并打开工作表，或选择 Projects » Dashboards 打开仪表板列表并打开仪表板。

  3. 选择 显示或隐藏筛选器，如果在工作表中，选择 Manage Filters。

  4. 在显示的 Filters 对话框中，选择 + Filter。

  5. 要添加筛选器，请完成以下操作：

    1. 对于 Display Name，输入筛选器的名称。在工作表或仪表板上选择筛选器时，此名称会显示在筛选器上。

    2. 对于 SQL Keyword，输入要插入查询的唯一关键字。使用格式 :<string>，不带空格。例如：:page_path。

    3. 对于 Description，输入筛选器的描述。

    4. 对于 Role，选择与筛选器关联的角色，并运行用于填充筛选器值的查询（如果筛选器基于查询）。只有具有创建自定义筛选器权限的角色才会显示在下拉列表中。有关更多详细信息，请参阅 管理自定义筛选器的所有权。

    5. 对于 Warehouse，如果筛选器基于查询，请选择用于刷新筛选器值的仓库。筛选器的所有者角色必须对您选择的仓库具有 USAGE 权限。如果要在这些步骤中运行并验证查询，则仓库必须正在运行。

    6. 对于 Options via，选择筛选器值是通过查询还是列表填充：

      • 如果您选择 Query，请选择 Write Query 并查看 编写查询以填充筛选器 以获取编写筛选器查询的指导。

      • 如果您选择 List，请执行以下操作：

        1. 选择 Edit List。

        2. （可选）对于 Name，输入列表项目的名称。该名称将显示在筛选器的下拉列表中。如果您不提供名称，则会使用 Value。

        3. 对于 Value，输入要在筛选器中使用的列名称的值。

        4. 继续添加名称和值对，直到列表完成，然后选择 Save。

  6. 在 Add Filter 对话框中，对于 Value Type，选择列表项目的数据类型是 Text 还是 Number。

  7. 如果您希望用户能够在筛选器选项下拉列表中选择多个项目，请开启 Multiple values can be selected。

  8. 如果您希望用户能够查看列中所有项目的结果，请开启 Include an "All" option，然后选择您希望 All 选项如何工作：

    • 选择 Any value 以使筛选器为 All 意味着筛选器适用的列在结果中可以为任何值，无论该值在筛选器列表中是否存在。

    • 选择 Any value in list of options 以使筛选器为 All 意味着筛选器适用的列包含筛选器列表中的任何项目。

  9. 如果您希望用户能够查看筛选器中未指定的项目的结果，请开启 Include an "Other" option。

  10. 选择 Save。

  11. 选择 Done 以关闭 Filters 对话框。

编写查询以填充筛选器

要使用查询填充筛选器选项列表，查询必须遵循某些准则：

  • 必须返回列 name 和 value。

  • 可以返回可选列 description。

  • 可以返回其他列，但这些列不会显示在下拉筛选器列表中。

一个筛选器一次只能运行一个查询。您不能运行多个查询来生成筛选器选项列表，例如通过运行一个查询来返回 name 列，然后运行第二个查询来返回 value 列。

备注

用于填充筛选器选项列表的查询以创建（或最后修改）筛选器的用户身份运行。由于您账户中的任何人都可以在创建自定义筛选器后查看和使用该筛选器，因此请确保查询生成的筛选器选项列表不包含受保护或敏感的数据。

编写筛选器查询并将其添加到 New filter 对话框中后，执行以下操作以完成查询筛选器设置：

  1. 选择 Done 保存筛选器查询并返回 Add Filter 对话框。

  2. （可选）将默认刷新选项从 Refresh hourly 更改为 Never refresh 或 Refresh daily。有关筛选器刷新选项的详细信息和注意事项，请参阅 管理自定义筛选器的刷新频率。

  3. 返回创建自定义筛选器的步骤以完成筛选器创建。请参阅 创建自定义筛选器。

查看和管理账户中的自定义筛选器

要查看账户中的自定义筛选器，请打开工作表或仪表板，然后选择 显示或隐藏筛选器。

要更改任何筛选器，例如更改用于填充自定义筛选器列表的查询的刷新频率，您必须拥有 ACCOUNTADMIN 角色或具有 管理筛选器权限 的角色。请参阅 管理自定义筛选器的刷新频率。

管理自定义筛选器的所有权

每个自定义筛选器都有一个关联角色。具有该角色的任何人都可以编辑或删除筛选器。具有 ACCOUNTADMIN 角色的用户可以查看和编辑账户中的每个筛选器。

如果删除与筛选器关联的角色，则删除筛选器角色的角色将 不会 继承自定义筛选器的所有权。否则，具有 ACCOUNTADMIN 角色的用户可以编辑筛选器并更改与筛选器关联的角色。

管理自定义筛选器的刷新频率

由 SQL 查询填充的自定义筛选器也有刷新频率。刷新频率可以是每小时、每天，或者从不。

筛选器的运行基于其保存时间以及运行刷新筛选器选项的查询所需的时间。

例如，如果您在 10:07 AM 保存了一个具有每小时查询刷新频率的筛选器，则第一个刷新查询在 11:07 AM 或之后运行。如果最终计划同时运行大量筛选器刷新查询，则查询将排队以限制同时运行的筛选器刷新查询的数量。下一次筛选器刷新基于上次刷新完成的时间。在此示例中，如果查询在 11:07 AM 刷新需要 20 分钟完成，则下一个刷新查询将在 12:27 PM 或之后运行。

筛选器刷新会以创建或上次修改筛选器的用户身份运行，并作为 Queries executed by user tasks 的类型之一在 Query History 中显示。有关使用 Query History 的详细信息，请参阅 使用 Query History 监控查询活动。

要确定哪个筛选器负责筛选查询刷新，必须打开筛选器列表并打开每个筛选器以查看详细信息。

排查筛选器查询刷新失败的问题

筛选器查询刷新可能会因以下原因失败：

  • 已在 Snowflake 中删除或禁用创建或最后修改筛选器的用户。

  • 用户处于非活动状态，因为其已 3 个月没有登录。

无法查看哪些用户创建或最后修改了指定筛选器。如果筛选器无法刷新，您可能会在 SNOWFLAKE 共享数据库内 ACCOUNT_USAGE 架构的 LOGIN_HISTORY 视图 视图中，看到 WORKSHEETS_APP_USER 用户的成功身份验证尝试，随后还会看到某个用户的失败身份验证尝试。

例如，您可以使用以下查询来识别前两天使用 OAuth 访问令牌的登录活动：

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.LOGIN_HISTORY
WHERE
    FIRST_AUTHENTICATION_FACTOR = 'OAUTH_ACCESS_TOKEN'
    AND
    REPORTED_CLIENT_TYPE = 'SNOWFLAKE_UI'
    AND
    EVENT_TIMESTAMP > DATEADD('DAY', -2, CURRENT_DATE());
ORDER BY
    EVENT_TIMESTAMP DESC;
Copy

与失败查询刷新频率相关的失败身份验证尝试将在每天或每小时的同一时间发生，具体取决于自定义筛选器刷新频率。

在 SQL 查询中指定筛选器

您可以在 SQL 查询中使用 系统筛选器 或自定义筛选器。不得在存储过程或用户定义函数 (UDF) 中使用筛选器。

要将筛选器添加到 SQL 查询，请使用下列格式之一：

  • 在 SELECT 语句中指定筛选器，例如：samp:SELECT :<filter_name>(<col_name>)。

  • 使用等号作为比较器来指定筛选器。例如：

    • WHERE <col_name> = :<filter_name>

    • WHERE <:filter_name> = <col_name>

    • <value_a>:<value_b>::string = <:filter_name>

您只能使用等号作为筛选器的比较器，因此不能使用带有 LIKE 或 CONTAINS 的筛选器。

筛选器适用的列还必须与筛选器期望的值类型相匹配：

  • 对于设置为使用文本值类型的自定义筛选器，该列必须是文本字符串或在查询中转换为文本字符串。请参阅 文本字符串的数据类型。

  • 对于设置为使用数字值类型的自定义筛选器，该列必须是数字数据类型。请参阅 数值数据类型。

  • 对于系统筛选器，该列必须是 TIMESTAMP 数据类型。请参阅 日期和时间数据类型。

向 SQL 查询添加筛选器，然后使用下拉列表选择筛选器选项时，查询的 SQL 语法将会更改。有关选择列表中的不同选项时 SQL 语法会如何变化的详细信息，请参阅下表：

筛选 SQL 参考

已选择的筛选器选项

已使用的 SQL

列表项目

<col> = <list_item>

已选择的多个列表项目

<col> IN (<list_item>, <list_item>)

全部，指定 Any value

true

全部，指定 Any value in list of options

<col> IN (<list_item>, <list_item>, ... )

其他

<col> NOT IN(<list_item>, <list_item>, ... )

应用和保存筛选器

当您更改筛选器中选择的选项时，将显示应用更改的选项。当您选择 Apply 时，工作表或仪表板将运行并显示更新的筛选结果，让您无需保存即可查看更改。

将更改应用于仪表板上的筛选器后，将显示保存更改的选项。当您选择 Save 时，您对仪表板所做的更改已保存，并且可供仪表板的其他用户使用。

例如，您可以选择 Apply 更改筛选器以查看 All Time 结果，但您不希望在下次有人打开仪表板时，仪表板运行如此大量的数据，因此您 不 选择 Save。在所有时间运行仪表板后，将日期范围筛选器更改为 Last 7 days，选择 Apply 运行仪表板，然后选择 Save 为仪表板用户保存默认筛选器值。

Snowsight 系统筛选器

以下系统筛选器可用于所有角色：

  • :daterange

    • 按日期范围筛选列，例如 Last day、Last 7 days、Last 28 days、Last 3 months、Last 6 months、Last 12 months、All time 或自定义日期范围。

      备注

      日期范围筛选器始终使用 UTC 时区，不受 TIMESTAMP_INPUT_FORMAT 参数影响。

      默认值为 Last day。

  • :datebucket

    • 按时间段对汇总数据进行分组，例如 Second、Minute、Hour、Day、Week、Month、日历月中的 Quarter 或 Year。

      默认值为 Day。

这些筛选器无法编辑或删除。

示例：使用日期筛选器

例如，给定一个包含订单数据的表（如 SNOWFLAKE_SAMPLE_DATA 数据库和 TPCH_SF1 架构中的 ORDERS 表），您可能希望查询表并按特定时间桶（例如按天或按周）对结果进行分组，并指定要检索结果的特定日期范围。

为此，您可以编写如下查询：

SELECT
    COUNT(O_ORDERDATE) as orders,
    :datebucket(O_ORDERDATE) as bucket
FROM
    SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
WHERE
    O_ORDERDATE = :daterange
GROUP BY
    :datebucket(O_ORDERDATE)
ORDER BY
    bucket;
Copy

在此示例中，您执行以下操作：

  • 计算订单数量并从 ORDERS 表中检索有关订单日期的详细信息。

  • 通过在 WHERE 子句中包含 :daterange 系统筛选器，按特定日期范围筛选结果。

  • 通过在 GROUP BY 子句中包含 :datebucket 系统筛选器，按特定时间范围对结果进行分组。

  • 通过包括 ORDER BY 子句，按从早到晚的时间段对结果进行排序。

向查询中添加筛选器时，相应的筛选器按钮在工作表或仪表板的顶部显示：

显示筛选器按钮时，会按照选项卡顺序显示在显示和隐藏筛选器按钮后。

要处理从查询中看到的结果，请使用筛选器选择特定的值。

对于此示例，设置对应于日期桶筛选器的 Group by 筛选器，以按 Day 分组。将对应于日期范围筛选器的另一个筛选器设置为 All time。

选择 Apply 并将筛选器应用到结果时，结果按天分组，并显示如下输出结果：

+--------+------------+
| orders |  buckets   |
+--------+------------+
|    621 | 1992-01-01 |
|    612 | 1992-01-02 |
|    598 | 1992-01-03 |
|    670 | 1992-01-04 |
+--------+------------+

您可以选择不同的日期桶来显示不同的数据分组。例如，要查看每周订单数据，请将 Group by 筛选器设置为 Week 并选择 Apply。显示如下输出结果：

+--------+------------+
| orders |  buckets   |
+--------+------------+
|   3142 | 1991-12-30 |
|   4404 | 1992-01-06 |
|   4306 | 1992-01-13 |
|   4284 | 1992-01-20 |
+--------+------------+
语言: 中文