创建已保存的查询

本文档介绍了如何创建已保存的查询和传统版已保存的查询。

已保存的查询

请参阅以下部分，了解如何创建已保存的查询。已保存的查询是由 Dataform 提供支持的 BigQuery Studio 代码资源。

如需详细了解如何删除已保存的查询和管理已保存的查询历史记录，请参阅已保存的查询。

启用 BigQuery Studio

按照启用 BigQuery Studio 进行资产管理中的说明来保存、共享和管理代码资产（例如已保存的查询）版本。

重要提示：2024 年 3 月，系统将自动为所有 BigQuery 项目启用支持 BigQuery Studio 功能的 API。如需了解详情，请参阅自动启用 BigQuery Studio API。

所需权限

设置适当的权限以创建、修改或查看已保存的查询。

具有 Dataform Admin (roles/dataform.admin) 角色的所有用户都可以访问在项目中创建的所有已保存查询。

如需详细了解 BigQuery Identity and Access Management (IAM)，请参阅使用 IAM 进行访问权限控制。

创建已保存的查询的权限

如需创建和运行已保存的查询，您需要以下 IAM 权限：

• dataform.locations.get
• dataform.locations.list
• dataform.repositories.list

• dataform.repositories.create

  注意：拥有 dataform.repositories.create 权限的用户可以使用默认的 Dataform 服务账号和授予该服务账号的所有权限来执行代码。如需了解详情，请参阅 Dataform 权限的安全注意事项。

您可以从以下 IAM 角色获取这些权限：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)

• Code Creator (roles/dataform.codeCreator)

  注意：在项目中分配了 Code Creator 角色的用户可以使用 Dataform API 或 Dataform 命令行界面 (CLI) 列出该项目中代码资源的名称。使用 BigQuery Studio 的非管理员只能看到他们创建或与他们共享的代码资产。

修改已保存查询的权限

如需修改和运行已保存的查询，您需要以下 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Code Editor (roles/dataform.codeEditor)

查看已保存的查询的权限

如需查看和运行已保存的查询，您需要以下 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• Code Viewer (roles/dataform.codeViewer)

设置代码资源的默认区域

如果这是您第一次创建代码资源，请设置代码资源的默认区域。代码资源创建后，便无法更改该区域。

注意：如果您创建了一个已保存查询，并选择了与用于代码资源的区域不同的默认区域，例如在已使用 us-central1 的情况下选择了 us-west1，则默认情况下，该查询和您后续创建的所有代码资源都将使用该新区域。现有代码资源将继续使用在创建它们时为其分配的区域。

创建已保存的查询

如需创建已保存的查询，请按照下列步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 点击 编写新查询。

3. 在查询编辑器中，输入有效的 SQL 查询。 例如，您可以查询公共数据集：

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

4. 点击 保存查询 > 保存查询。

5. 在保存查询对话框中，为已保存的查询输入一个名称。

6. 可选：如需更改此已保存的查询将来使用的区域以及所有其他代码资源，请在区域中选择一个新区域。

7. 点击保存。

授予对已保存查询的访问权限

如需向其他用户授予对已保存查询的访问权限，请将这些用户添加到相应的 IAM 角色。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和查询文件夹，然后根据需要展开共享查询文件夹。找到要授予其访问权限的已保存查询。

3. 点击已保存的查询旁边的 查看操作，然后点击共享 > 管理权限。

4. 在管理权限窗格中，点击添加用户/群组。

5. 在新的主账号字段中，输入主账号。

6. 在角色列表中，选择以下角色之一：

   • Code Owner：可以对已保存的查询执行任何操作，包括删除或共享已保存的查询。
   • Code Editor：可以修改查询。
   • Code Viewer：可以查看查询。
   注意：主账号还必须具有 BigQuery User (roles/bigquery.user) 角色才能运行已保存的查询。

7. 可选：如需查看角色和高级共享设置的完整列表，请点击高级共享。

8. 点击保存。

9. 如需恢复为已保存的查询信息，请点击关闭。

共享已保存的查询

您可以通过生成并共享指向已保存查询的链接来与其他用户共享已保存的查询。您必须先授予用户访问已保存查询的权限，这些用户才能查看您共享的查询。

要运行共享查询，用户必须有权访问相应查询所访问的数据。如需了解详情，请参阅授予对数据集的访问权限。

如果您打算共享已保存的查询，请考虑在查询中添加描述其用途的注释。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和查询文件夹，然后根据需要展开共享查询文件夹。找到您要共享的已保存查询。

3. 点击查询旁边的 查看操作，然后点击共享 > 复制链接。

4. 与其他用户共享该链接。

将已保存的查询版本作为新查询打开

如需将现有已保存的查询的任何版本作为新查询打开，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和查询文件夹，然后根据需要展开共享查询文件夹。选择已保存的查询。

3. 选择活动窗格。

4. 点击已保存的查询版本旁边的 查看操作，然后点击作为新查询打开。

更新已保存的查询

如果您更新已保存的查询，则可以将更改保存到查询的新版本中。

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和查询文件夹，然后根据需要展开共享查询文件夹。点击已保存的查询名称将其打开。

3. 修改查询。

4. 如需保存修改后的查询，请点击 保存查询 > 保存查询。

   系统会创建查询的新版本，您可以在活动窗格中查看该版本。

上传已保存的查询

您可以上传本地 SQL 查询，以便在 BigQuery Studio 中将其用作已保存的查询。上传的已保存查询随后也会显示在 Google Cloud 控制台的 BigQuery 页面中。

如需上传已保存的查询，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目，然后执行以下操作之一：

   • 在查询旁边，点击 查看操作 > 上传 SQL 查询。
   • 在 Google Cloud 项目名称旁边，点击 查看操作 > 上传到项目 > SQL 查询。

3. 在上传 SQL 对话框的 SQL 字段中，点击浏览，然后选择要上传的查询。

4. 可选：在 SQL 名称字段中，修改查询的名称。

5. 在区域字段中，选择要在其中上传已保存的查询的区域。

6. 点击上传。

您已保存的查询会显示在探索器窗格中。

传统版已保存的查询

已弃用：BigQuery Studio 预览版中提供的已保存的查询将在 2025 年 3 月之前完全取代传统版已保存的查询。如需了解详情，请参阅弃用传统版已保存的查询。如需了解如何迁移到已保存的查询，请参阅迁移传统版已保存的查询。

请参阅以下部分，了解如何创建和更新传统版已保存的查询。如需详细了解如何共享、迁移和删除传统版已保存的查询，请参阅传统版已保存的查询。

注意：如果您尚未启用 BigQuery Studio，传统版已保存查询将显示在探索器窗格的已保存查询 (NUMBER) 文件夹中，而不是（传统版）查询文件夹中。

传统版已保存查询的必需权限

必须拥有以下 IAM 权限才能创建、查看、更新和删除传统版已保存的查询：

• 不公开的传统版已保存的查询：
  • 创建不公开的传统版已保存的查询无需任何特殊权限。您可以在任何项目中保存不公开的查询，但只有您才能查看、更新或删除它们。
• 项目级传统版已保存的查询：
  • 创建项目级传统版已保存的查询需要具有 bigquery.savedqueries.create 权限。bigquery.admin 预定义角色可提供 bigquery.savedqueries.create 权限。
  • 查看项目级传统版已保存的查询需要具有 bigquery.savedqueries.get 和 bigquery.savedqueries.list 权限。 bigquery.admin 和 bigquery.user 预定义角色可提供 bigquery.savedqueries.get 和 bigquery.savedqueries.list 权限。
  • 更新项目级传统版已保存的查询需要具有 bigquery.savedqueries.update 权限。bigquery.admin 预定义角色可提供 bigquery.savedqueries.update 权限。
  • 删除项目级传统版已保存的查询需要具有 bigquery.savedqueries.delete 权限。bigquery.admin 预定义角色可提供 bigquery.savedqueries.delete 权限。
• 公开的传统版已保存的查询：
  • 创建公开的传统版已保存的查询无需任何特殊权限。您可以在任何项目中保存公开的传统版已保存的查询，但只有您才能更新或删除它们。知道链接的任何人都可以查看公开的传统版已保存的查询。

注意：在项目级拥有 dataform.repository.list 权限的用户可以查看在项目中创建的所有已保存的查询。

如需详细了解 BigQuery 中的 IAM 角色，请参阅预定义的角色和权限。

创建传统版已保存查询

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 点击 编写新查询。

3. 在查询编辑器中，输入有效的 SQL 查询。 例如，您可以查询公共数据集：

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

4. 点击 保存查询（经典版）> 保存查询（经典版）。

5. 在保存查询对话框中，为您的查询输入一个名称，然后将公开范围设置为以下选项之一：

   • 个人（只能由您修改），用于不公开的传统版共享查询。
   • 项目（可由拥有相应权限的主账号修改），用于项目级传统版已保存的查询。
   • 公开，用于公开的传统版已保存的查询。

6. 点击保存。

共享传统版已保存查询

您可以共享公开范围为“项目”或“公开”的传统版查询。如果将公开范围设置为“项目”，则其具备所需权限的主账号可以查看、更新或删除该查询。如果将公开范围设置为“公开”，则任何知道查询链接的人员都可以查看该查询，但无法执行更新或删除操作。

您可以通过生成并共享指向传统版已保存查询的链接来与其他用户共享传统版已保存查询。

如需运行传统版共享查询，用户必须有权访问相应查询所访问的数据。如需了解详情，请参阅授予对数据集的访问权限。

如果您打算共享传统版已保存查询，请考虑在查询中添加描述其用途的注释。

1. 在探索器窗格中，展开您的项目和（传统版）查询文件夹，然后找到您要共享的传统版已保存查询。
2. 点击查询旁边的 查看操作，然后点击获取链接。
3. 与要授予查询访问权限的用户共享链接。

更新传统版已保存查询

1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

   转到 BigQuery

2. 在探索器窗格中，展开您的项目和（传统版）查询文件夹，然后根据需要展开项目查询文件夹。

3. 点击一个已保存的传统查询的名称将其打开。

4. 修改查询。

5. 如需保存修改后的查询，请点击 保存查询（经典版）> 保存查询（经典版）。

后续步骤

• 了解如何管理已保存的查询。