# MySQL Tables Export Integration

この記事では、既存のMySQLインスタンスにジョブ結果を書き込む方法について説明します。

サンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/mysql)を参照してください。

## 前提条件

- TD Toolbeltを含むTreasure Dataの基本的な知識
- **MySQL**インスタンス
- Treasure DataはSELECT、INSERT、DELETE、CREATE、DROP、およびALTER権限を持っている必要があります


replaceモードを使用すると、MySQLテーブルのスキーマが変更される場合があります。ターゲットテーブルへのスキーマ変更を避けるには、「スキーマを保持する」オプションを選択してください。

## MySQLインスタンスへの結果エクスポートの設定

Treasure Dataからのエクスポートはクエリを使用します。クエリを作成するか、既存のクエリを再利用します。クエリ内で、データ接続を設定します。

### 新しいクエリを使用する

1. TD Consoleを開きます。
2. Data Workbench > Queriesに移動します。
3. 右上隅の**New Query**を選択して、新しいクエリを作成します。


![](/assets/image-20191020-192019.0232885374130325d22392d0b4bfe64f91a33c43b49bdf70ce83060d1f45299b.db94e26c.png)

### 既存のクエリを使用する

データのエクスポートに使用する予定のクエリを選択します。

![](/assets/image-20191020-192033.1a80cf9f6102a7cf739abfa2a0c95a0dea12ab476055e8d4083d2edcf242266b.db94e26c.png)

## クエリ結果のエクスポート設定

クエリの設定が完了したら、**Export Results**を選択します。

![](/assets/image-20191020-192103.7e7c03acaa386e8b65a85daec52df752433beac913b2a2f7422753de3a8e49e4.db94e26c.png)

Choose Integrationダイアログが開きます。結果をエクスポートするために使用する接続を選択する際、2つのオプションがあります：既存の接続を使用するか、新しいMySQL接続を作成するかです。

### 既存の接続を使用する

検索ボックスに接続名を入力し、接続を選択します。

![](/assets/image-20191020-192117.37506e5691df7c6b8aa5458de241fbd2d745f52a8ef70e1304f2b27d5ec86af2.db94e26c.png)

### 新しいMySQL接続を作成する

フィールド値を入力して、新しい接続を作成します。

![](/assets/image-20191020-192136.9cc73a6228a35919cea004207f44963b544c0888bfe71946c0ac35b01877560e.db94e26c.png)

新しいMySQL接続に必要な認証情報を入力します。以下のパラメータを設定します：

- **Host**: IPアドレスなど、ソースデータベースのホスト情報
- **User**: ソースデータベースに接続するためのユーザー名
- **Password**: ソースデータベースに接続するためのパスワード
- **Use SSL**: SSLを使用して接続する場合は、このボックスをチェックします
  - **Require a valid SSL certificate?:** 接続時に有効なSSL証明書の提示を要求します


## 転送設定の構成

接続を設定した後、転送パラメータを設定します。

![](/assets/mysql-tables-export-integration-2024-07-18.b3200bd9989c35ccb7adfebbc1b02a3b5aa03582bfda7549ed3a88c55d55eb68.db94e26c.png)

![](/assets/mysql-tables-export-integration-2024-03-26-1.8720778daefb1d45c4bb95b34334bef5b148523455cfa4e53a85147585d4a809.db94e26c.png)

- **Database name**: データを転送するデータベースの名前（例：`your_database_name`）
- **Table**: データをエクスポートするテーブル
- **Table Charset**: ターゲットテーブルがサーバーのデフォルト文字セットと異なる文字セットを持つ場合に入力する必要があります。例：utf8mb4
- **Table Collation**: ターゲットテーブルがサーバーのデフォルト照合順序と異なる照合順序を持つ場合に入力する必要があります。例：utf8mb4_0900_ai_ci、utf8mb4_general_ci
- **Output mode**: データをアップロードするための異なる方法
  - **Append**（URLでmodeオプションが指定されていない場合に使用されるデフォルト）クエリ結果はテーブルに追加されます。テーブルが存在しない場合は、テーブルが作成されます。このモードはアトミックです。SQL文を使用します
    - `INSERT INTO target_table SELECT * FROM * temp_table;`
  - **Replace**: 既存のテーブルの全体の内容を、結果のクエリ出力で置き換えます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。replaceモードは、**単一のトランザクション**で以下の3つのステップを実行することにより、アトミック性（テーブルの消費者が常に一貫したデータを持つようにする）を実現します：
    1. 一時テーブルを作成します。
    2. 一時テーブルに書き込みます。
    3. ALTER TABLE RENAMEを使用して既存のテーブルを一時テーブルに置き換えます。
replaceモードを使用すると、MySQLテーブルのスキーマが変更される場合があります。ターゲットテーブルへのスキーマ変更を避けるには、「スキーマを保持する」オプションを選択してください。
    4. SQL文を使用します
      - target_tableが存在しない場合：RENAME temp_table --> target_table
      - target_tableが存在する場合：RENAME temp_table --> swap_table, target_table --> temp_table, swap_table --> target_table
  - **Truncate:** システムはまず既存のテーブルをトランケートし、Appendモードのようにクエリ結果を挿入します。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。このモードはアトミックです。
  - **Update:** 「unique」パラメータで指定された列に重複した値を引き起こさない限り、行が挿入されます：その場合は、代わりに更新が実行されます。「unique」パラメータは、updateモードを使用する場合にのみ適用されます。このモードはアトミックです。SQL文
    - uniqueパラメータなしまたはnull：REPLACE INTO target_table SELECT * FROM * temp_table;
    - uniqueパラメータあり：upsertを実行
      - UPDATE target_table, temp_table SET target_table.* = temp_table.* WHERE target_table.unique_keys = temp_table.unique_keys
      - INSERT INTO target_table SELECT * FROM temp_table WHERE NOT EXISTS (SELECT 1 FROM target_table TD WHERE target_table.unique_keys = temp_table.unique_keys)
- **Use compression**: サーバーへの接続では、接続を介して送信されるバイト数を減らすために、クライアントとサーバー間のトラフィックに圧縮を使用できます。
- **Use UTF-8 Encoding**: UTF-8形式のMySQL server configとの後方互換性。


## クエリの実行と結果の確認

「Output Results」チェックボックスをチェックした状態でクエリを実行します。クエリが正常に完了すると、転送の詳細を入力したときに指定したMySQLデータベースとテーブルに結果が表示されます。

## Audience Studioでセグメントをアクティベートする

Audience Studioでアクティベーションを作成することにより、ターゲットプラットフォームにセグメントデータを送信することもできます。

1. **Audience Studio**に移動します。
2. 親セグメントを選択します。
3. ターゲットセグメントを開き、右クリックして、**Create Activation**を選択します。
4. **Details**パネルで、アクティベーション名を入力し、Configuration Parametersに関する前のセクションに従ってアクティベーションを設定します。
5. **Output Mapping**パネルでアクティベーション出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - すべての列を変更せずにエクスポートするには、**Export All Columns**を選択します。
  - エクスポート用に特定の列を追加するには、**+ Add Columns**を選択します。Output Column Nameには、同じSourceカラム名が事前入力されます。Output Column Nameを更新できます。アクティベーション出力に新しい列を追加するには、**+ Add Columns**を引き続き選択します。
- String Builder
  - エクスポート用の文字列を作成するには、**+ Add string**を選択します。以下の値から選択します：
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時
    - Segment Id: セグメントID番号
    - Segment Name: セグメント名
    - Audience Id: 親セグメント番号


1. **Schedule**を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- スケジュールを定義する値を選択し、オプションでメール通知を含めます。


1. **Create**を選択します。


## 出力のためのスケジュールされたジョブのオプション使用

Result Outputを使用したスケジュールされたジョブは、指定されたMySQLインスタンスに出力結果を定期的に書き込みます。

## ワークフローでのエクスポート結果設定のオプション構成

Treasure Workflow内で、このデータコネクタを使用してデータを出力することを指定できます。


```yaml
timezone: UTC

_export:
  td:
    database: sample_datasets

+td-result-output-mysql:
  td>: queries/sample.sql
  result_connection: your_connections_name
  result_settings:
   database: database_name
   table: table_name
   mode: append
```

## 付録

#### MySQLサーバーを5.7から8にアップグレードする際のデフォルト照合順序

MySQL 5.7では、デフォルトの照合順序は`utf8mb4_general_ci`でした。しかし、MySQL 8では、デフォルトの文字セットは`utf8mb4`であり、デフォルトの照合順序は`utf8mb4_0900_ai_ci`です
MySQL output connectorは、サーバーのデフォルト照合順序（一時テーブルの作成に使用される）がターゲットテーブルの照合順序と異なる場合、`update`モード（`unique`設定を使用）で動作しない可能性があります（illegal mix of collationsエラー）
その場合、一時テーブルがターゲットテーブルと同じ文字セットと照合順序を持つことを確認するために、2つの設定（table_charsetとtable_collation）を使用する必要があります

（MySQLの「illegal mix of collations」エラーは、互換性のない照合順序を持つテキスト列を比較または結合しようとしたときに発生します（照合順序は文字セット内の文字を比較するためのルールのセットです）。