声明数据源

本文档介绍了如何使用 Dataform 核心声明 BigQuery 数据源。

您可以在 Dataform 中将任何 BigQuery 表类型声明为数据源。声明 Dataform 之外的 BigQuery 数据源后，您可以将这些数据源视为 Dataform 对象。

声明数据源是可选操作，但在您想要执行以下操作时，声明数据源会很有用：

  • 引用或解析声明的来源的方式与 Dataform 中的任何其他表相同。
  • 在直观呈现的 Dataform 图表中查看声明的来源。
  • 使用 Dataform 管理外部创建的表的表级和列级说明。
  • 触发包含外部数据源的所有依赖项的工作流调用。

您可以使用 JavaScript 或 SQLX 文件声明数据源。在 JavaScript 文件中，您可以为每个文件声明多个数据源。在 SQLX 文件中，每个文件可以声明一个数据源。

准备工作

在声明数据源之前，请在代码库中创建并初始化开发工作区。

所需的角色

如需获得声明数据源所需的权限，请让您的管理员为您授予工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

为多个数据源声明创建 JavaScript 文件

将数据源声明的 JavaScript 文件存储在 definitions/ 目录中。如需在 definitions/ 目录中创建新的 JavaScript 文件，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，进入 Dataform 页面。

    前往 Dataform 页面

  2. 选择一个代码库。

  3. 选择一个开发工作区。

  4. 在文件窗格中，点击 definitions/ 旁边的更多菜单。

  5. 点击创建文件。

  6. 在创建新文件窗格中，执行以下操作：

    1. 在添加文件路径字段中，在 definitions/ 后面输入文件名称，后跟 .js。例如 definitions/declarations.js。

      文件名只能包含数字、字母、连字符和下划线。

    2. 点击创建文件。

向 JavaScript 文件添加声明

您可以在每个 JavaScript 文件中声明多个数据源。如需添加新的声明，请按以下步骤操作：

  1. 在开发工作区中的 Files 窗格中，点击数据源声明的 JavaScript 文件。

  2. 在该文件中，针对每个数据源添加以下代码段：

      declare({
    database: "DATABASE_PROJECT_ID",
    schema: "BIGQUERY_SCHEMA",
    name: "RELATION_NAME",
  });

    替换以下内容：

    • DATABASE_PROJECT_ID：包含数据源的项目的项目 ID。
    • BIGQUERY_SCHEMA：数据源所在的 BigQuery 数据集。
    • RELATION_NAME：您要用作数据源的表或视图的名称。您稍后可以使用该名称在 Dataform 中引用数据源。

创建用于数据源声明的 SQLX 文件

将数据源声明的 SQLX 文件存储在 definitions/ 目录中。如需在 definitions/ 目录中创建新的 SQLX 文件，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，进入 Dataform 页面。

    前往 Dataform 页面

  2. 选择一个代码库。

  3. 选择一个开发工作区。

  4. 在文件窗格中，点击 definitions/ 旁边的更多菜单。

  5. 点击创建文件。

  6. 在创建新文件窗格中，执行以下操作：

    1. 在添加文件路径字段中，在 definitions/ 后面输入文件名称，后跟 .sqlx。例如 definitions/dataset-declaration.sqlx。

      文件名只能包含数字、字母、连字符和下划线。

    2. 点击创建文件。

声明数据源

每个 SQLX 声明文件可以声明一个数据源。如需在 SQLX 文件的配置块中声明数据源，请按以下步骤操作：

  1. 在开发工作区中的 Files 窗格中，点击数据源声明的 SQLX 文件。

  2. 在文件中输入以下代码段：

    config {
  type: "declaration",
  database: "DATABASE",
  schema: "SCHEMA",
  name: "NAME",
}

    替换以下内容：

    • DATABASE：包含数据源的项目的项目 ID。
    • SCHEMA：数据源所在的 BigQuery 数据集。
    • NAME：您要用作数据源的表或视图的名称。您稍后可以使用该名称在 Dataform 中引用数据源。

  3. 可选：点击格式。

以下代码示例展示了将 bigquery-public-data 项目的 samples 数据集中的 shakespeare 表声明为数据源的示例：

    config {
      type: "declaration",
      database: "bigquery-public-data",
      schema: "samples",
      name: "shakespeare",
    }

后续步骤