> ## 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.

# Oracle Upsert 配置

> 从工作流中的知行之桥消息插入或更新 Oracle 数据。

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

## 表格和列

Oracle Upsert 端口支持两种配置模式：**表结构** 和 **映射**。

**表结构** 是默认模式。当 **映射** 开关处于关闭状态时，单击 **添加表结构** 从 Oracle 中选择目标表。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_landing_page.png)

在 **编辑目标结构** 面板中，选择所需的表，然后单击 **应用**。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_table_modal.png)

> [!NOTE]
>
> 有关选择多个相关表的更多信息，请参阅 [子表](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/oracle/oracle-ac.md#子表)。

随即显示所选的表和列。端口会自动检测具有特殊相关性的值（例如主键）并相应地标记它们。右键单击某列可访问其他设置，包括该列的 UPSERT 设置。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_table_structure.png)

**映射** 模式提供完整的映射编辑器。启用 **映射** 开关即可切换到此模式。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_mapping_editor.png)

在 **目标** 面板中，单击 **添加目标结构**，选择目标表，然后单击 **应用**。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_add_destination_modal.png)

所选的表和列会显示在 **目标** 面板中。右键单击某列可访问其他设置，包括该列的 UPSERT 设置。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_destination_structure.png)

> [!NOTE]
>
> 添加目标结构或配置 UPSERT 设置不需要源模板。你可以在连接源之前，在仅结构模式下设置 UPSERT 键并保存。

## UPSERT 查询行为

在表结构模式和映射模式下，均按列配置 UPSERT 设置。右键单击某列，然后从上下文菜单中选择 **UPSERT 设置**。

随即打开 **UPSERT 设置** 对话框。默认情况下，**启用 UPSERT 设置** 开关为 **ON**，这意味着端口会先检查目标中是否已存在记录，再决定执行 INSERT 还是 UPDATE。

![](https://docs.kasoftware.com/26.4/images/dbsa_upsert_settings_dialog.png)

用于确定记录是否存在的查询由以下部分中描述的逻辑控制。

### UPSERT 设置已启用

当 **启用 UPSERT 设置** 处于开启状态时，查询行为取决于在 **UPSERT 设置** 列表中选择的选项：**UPSERT by**（按单列匹配）或 **Query to select UPSERT key**（使用自定义查找查询）。

#### 按 ID UPSERT

在 **UPSERT 设置** 列表中选择 **UPSERT by** 并选择表的键列后，端口会发出查询，以确定是否存在具有匹配键值的任何记录：

```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 设置** 列表中选择 **UPSERT by** 并选择非键列后，端口会发出查询，以确定是否存在该列包含匹配值的记录，SELECT 语句以表的主键为目标（以下示例演示向 Orders 表执行 UPSERT）：

```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 设置** 列表中选择 **Query to select UPSERT key** 后，可以编写自定义查询来确定 UPSERT 键。这样可以使用比单列匹配更复杂的逻辑来执行查找。考虑以下查询：

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

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

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

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

### UPSERT 设置已禁用

要对某列禁用 UPSERT 行为，请打开 **UPSERT 设置** 对话框（右键单击目标列并选择 **UPSERT 设置**），将 **启用 UPSERT 设置** 切换为 **OFF**，然后单击 **应用**。

禁用 UPSERT 设置后，端口仅发出 INSERT 查询。检查输入映射的代码视图显示表的 `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 配置的 Oracle 端口选择表格和列后，将端口放置在 知行之桥 工作流的末尾。下面的屏幕截图描述了一个示例流程，其中包含一个 File 端口、一个 CSV 端口和一个 Oracle Upsert 端口：

![](https://docs.kasoftware.com/26.4/images/oracle_upsert.png)

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

<ol><li>File 端口从磁盘提取 CSV 文件并将其放入流程中。</li>
<li>**CSV1** 端口将 CSV 文件转换为 XML。</li>
<li>**Oracle\_Upsert** 端口接收 XML 数据。在端口的 **操作** 选项卡上使用映射模式直接配置列映射，如 [表和列](#表和列) 中所述。然后，端口执行 Upsert 并将结果数据传递给 Oracle。</li></ol>


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