# 添加 SQL 转换

您可以在转换任务中包含基于 SQL 的表。SQL 转换允许您将 SQL SELECT 查询输入到管道中，以定义复杂或简单的转换。您可以让 SQL assistant 使用生成式 AI 从文本提示生成查询。您还可以使用宏来调整查询，以便在执行初始加载或增量加载时运行。

在将 SQL 添加到转换之前，您可以使用 SQL workbench 探索数据并验证只读 SQL。有关更多信息，请参阅 [使用 SQL Workbench 探索数据](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/SQL-workbench-data-exploration.htm)。

有关创建转换任务的更多信息，请参阅 [转换数据](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Transformations.htm)。

## 添加 SQL 转换

要在转换数据任务中添加 SQL 转换：

1. 在转换中，选择要包含在查询中的数据集，然后单击添加 SQL 转换。

   在名称中设置转换的名称。有关其他设置的更多信息，请参阅 [设置](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Adding-SQL-based-tables.htm#Settings)。

   准备好创建 SQL 转换后，单击添加。

   将显示编辑 SQL 转换。

2. 在查询窗格中编写查询以返回基于 SQL 的表。

   有关更多信息，请参阅 [编辑 SQL 查询](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Adding-SQL-based-tables.htm#Editing)。

3. 单击运行查询。

   这将获取元数据和数据预览。

4. 在参数中查看参数。

   有关更多信息，请参阅 [参数](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Adding-SQL-based-tables.htm#Paramete)。

5. 在元数据中设置主键。

   有关更多信息，请参阅 [元数据](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Adding-SQL-based-tables.htm#Metadata)。

6. 当您对查询结果感到满意时，单击保存并关闭。数据集现在已添加到目标列表中，您可以预览它。

## 编辑 SQL 查询

在查询窗格中键入查询以返回基于 SQL 的表。查询只能从您选择的源数据集中读取，但您可以使用添加来添加更多源数据集。

* 您可以创建一条语句以从对象加载数据集。单击 the 添加 SELECT 语句 icon，然后单击。

* 您可以通过单击 the 复制 icon，然后单击，将数据集的名称复制到剪贴板。

* 单击 > 将数据集或列名移动到编辑器中。

* 单击 the 搜索 icon 在编辑器中搜索并替换文本。

信息注释您可以使用 SQL assistant 通过生成式 AI 生成查询。有关更多信息，请参阅 [从文本提示生成 SQL 转换](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Generating-SQL-from-text-prompt.htm)。SQL assistant 在 Qlik Cloud 政府 中不可用。

如果使用增量加载，您可以使用宏来调整查询，以便在执行初始加载或增量加载时运行。

有关更多信息，请参阅 [使用宏使查询适应加载类型](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/DataIntegration/Transformation/Adding-SQL-based-tables.htm#Using)。

### 键盘快捷键

信息注释键盘快捷键的表达假设您在 Windows 中工作。对于 macOS，请使用 Command 而不是 Ctrl。

* Ctrl+F 搜索并替换

* Ctrl+/ 注释/取消注释当前行

* Ctrl+Enter 运行查询

* Ctrl+Z 撤消

* Ctrl+Y 重做

### 预览结果

您可以使用结果中的数据样本预览结果。

信息注释必须在 Administration 中的租户级别启用数据预览。您可以在设置中的功能控制下找到在 数据集成 中查看数据选项。

必须为您分配以下角色才能预览数据：

* 在连接所在的空间中具有可以查看数据角色。

* 在项目所在的空间中具有可以查看角色。

将显示使用数据样本的结果。您可以使用行数设置样本中包含的数据行数。

* 单击上次执行的查询以查看上次执行查询的最后运行时间和持续时间。

#### 过滤结果

您可以按一列或多列过滤结果。

* 单击要过滤的第一列上的 the 过滤 icon，然后单击。

  选择要使用的运算符以及要过滤的值。

  您可以通过单击添加过滤器来添加更多列过滤器。

过滤器只会影响现有的样本数据。

#### 对结果进行排序

您可以按特定列对数据样本进行排序。

* 单击要排序的列上的 the 升序排序 icon，然后单击或降序排序。

排序只会影响现有的样本数据。如果您使用过滤器仅包含 2024 年的订单并反转排序顺序，则样本数据仍将仅包含 2024 年的订单。

#### 管理显示的列

您可以选择在结果中显示哪些列。保存转换时不会保存此选择。

* 通过单击列上的 the 隐藏列 icon，然后单击来隐藏列。

* 通过单击任意列上的 the 显示的列 icon，然后单击来管理所有列的显示。

### 参数

单击参数以更改 SELECT 查询中的参数。参数应映射到源对象或目标对象。

在以下情况下，参数会自动映射：

* 在对象中使用添加 SELECT 语句。

* 单击 > 将数据集或列名移动到编辑器中。

* 参数名称与对象中表的表名匹配。

信息注释如果使用任意参数名称，则必须手动映射参数。只有与数据集名称匹配的参数名称才会被自动映射。

您可以映射到

* 历史类型 2 结构 (\_history)

* 当前结构

* 目标对象

  只有当参数在增量宏内部定义时，您才能映射目标对象。

提示注释您可以将参数替换为引用，以使查询更易于阅读。更改参数中的值，SELECT 查询中的引用也会随之更改。

### 元数据

您可以在元数据中编辑元数据设置。

* 在键列中设置主键。

  通过单击建议并验证键，您可以获得合适主键的建议并验证这些键。

* 在可为空列中设置该列是否可为空。

* 选择一列并单击编辑以设置列名、键、可为空和数据类型。

#### 建议并验证键

通过单击建议并验证键，您可以获得合适主键的建议并验证这些键。完整的 SQL 查询必须至少运行过一次。

* 如果您选择加入跨区域推理，则会使用 GenAI 来建议键。这允许 Qlik Cloud 将推理请求发送到您的租户区域之外。有关推理处理位置的详细信息和最新信息，请参阅 [启用跨区域推理](https://help.qlik.com/zh-CN/cloud-services/Subsystems/Hub/Content/Sense_Hub/Admin/cross-region-data-processing.htm)。

  信息注释Qlik 不控制生成的输出。由于 GenAI 的性质，如果不进行审查或编辑，响应可能无法生成满足您要求的 SQL。根据 Qlik 客户协议的条款，生成的查询被视为“内容”。

  Qlik Cloud Government 注释

  GenAI 辅助的键建议在 Qlik Cloud 政府 中不可用。

  如果未启用 GenAI，将根据源表数据以编程方式建议键。

* 验证将始终在不使用 GenAI 的情况下执行，通过运行 SQL 查询来确保没有重复项或 NULL 值。

  信息注释仅当查询返回数据时，验证才可用。

* 建议并验证键

  这将审查查询和源表键，并建议有效的主键。此操作可能需要一些时间。

* 验证键

  这将验证现有的主键，以确保它们是唯一的且非 NULL。此操作可能需要一些时间。

* 建议但不验证

  这将审查查询和源表键，并建议主键而不进行验证。在应用键之前，请手动审查并验证它们。

## 运行查询

在开发过程中，您可以随时通过单击运行查询来运行查询。首次运行查询时，将检索元数据。运行查询后，您可以转到元数据并设置主键，这是完成转换所必需的。

信息注释如果编辑器包含多个查询，您可以通过选择查询并单击运行查询来运行单个查询。

## 使用宏使查询适应加载类型

如果使用增量加载，您可以使用宏来调整查询，以便在执行初始加载或增量加载时运行。

选择宏并将查询添加到相应的子句中。

* Q\_RUN\_INCREMENTAL 添加一个子句，您可以在其中放置仅在执行增量加载时运行的查询。

* Q\_RUN\_INITIAL\_LOAD 添加一个子句，您可以在其中放置仅在执行初始加载时运行的查询。

您不需要为每个宏指定完整的查询。您可以根据您的用例调整或添加代码。

### 用例：使用日期范围的增量过滤器：

在此用例中，需要使用自定义 SQL 转换一组订单数据。由于这是一个大型数据集，您希望包含增量过滤，以确保增量加载仅考虑过去 12 小时内的订单。

这是基本查询：

```
  SELECT O.ORDER_ID, O.CUSTOMER_ID,  OD.PRODUCT_ID, OD.QUANTITY, O.AMOUNT , OD.LAST_UPDATE_DTM 
   FROM “mydb”.”myStorageTask”.”ORDER” O
   JOIN  “mydb”.”myStorageTask”.”ORDER_DETAIL” OD
      ON O.ORDER_ID = OD.ORDER_ID 

```

这是在增量运行期间应用的过滤器，您只考虑过去 12 小时内添加的订单：

```
   WHERE OD.UPDATE_DTM >  DATEADD(hour, -12, CURRENT_TIMESTAMP())
```

提示注释在实现基于 SQL 的表时，建议将表名替换为 ${TABLE} 表示法。这可以防止硬编码数据库和模式名称，这些名称可能会因环境而异，例如从开发环境转移到生产环境时。

这是完整的查询，使用了过滤器宏，并将表名替换为 ${TABLE} 表示法：

```
  SELECT O.ORDER_ID, O.CUSTOMER_ID,  OD.PRODUCT_ID, OD.QUANTITY, O.AMOUNT , OD.LAST_UPDATE_DTM
   FROM ${ORDER} O
   JOIN  ${ORDER_DETAIL} OD
      ON O.ORDER_ID = OD.ORDER_ID 
{{#QLIK_FUNC_IF Q_RUN_INCREMENTAL}}
   WHERE OD.UPDATE_DTM > DATEADD(hour, -12, CURRENT_TIMESTAMP() )
{{/QLIK_FUNC_IF}}      

```

这会产生一个初始加载查询：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT , OD.LAST\_UPDATE\_DTM FROM ${ORDER} O JOIN ${ORDER\_DETAIL} OD ON O.ORDER\_ID = OD.ORDER\_ID

以及一个增量加载查询：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT , OD.LAST\_UPDATE\_DTM FROM ${ORDER} O JOIN ${ORDER\_DETAIL} OD ON O.ORDER\_ID = OD.ORDER\_ID WHERE OD.UPDATE\_DTM > DATEADD(hour, -12, CURRENT\_TIMESTAMP() )

### 用例：使用目标中的数据进行增量过滤：

在此用例中，需要使用自定义 SQL 转换一组订单数据。由于订单是一个大型数据集，您希望包含增量过滤，以确保增量加载仅考虑比目标表中的数据更新的订单详细信息记录。您还希望标记某行是由初始加载还是增量加载处理的。

信息注释正如您从此示例中看到的，宏可用于调整查询的任何部分以进行初始加载或增量加载。

这是基本查询：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT , OD.LAST\_UPDATE\_DTM FROM “mydb”.”myStorageTask”.”ORDER” O JOIN “mydb”.”myStorageTask”.”ORDER\_DETAIL” OD ON O.ORDER\_ID = OD.ORDER\_ID

这是在增量运行期间应用的过滤器。“ORDERS\_DERIVED” 是目标数据集的名称。

WHERE OD.UPDATE\_DTM > = (SELECT MAX(LAST\_UPDATE\_DTM) FROM “mydb”.”myTrasformTask”.”ORDERS\_DERIVED” )

提示注释增量加载还可以将 ${TABLE} 表示法映射到由转换任务创建的目标对象。

这是完整的查询，使用了过滤器宏，并将表名替换为 ${TABLE} 表示法。如果加载是初始加载，则 LOADED\_BY 设置为 INIT，如果加载是增量加载，则设置为 INCR：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT, OD.LAST\_UPDATE\_DTM, {{#QLIK\_FUNC\_IF Q\_RUN\_INITIAL\_LOAD}} ‘INIT’ as LOADED\_BY {{/QLIK\_FUNC\_IF}} {{#QLIK\_FUNC\_IF Q\_RUN\_INCREMENTAL}} ‘INCR’ as LOADED\_BY {{/QLIK\_FUNC\_IF}} FROM ${ORDER} O JOIN ${ORDER\_DETAIL} OD ON O.ORDER\_ID = OD.ORDER\_ID {{#QLIK\_FUNC\_IF Q\_RUN\_INCREMENTAL}} WHERE OD.UPDATE\_DTM >= (SELECT MAX(LAST\_UPDATE\_DTM) FROM ${TARGET\_TABLE} ) {{/QLIK\_FUNC\_IF}}

这会产生一个初始加载查询：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT, OD.LAST\_UPDATE\_DTM, ‘INIT’ as LOADED\_BY FROM ${ORDER} O JOIN ${ORDER\_DETAIL} OD ON O.ORDER\_ID = OD.ORDER\_ID

以及一个增量加载查询：

SELECT O.ORDER\_ID, O.CUSTOMER\_ID, OD.PRODUCT\_ID, OD.QUANTITY, O.AMOUNT, OD.LAST\_UPDATE\_DTM, ‘INCR’ as LOADED\_BY FROM ${ORDER} O JOIN ${ORDER\_DETAIL} OD ON O.ORDER\_ID = OD.ORDER\_ID WHERE OD.UPDATE\_DTM >= (SELECT MAX(LAST\_UPDATE\_DTM) FROM ${TARGET\_TABLE} )

## 设置

单击 the 设置 icon 以编辑 SQL 转换的设置。

在名称中输入目标数据集的名称。

也可以在描述中添加较长的说明。

在具体化中，选择转换后的输出是否应具体化。您可以选择从数据任务设置中继承设置。
* 如果开启，将创建表格并处理相关的 ELT 处理。

* 选择关闭将创建即时执行转换的视图。

在历史数据存储（类型 2）中，选择是否要保留历史数据。您可以选择从数据任务设置中继承设置。此设置要求开启物化功能。

增量加载允许您通过应用筛选器或其他条件来调整增量数据加载的查询，以减少使用宏处理的数据集。只有当数据具体化为表时，增量加载才可用。
* 如果增量加载开启

  任务的第一次执行将执行初始加载，将查询的所有结果插入到目标表中。后续执行将利用您为增量处理定义的筛选器或特定条件执行增量加载。在增量加载期间，任务将只把数据作为更新或插入处理，不管理删除。

* 如果增量加载关闭

  任务的第一次执行将执行初始加载，将查询的所有结果插入到目标表中。后续执行将通过与目标表进行比较来处理查询的所有结果，并处理新的、更改的或删除的记录。

信息注释如果查询将选择目标中应该存在的所有记录，请将增量加载设置为关闭。将从目标中删除未选择的记录。

## 最佳实践

* 添加 SQL 转换时，不会自动定义主键。在数据集选项卡中向数据集添加键。

* 不要在转换后的输出中手动创建列标题。

* 避免使用带有 \* 的 SELECT，因为这可能会在每次运行查询时返回不同的列。如果模式发生更改，请相应地更改查询并再次执行描述表。然后您可以编辑列并调整表。