# Mixpanel Import Integration

Mixpanel用データコネクタを使用すると、MixpanelのイベントデータをTreasure Dataにバックアップできます。ユースケースには以下が含まれます：

| **ユースケース** | **説明** |
|  --- | --- |
| 一回限りの移行 | 組織がMixpanelから移行し、データの生コピーを保持したい場合 |
| 増分型の日次バックアップ | 組織がMixpanel内のイベントデータにSQLでよりきめ細かいアクセスを必要とする場合 |


Mixpanelからイベントデータをインポートする方法のサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td_load/mixpanel)を参照してください。

## TD Consoleを使用する

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

1. Integrations Hub > Catalogに移動します
2. Mixpanelを検索して選択します。
3. 以下のダイアログが開きます。Mixpanelの認証情報の詳細を編集します。
4. **Continue**を選択し、この接続の名前を指定します。


![](/assets/image-20200331-191757.62ae4934c2d416ee52ac82c22d39f0c09cd44e57f2928e0c14050423ccb5d3cc.6d61b60d.png)

### 新しいソースを作成する

接続を作成すると、自動的にAuthenticationsページに移動します。作成した接続を探して、**New Source**を選択します。

![](/assets/image-20200331-191831.26c095e5bbdc4e186d5fa3ccfc1a83d8bbc25bb940fc52d25101bcf1fbcc4a60.6d61b60d.png)

#### **Connection**

以下のダイアログが開きます。

1. データ転送に名前を付けて、**Next**を選択します。


![](/assets/image-20200331-191847.490cea31436f6abfee2dbbf9ba1cc8877628c2017c0e39fedf50e839bc192311.6d61b60d.png)

#### Source Table

以下のダイアログが開きます。

1. ソースパラメータを編集して、**Next**を選択します。


![](/assets/image-20200331-205825.b6c7b1431dcb1fe90a3ca2a28e9507ccef368b7d4f718f2404ab4610b9f39289.6d61b60d.png)

![](/assets/image-20200331-191941.156b803358278dab82a2798475a19f9d207c16048e0db26d98c769ce663c861f.6d61b60d.png)

| **パラメータ** | **説明** |
|  --- | --- |
| **Data Export API Endpoint:** | Export API呼び出しに使用するエンドポイント。空のままにすると、デフォルト値は[https://data.mixpanel.com/api/2.0/export/](https://data.mixpanel.com/api/2.0/export/)です |
| **JQL API Endpoint** | JQL API呼び出しに使用するエンドポイント。空のままにすると、デフォルト値は[https://mixpanel.com/api/2.0/jql/](https://mixpanel.com/api/2.0/jql/)です |
| **Timezone** | プロジェクトのタイムゾーン。PROJECT SETTINGS >> YOUR PROJECT >> OVERVIEWで確認できます。 |
| **JQL Mode** | JQLエンドポイントを使用するか、単にexportエンドポイントを使用するか。デフォルト値はfalseです |
| **JQL** | JQLスクリプト。JQL Modeがtrueの場合のみ有効です |
| **Incremental Loading** | 転送を増分モードで実行するかどうか |
| **Incremental Field** | 増分のインデックスとして使用されるフィールド。デフォルト値は`time`です |
| **From date** | 増分の開始日 |
| **Number of Days to Fetch** | 一度にデータを取得する日数の合計 |
| **Number of Days to Slice** | 1つのリクエストで取得する日数 |


### Data Settings

このページでデータ設定を編集できます。

1. データ設定を編集するか、オプションでこのダイアログページをスキップします。


![](/assets/image-20200331-205910.f234277625ea61950315dda899a5b3add865c944ac5d12c3f5c22882471a0288.6d61b60d.png)

![](/assets/image-20200331-205934.3f7e6cd4df143e81f63184b21ad59f4393eba4b89cdf45399886ab5adf3a1706.6d61b60d.png)

| **パラメータ** | **説明** |
|  --- | --- |
| **Backfill Days** | APIリクエストで使用される最終的な`from_date`を計算するために`from_date`から減算される時間。これは、Mixpanelがユーザーデバイス上でデータをキャッシュしてからMixpanelサーバーに送信するためです。Incrementalがtrueで、Incremental Fieldが指定されている場合のみ影響します。デフォルト値は5です |
| **Incremental Column Upper Limit Delay In Seconds** | 増分カラムの上限。増分カラムでexportを使用する場合、プラグインは増分カラムクエリの上限をジョブ開始時刻でロックします。これは、Mixpanelの処理に遅延がある場合をサポートするためです。Exportエンドポイントのみに影響します。デフォルト値は0です。 |
| **Allow Partial Import** | プラグインがインポート時のエラーをスキップできるようにします。Exportエンドポイントのみに影響します。デフォルト値はtrueです。 |
| **Fetch Custom Properties** | Exportエンドポイント専用のすべてのカスタムプロパティをプラグインがインポートできるようにします。デフォルト値はfalseです。 |
| **Events** | Exportエンドポイント専用のデータをフィルタリングするためのイベント |
| **Filter Expression** | Exportエンドポイント専用のセグメンテーション式 |
| **Bucket** | Exportエンドポイント専用のデータをフィルタリングするためのデータバケット |
| **Schema** | TDテーブルに格納されるカラム名と型を含むスキーマ。 |


### Data Preview

インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data)を表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. **Next** を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、**Generate Preview** を選択します。
3. データを確認します。


### Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. **Next** を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。
2. **Database** を選択 > **Select an existing** または **Create New Database** を選択します。
3. オプションで、database 名を入力します。
4. **Table** を選択 > **Select an existing** または **Create New Table** を選択します。
5. オプションで、table 名を入力します。
6. データをインポートする方法を選択します。
  - **Append** (デフォルト) - データインポートの結果は table に追加されます。
table が存在しない場合は作成されます。
  - **Always Replace** - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
  - **Replace on New Data** - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。
7. **Timestamp-based Partition Key** 列を選択します。
デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。
8. データストレージの **Timezone** を選択します。
9. **Schedule** の下で、このクエリを実行するタイミングと頻度を選択できます。


#### 一度だけ実行

1. **Off** を選択します。
2. **Scheduling Timezone** を選択します。
3. **Create & Run Now** を選択します。


#### 定期的に繰り返す

1. **On** を選択します。
2. **Schedule** を選択します。UI では、*@hourly*、*@daily*、*@monthly*、またはカスタム *cron* の 4 つのオプションが提供されます。
3. **Delay Transfer** を選択して、実行時間の遅延を追加することもできます。
4. **Scheduling Timezone** を選択します。
5. **Create & Run Now** を選択します。


転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。

## コマンドラインを使用する

### 'td' Command v0.11.9以降をインストールする

最新の[Treasure Data Toolbelt](https://support.treasuredata.com/hc/en-us/articles/360000720048-Treasure-Data-Toolbelt-Command-line-Interface)をインストールします。

### Mixpanel API認証情報を確認する

Mixpanelアカウントにログインし、「Account」、次に「Projects」に移動して、APIキーとAPIシークレットを確認します。

### シード設定ファイル（seed.yml）を作成する

次のように`seed.yml`というファイルを作成します。


```yaml
in:
  type: mixpanel
  api_key: MIXPANEL_API_KEY
  api_secret: MIXPANEL_API_SECRET
  timezone: 'UTC'
  from_date: "2015-10-28"
  fetch_days: 1
out:
  mode: append
```

このシードファイルは、カラム名を含む完全な設定ファイルを「推測」するために使用されます。この例では、2015年10月28日の1日分のデータがMixpanelからTreasure Dataにエクスポートされます。

利用可能な`out`モードの詳細については、以下の付録を参照してください。

### フィールドを推測する（load.ymlを生成する）

`seed.yml`に基づいて、`connector:guess`コマンドで`load.yml`を生成します。


```
$ td connector:guess seed.yml -o load.yml
```

カラム名とタイプは、Mixpanelの設定方法によって異なります。`load.yml`ファイルは次のようになります：


```yaml
in:
  type: mixpanel
  api_key: MIXPANEL_API_KEY
  api_secret: MIXPANEL_API_SECRET
  timezone: UTC
  from_date: '2015-10-28'
  fetch_days: 1
  columns:
  - name: event
    type: string
  - name: "$browser"
    type: string
  - name: "$browser_version"
    type: long
  - name: "$city"
    type: string
  - name: "$current_url"
    type: string
  - name: "$initial_referrer"
    type: string
  - name: "$initial_referring_domain"
    type: string
  - name: "$lib_version"
    type: string
  - name: "$os"
    type: string
  - name: "$referrer"
    type: string
  - name: "$referring_domain"
    type: string
  - name: "$region"
    type: string
  - name: "$screen_height"
    type: long
  - name: "$screen_width"
    type: long
  - name: ENV
    type: string
  - name: RAILS_ENV
    type: string
  - name: distinct_id
    type: long
  - name: from
    type: string
  - name: job_id
    type: long
  - name: mp_country_code
    type: string
  - name: mp_lib
    type: string
  - name: name
    type: string
  - name: time
    type: long
filters:
- type: rename
  rules:
  - rule: upper_to_lower
  - rule: character_types
    pass_types: ["a-z", "0-9"]
    pass_characters: "_"
    replace: "_"
  - rule: first_character_types
    pass_types: ["a-z"]
    pass_characters: "_"
    prefix: "_"
  - rule: unique_number_suffix
    max_length: 128
out:
  mode: append
exec: {}
```

`rename`フィルタの詳細については、[Data Connectorのrenameフィルタプラグイン](https://docs.treasuredata.com/smart/project-product-documentation/rename-filter-function)を参照してください。

Data Connectorは次のようなフィールドを検出しました：

- ENV
- RAILS_ENV
- $current_url


カラム名は、type: renameフィルタセクションで正規化されます。

### データ読み込みのプレビュー

`connector:preview`コマンドを使用して、データ読み込みをプレビューします。


```bash
td connector:preview load.yml
```

データが問題なければ、Mixpanelデータをインポートする先のデータベースとテーブルをTreasure Data上に作成します：


```bash
td db:create mixpanel_historical
td table:create mixpanel_historical app_name
```

### データの読み込み

読み込みジョブを送信します。データのサイズによっては数時間かかる場合があります。ユーザーは、データが保存されるデータベースとテーブルを指定する必要があります。

Treasure Dataのストレージは時間でパーティション分割されているため（[アーキテクチャ](https://support.treasuredata.com/hc/en-us/articles/360001480667)を参照）、`--time-column`オプションを指定することを推奨します。このオプションが指定されていない場合、Data Connectorは最初の`long`または`timestamp`カラムをパーティショニング時間として選択します。`--time-column`で指定するカラムのタイプは、`long`または`timestamp`タイプである必要があります。


```bash
td connector:issue load.yml --database mixpanel_historical --table app_name --time-column time
```

上記のコマンドは、*database(td_sample_db)*と*table(td_sample_table)*がすでに作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは失敗するため、データベースとテーブルを[手動で](https://docs.treasuredata.com/articles/product-documentation-publication/data-management)作成するか、`td connector:issue`コマンドで`--auto-create-table`オプションを使用してデータベースとテーブルを自動作成してください：


```
$ td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column created_at --auto-create-table
```


```

"--time-column" オプションで、Time Format列を「パーティショニングキー」に割り当てることができます。

Treasure Data内のデータに対してSQLクエリを直接実行することで、データが読み込まれたことを確認できます:

```bash
td query -T presto -w -d mixpanel_historical 'SELECT COUNT(1) FROM app_name'
```

### 増分データ読み込みのスケジューリング

Mixpanelから完全に移行するのでない限り、Mixpanelデータは定期的にTreasure Dataへ増分読み込みする必要があります。Data Connectorのスケジューリング機能がこの目的に便利です。

スケジューリング後、Mixpanel Data Connectorは実行の度に `from_date` パラメータを `fetch_days` だけ増加させます。例えば、`load.yml` での初回実行が


```
from_date: '2015-10-28'
fetch_days: 1
```

であった場合、次回の実行は以下のようになります:


```
from_data: '2015-10-29'
fetch_days: 1
```

アップロード後に `load.yml` を更新する必要は**ありません**。`from_date` フィールドはサーバー側で自動的に更新されるためです。

毎日アップロードをスケジュールしたいとします。その場合、初回の `from_date` は少なくとも2日前に設定し、`load.yml` で `fetch_days: 1` を設定してください。次のコマンドで「daily_mixpanel_import」という毎日のジョブが作成され、Treasure Data上の `mixpanel_historical.app_name` に履歴データを毎日読み込みます。


```
$ td connector:create \
    daily_mixpanel_import \
    "10 0 * * *" \
    mixpanel_historical \
    app_name \
    load.yml \
    --time-column time # オプション
```

インポートの履歴実行は `td connector:history name` で確認できます。例: `td connector:history daily_mixpanel_import`

### 増分カラムを使用した増分データ読み込み

一部のMixpanelアカウントでは、Mixpanelがデータを処理した時刻を示す追加フィールドを持つプロジェクトが設定されています。例: `mp_processing_time_ms`

Mixpanel Input Pluginに追加パラメータ `incremental_column` を追加できます。実行セッションの最大 `incremental_column` 値が保存され、次回実行時のフィルタとして使用されます。例: `where incremental_column > previous_run_max_value`

例:


```
in:
  type: mixpanel
  api_key: MIXPANEL_API_KEY
  api_secret: MIXPANEL_API_SECRET
  timezone: 'UTC'
  from_date: "2015-10-28"
  incremental_column: mp_processing_time_ms
  fetch_days: 1
out:
  mode: append
```

#### ***back_fill_days*** でデータをさかのぼる

スマートフォンやタブレットなどのデバイスデータの場合、MixpanelはMixpanel Serverに送信する前にユーザーのデバイス内にデータを一時保持することがあります。そのため、クエリに表示されるデータは最大5日遅れることがあります。Mixpanelから増分インポートする際、ユーザーデバイスにキャッシュされているデータを見逃す可能性があります。この問題を解決するには、`back_fill_days` パラメータ(デフォルトは5)を設定します。プラグインは指定された日数分さかのぼります(`from_date - back_fill_days`)。パフォーマンス上の問題により、この機能は incremental_column と一緒にのみ動作します。

#### ***slice_range*** で範囲クエリをより小さなAPIクエリに分割

場合によっては、返されるデータが大きすぎて、1回のクエリで返されるデータがMixpanelの制限を超え、ジョブが失敗する可能性があります。その場合、`slice_range` 設定パラメータを使用して、大きな範囲クエリを小さなものに分割できます。このパラメータはオプションで、デフォルトは***7***です。

例:


```yaml
in:
  type: mixpanel
  api_key: MIXPANEL_API_KEY
  api_secret: MIXPANEL_API_SECRET
  timezone: 'UTC'
  from_date: "2015-10-20"
  incremental_column: mp_processing_time_ms
  fetch_days: 6
  slice_range: 2
out:
  mode: append
```

上記の設定により、[2015-10-20,2015-10-25] の代わりに、次の範囲のクエリが生成されます: `[2015-10-20,2015-10-21],[2015-10-22,2015-10-23],[2015-10-24,2015-10-25]`

## 付録

### Out Pluginのモード

seed.ymlの `out` セクションでファイルインポートモードを指定できます。

- append (デフォルト)


これはデフォルトのモードで、レコードはターゲットテーブルに追加されます。


```
in:
  ...
out:
  mode: append
```

- replace (td 0.11.10以降)


このモードは、ターゲットテーブル内のデータを置き換えます。ターゲットテーブルに対して手動で行われたスキーマ変更は、このモードでもそのまま保持されます。


```
in:
  ...
out:
  mode: replace
```