声明数据源

本文档介绍了如何使用 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. 在开发工作区的文件窗格中，点击用于数据源声明的 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. 在开发工作区的文件窗格中，点击用于数据源声明的 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",
    }

后续步骤