此页面由 Cloud Translation API 翻译。

创建操作

本文档介绍了如何在专用 SQLX 文件中定义自定义 SQL 操作。

Dataform 可以运行不适合发布表或写入断言的 Dataform 模型的自定义 SQL 操作。您可以定义自定义 SQL 命令，供 Dataform 在 BigQuery 中运行。

准备工作

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

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

将自定义操作定义 SQLX 文件存储在 definitions/ 目录中。如需在 definitions/ 目录中创建新的 SQLX 文件，请按以下步骤操作：

前往您的开发工作区。
在文件窗格中，点击 definitions/ 旁边的更多菜单。
点击创建文件。
在添加文件路径字段中，输入文件名称，然后在 definitions/ 后面添加 .sqlx。例如 definitions/sample-operation.sqlx。

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

您可以在 type: operations 的 SQLX 文件中定义自定义 SQL 操作。您可以在 operations 文件中编写任何 BigQuery SQL 语句。Dataform 会在 BigQuery 中运行您的自定义 SQL 操作，而不会进行修改。

您可以在一个 SQLX 文件中定义多个自定义 SQL 操作。 BigQuery 会在同一上下文中运行文件中的所有操作，并通过使用分号 (;) 连接所有操作来创建运行 SQL。

如果将开源 Dataform 框架与 BigQuery 以外的数据仓库搭配使用，要定义多个自定义 SQL 操作，请使用 --- 分隔各个操作。

如需在专用 SQLX 文件中定义自定义 SQL 操作，请按以下步骤操作：

以下代码示例展示了在 operations 文件中定义的多个自定义 SQL 操作：

config { type: "operations" }

DELETE FROM dataset.table WHERE country = 'GB';

DELETE FROM dataset.table WHERE country = 'FR';

以下代码示例展示了手动创建视图的自定义 SQL 操作：

config { type: "operations" }
CREATE OR REPLACE VIEW dataset.table AS (SELECT 1 AS TEST)

您可以在自定义 SQL 操作中手动创建一个表，然后在其他脚本中引用该表。如需创建可供其他脚本使用的表，您需要声明相应操作具有输出。

为了使输出表的名称与 operations 文件的名称一致，您可以在 CREATE 操作中使用 self 函数。

如需在自定义操作中创建表格并使其可供其他脚本使用，请按以下步骤操作：

在开发工作区中，选择用于自定义操作定义的 SQLX 文件。
在 SQLX 文件中，输入以下代码段：
```
config {
 type: "operations",
 hasOutput: true
}
```
重要提示：当 hasOutput 设置为 true 时，此操作必须创建与该操作同名的表。使用 self() 上下文函数可确保名称相同。
为了使输出表的名称与文件的名称一致，请使用以下格式通过 self 函数编写 SQL CREATE 操作：
```
CREATE OR REPLACE TABLE ${self()} AS (CUSTOM_SQL_QUERY)
```
将 CUSTOM_SQL_QUERY 替换为您的表定义 SQL SELECT 语句。
可选：点击格式。

以下代码示例展示了 custom_SQL_operation_table.sqlx 文件中的自定义 SQL 操作，该操作会创建一个名为 custom_SQL_operation_table 的可引用表：

// filename is custom_SQL_operation_table.sqlx
config {
type: "operations",
hasOutput: true
}
CREATE OR REPLACE VIEW ${self()} AS (SELECT 1 AS TEST)

以下代码示例展示了如何在表定义 SQLX 文件中引用 custom\_SQL\_operation\_table table：

config { type: "table" }
SELECT * FROM ${ref("custom_SQL_operation_table")}

您可能需要创建一个空表，以便其他服务可以向其中填充数据。您可以使用 CREATE TABLE 函数在自定义 SQL 操作中创建空表。为了能够在其他工作流操作定义（例如表和视图）中引用空表，您可以将 hasOutput:true 属性添加到空表操作的 config 块。

config {
  type: "operations",
  hasOutput: true  // optional, lets you reference the empty table
}

CREATE TABLE ${self()} (

)

以下代码示例展示了一个自定义 SQL 操作，该操作可创建一个包含整数列和字符串列的空表。创建的空表无法被其他工作流操作引用：

config {
  type: "operations"
}

CREATE TABLE ${self()} (
  x INT64,
  y STRING
)