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

# Databricks Upsert

> フロー内のArc メッセージからDatabricks のデータを挿入または更新します。

Upsert アクションは、Databricksのデータを更新または挿入します。デフォルトでは、Databricksにレコードがすでに存在する場合、入力から提供された値を使用してDatabricks内の既存データに対して更新が実行されます。詳細については、[UPSERT クエリの動作](#upsert-query-behavior)を参照してください。

## テーブルとカラム

Databricks Upsert コネクタは、**Table Structure** と**Mapping** の2つの構成モードをサポートしています。

**Table Structure** がデフォルトです。**Mapping** トグルがオフの場合、**Add Table Structure** をクリックしてDatabricksから対象のテーブルを選択します。

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

**Edit Destination Structure** ペインで目的のテーブルを選択し、**Apply** をクリックします。

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

> [!NOTE]
>
> 複数の関連テーブルの選択について詳しくは、[子テーブル](https://docs.arc.cdata.com/26.4/self-hosted/ja/connectors/databricks/databricks-ac.md#child-tables)を参照してください。

選択したテーブルとカラムが表示されます。コネクタは、主キーなど特別な意味を持つ値を自動的に検出し、それに応じてラベルを付けます。カラムを右クリックすると、そのカラムのUPSERT 設定を含む追加の設定にアクセスできます。

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

**Mapping** モードでは、フルマッピングエディタが有効になります。**Mapping** トグルを有効にして、このモードに切り替えます。

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

**Destination** ペインで**Add Destination Structure** をクリックし、対象のテーブルを選択して**Apply** をクリックします。

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

選択したテーブルとカラムが**Destination** ペインに表示されます。カラムを右クリックすると、そのカラムのUPSERT 設定を含む追加の設定にアクセスできます。

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

> [!NOTE]
>
> 宛先構造の追加やUPSERT 設定の構成にソーステンプレートは必要ありません。ソースを接続する前に、構造のみのモードでUPSERT キーを設定して保存できます。

## UPSERT クエリの動作

UPSERT 設定は、Table Structure モードとMapping モードの両方でカラムごとに設定します。カラムを右クリックし、コンテキストメニューから**UPSERT Settings** を選択します。

**UPSERT Settings** ダイアログが開きます。デフォルトでは**Enable UPSERT settings** トグルは**ON** になっており、コネクタはINSERT かUPDATE かを決定する前に、宛先にレコードがすでに存在するかどうかを確認します。

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

レコードが存在するかどうかを判定するために使用されるクエリは、以下のセクションで説明するロジックによって制御されます。

### UPSERT 設定を有効化

**Enable UPSERT settings** がON の場合、クエリの動作は**UPSERT Settings** リストで選択したオプションによって決まります：**UPSERT by**（単一カラムでの一致）または**Query to select UPSERT key**（カスタムルックアップクエリの使用）。

#### Id によるUPSERT

**UPSERT Settings** リストで**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 Settings** リストで**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 Settings** リストで**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 Settings** ダイアログを開き（宛先カラムを右クリックして**UPSERT Settings** を選択します）、**Enable UPSERT settings** を**OFF** に切り替えて、**Apply** をクリックします。

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 コマンドの効果は対象のデータベースタイプによって異なる可能性があるため、予想より多くの行が変更されたり、まったく変更されなかったりする場合があります。

## Arc フローの例

Upsert で構成されたDatabricksコネクタのテーブルとカラムを選択したら、そのコネクタをArc フローの末尾に配置します。次のスクリーンショットは、File コネクタ、CSV コネクタ、および末尾のDatabricks Upsert コネクタから成るフローの例を示しています。

![](https://docs.arc.cdata.com/26.4/images/databricks_upsert.png)

このフローの例では、データは次の手順を通過します。

<ol><li>File コネクタがディスクからCSV ファイルを取得してフローに取り込みます。</li>
<li>**CSV1** コネクタがCSV ファイルをXML に変換します。</li>
<li>**Databricks\_Upsert** コネクタがXML データを受信します。[テーブルとカラム](#tables-and-columns)で説明されているMapping モードを使用して、コネクタの**Action** タブでカラムマッピングを直接設定します。その後、コネクタはUpsert を実行し、結果のデータをDatabricksに渡します。</li></ol>


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