> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CData Upsert 配置

> 从流程中的知行之桥消息插入或更新 CData 数据。

Upsert 操作插入或更新 CData 数据。默认情况下，如果 CData 中已存在记录，则使用输入提供的值对 CData 中的现有数据执行更新。有关详细信息，请参阅 [UPSERT 查询行为](#upsert-查询行为)。

> [!NOTE]
>
> CData 端口已弃用。与其他数据库端口不同，它不支持映射模式，因此 Upsert 操作仍需要使用 XML Map 端口来映射列。

## 表和列

如果为 CData 端口选择 Upsert，则必须从 CData 中选择一个（或多个）目标表。单击**表格**面板上方的**添加**按钮。

![Upsert 配置面板，显示带有添加按钮的表格部分。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_upsert_tableadd.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=f87824e88131c0c880b2413401db18b3)

一个模态框出现并列出所有可用的表格。选择所需的表并单击**添加**。

![添加表模态框列出了可用的表，其中选中了 Orders 表，底部有添加按钮。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_tablelist.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=e9320e7d1ceef209409426e626aa9bda)

选定的表出现在**表格**面板下，表中的列出现在**列**面板下。端口会自动检测具有特殊相关性的值（例如主键和外键）并相应地标记它们。

![选中 Orders 表的 Upsert 配置面板，列面板中 Id 列的 UPSERT 开关设置为 ON，UPSERT By 字段设置为 Id。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_upsert_columns.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=bbd74c49ffefc0f82e04ceefd35f2294)

默认情况下，所有列都被选中以包含在 CData 端口的操作中。你可以通过取消选中来删除单个列。

> [!NOTE]
>
> 你可以通过单击**添加**并重复此过程来选择更多表。有关详细信息，请参阅[子表](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/cdata/cdata-ac.md#子表)。

## UPSERT 查询行为

默认情况下，列映射中的 **UPSERT** 滑块设置为 **ON**。这意味着 UPSERT 映射在 INSERT 记录（如果没有匹配记录）或 UPDATE 记录（如果记录已存在）之前确定记录是否存在于目标中。

![Upsert 配置面板，Id 列上的 UPSERT ON 开关被突出显示。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_upsert_slider.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=8ef7a8c05109cd9f9196a7b9c41a4d00)

用于确定该值的查询由以下部分中描述的逻辑确定。

### UPSERT 滑块设置为开启

当滑块设置为 **ON** 时，查询行为会根据在 **UPSERT By** 和**执行此查询...** 单选按钮中选择的内容而变化。

#### 按 ID 执行 UPSERT

如果输入 XML 中存在键列，则会向数据库发出查询以确定是否存在具有匹配键的任何记录：

```text theme={null}
The action type is UPSERT and an UPSERT query is not specified. The key column [Id] is present and will be determined using an automatically generated UPSERT query.
SELECT COUNT(*) AS [count] FROM [Orders] WHERE [Id] = @Id; @Id='123'
```

匹配结果更新；没有匹配结果导致插入。

如果输入 XML 中不存在键列，则始终插入记录：

```text theme={null}
The key column Id was not specified, INSERT will be executed.
The action type is UPSERT or an UPSERT query is specified. The key column is not present. Record will be INSERTED.
```

#### 按非键列执行 UPSERT

通过选择表的主键，向数据库发出查询，以确定是否存在所选 **UPSERT By** 列包含匹配值的记录：

```sql theme={null}
SELECT [Id] FROM [Orders] WHERE [OrderId] = @OrderId; @OrderId='12345'
```

SELECT 查询始终以 SELECT 语句中表的键列为目标。如果匹配成功，则输入 XML 中的数据将更新到数据源中。如果没有匹配，则插入记录。

> [!NOTE]
>
> 如果输入中未指定所选的 **UPSERT By** 列，则查找将与 NULL 值一起使用，如以下查询所示：

```sql theme={null}
SELECT [Id] FROM [Orders] WHERE [OrderId] = @OrderId; @OrderId=NULL
```

#### 使用自定义查询

还可以编写自定义查询来选择 UPSERT 键。此选项允许使用比单列匹配更复杂的逻辑来执行查找。考虑以下查询：

```sql theme={null}
SELECT [Id] FROM [Orders] WHERE [OrderId] = @OrderId AND Status = 'Active'
```

在此示例中，必须选择表的键列，以便为 UPDATE 提供足够的条件。`@OrderID` 语法用于引用匹配输入 XML 中的值。还可以使用静态值：`'Active'` 周围的引号表示该子句使用静态值。

同样，键列的成功匹配用于形成更新请求。如果没有匹配，则插入记录。

> [!TIP]
>
> 当对数据库插入的行为有疑问时，请查看 UPSERT 尝试的 `.log` 文件：用于指导该行为的逻辑的完整细分将发送到日志文件。

### UPSERT 滑块设置为关闭

当滑块设置为 **OFF** 时，端口只需将所有查询插入数据库即可。检查输入映射的代码视图显示表的 `action` 属性是 `insert`：

```xml theme={null}
<Items>
    <Orders table="`Orders`" action="insert">
```

无论主键是否存在，向表发出的所有查询都被视为插入。要根据表更新所有收到的记录，可以将此操作关键字设置为 `update`，如以下代码片段所示：

```xml theme={null}
<Items>
    <Orders table="`Orders`" action="update">
```

> [!WARNING]
>
> 当操作定义为 `update` 时，应用程序期望表的键列（例如 Id）存在。如果未提供键列，则 UPDATE 命令的效果可能会因目标数据库类型而异，因此可能会看到更改的行数比预期多，或者根本没有更改。

## 知行之桥流程示例

为 Upsert 配置的 CData 端口选择表格和列后，将端口放置在知行之桥工作流的末尾。下面的屏幕截图描述了一个示例流程，其中包含一个 File 端口、一个 CSV 端口、一个 XML Map 端口，以及末尾的一个 CData Upsert 端口：

![知行之桥示例工作流，依次显示四个端口：File\_Receive、CSV1、XMLMap1 和 CData\_Upsert。](https://mintcdn.com/qiao/4hcVjuRd69QHuQ3V/26.4/images/cdata_xmlflow_upsert.png?fit=max\&auto=format\&n=4hcVjuRd69QHuQ3V\&q=85\&s=0f8aec729fea0a9e80e2c383727ce0b3)

此示例工作流中的数据通过以下步骤：

<ol>
  <li>File 端口从磁盘提取 CSV 文件并将其放入流程中。</li>
  <li>**CSV1** 端口将 CSV 文件转换为 XML。</li>
  <li>此数据作为**源文件**传递给 **XML\_Map** 端口，后者映射到**源**树状结构中。</li>
  <li>来自 **CData\_Upsert** 端口的数据作为**目标文件**传递给 **XML\_Map** 端口，后者映射到**目标**树状结构。![XML Map 端口的映射界面，左侧为源树（source.xml），右侧为目标树（destination.xml），元素之间尚未建立映射。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_xmlmap_upsert.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=f9419a524b386a274de0fd945d671e73)</li>
  <li>**XML\_Map** 端口尝试自动将**源**元素映射到具有相同名称的**目标**元素。你可以手动更改这些映射，并通过将元素从**源**拖到**目标**来填充空白映射。![XML Map 端口的映射界面，源树中的元素已映射到目标树，以曲线连接 first 到 firstName、last 到 lastName 等字段。](https://mintcdn.com/qiao/92y00drsn6lqgU2C/26.4/images/dbsa_xmlmap_elements.png?fit=max\&auto=format\&n=92y00drsn6lqgU2C\&q=85\&s=7bd435b8bd7c60a55589b1fd3a40545f)</li>
  <li>**CData\_Upsert** 端口根据映射执行 Upsert 并将结果数据传递给 CData。</li>
</ol>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.