# Embulk Bulk Import From Tsv Files

オープンソースの一括データローダーである *Embulk* を使用して、TSVファイルからTreasure Dataにデータをインポートできます。

![](/assets/image-20191021-194448.33463c75cf3cb8b1a37595872537be60b30cee4f234d918acbc8fa2cb005f933.d2564ff8.png)

## 前提条件

- Treasure Dataの基本的な知識。
- [Embulk](http://www.embulk.org/docs/)の基本的な知識。
- [JRuby](https://www.jruby.org/download)がインストールおよび設定されている必要があります。Embulk v0.10.50およびv0.11.0にはJRubyが含まれていないため、手動でインストールおよび設定する必要があります。(EmbulkとJRubyの設定の詳細については、[Embulk v0.11 is coming soon](https://www.embulk.org/articles/2023/04/13/embulk-v0.11-is-coming-soon.md)の「JRuby」セクションを参照してください。)


## Embulkとは

Embulkを使用すると、さまざまなデータベース、ストレージの場所、ファイル形式、クラウドサービス間でデータを転送できます。

## Embulkのインストール方法

### Linux、MacおよびBSD

EmbulkはJavaアプリケーションです。Javaがインストールされていることを確認してください。

次の4つのコマンドで、Embulkをホームディレクトリにインストールします:


```bash
curl --create-dirs -o ~/.embulk/bin/embulk -L "http://dl.embulk.org/embulk-latest.jar"
chmod +x ~/.embulk/bin/embulk
echo 'export PATH="$HOME/.embulk/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### Windows

EmbulkはJavaアプリケーションです。Javaがインストールされていることを確認してください。

cmd.exeまたはPowerShell.exeで次のコマンドを使用して、`embulk.bat`をダウンロードできます:


```
PowerShell -Command \
  "& {Invoke-WebRequest http://dl.embulk.org/embulk-latest.jar -OutFile embulk.bat}"
```

## Treasure Data Pluginのインストール方法

pluginを使用して、さまざまなシステムやファイル形式からデータをロードできます。公開されているpluginのリストを表示するには、[カテゴリ別のpluginリスト](https://plugins.embulk.org/)を参照してください。

次のコマンドでembulk-output-td pluginをインストールします。このpluginは、レコードをTreasure Dataにインポートします。


```bash
embulk gem install embulk-output-td
```

# Seed設定ファイルの作成

お好みのテキストエディタを使用して、入力(file)および出力(TD)パラメータを定義するembulk設定ファイル(例:seed.yml)を作成します。例:


```yaml
in:
    type: file
    path_prefix: /path/to/files/sample_    # path of *.csv or *.tsv file on your local machine
out:
    type: td
    apikey: xxxxxxxxxxxx
    endpoint: api.treasuredata.com
    database: dbname
    table: tblname
    time_column: time
    mode: replace
    #by default mode: append is used, if not defined. Imported records are appended to the target table with this mode.
    #mode: replace, replaces existing target table
    default_timestamp_format: '%Y-%m-%d %H:%M:%S'
```

これはサンプルデータです。


```
id,account,time,purchase,comment
1,32864,2015-01-27 19:23:49,20150127,embulk
2,14824,2015-01-27 19:01:23,20150127,embulk jruby
3,27559,2015-01-28 02:20:02,20150128,"Embulk ""TSV"" parser plugin"
4,11270,2015-01-29 11:54:36,20150129,NULL
```

embulk-local-file-inputで使用可能な追加パラメータの詳細については、[Embulk Local file input](http://www.embulk.org/docs/built-in.md#local-file-input-plugin)を参照してください。また、embulk-output-tdの詳細については、[TD output plugin for Embulk](https://github.com/treasure-data/embulk-output-td#td-output-plugin-for-embulk)を参照してください。

## フィールドの推測(load.ymlの生成)

Embulkのguessオプションは、`seed.yml`を使用してターゲットファイルを読み取り、カラムタイプと設定を自動的に推測し、この情報を含む新しいファイル`load.yml`を作成します。


```bash
embulk guess seed.yml -o load.yml
```


```yaml
in:
  type: file
  path_prefix: /path/to/files/sample_
  'last_path:': /path/to/files/sample_02.tsv
  parser:
    charset: UTF-8
    newline: CRLF
    type: tsv
    delimiter: ','
    quote: '"'
    escape: '"'
    null_string: 'NULL'
    trim_if_not_quoted: false
    skip_header_lines: 1
    allow_extra_columns: false
    allow_optional_columns: false
    columns:
      - name: id
        type: long
      - name: account
        type: long
      - name: time
        type: timestamp
        format: '%Y-%m-%d %H:%M:%S'
      - name: purchase
        type: timestamp
        format: '%Y%m%d'
      - name: comment
        type: string
  out:
    type: td
    apikey: xxxxx
    endpoint: api.treasuredata.com
    database: dbname
    table: tblname
    time_column: time
    mode: replace
    default_timestamp_format: '%Y-%m-%d %H:%M:%S'
```

存在しないテーブルが自動的に作成されるように、load.yml に "auto_create_table: true" パラメータを追加してください。

.yml ファイル内の auto_create_table パラメータのサンプルです。


```yaml
out:
  type: td
  apikey: your apikey
  endpoint: api.treasuredata.com
  database: dbname
  table: tblname
  time_column: created_at
  auto_create_table: true
  mode: append
```

ロードジョブを実行する前に、TD でデータベースとテーブルを作成する必要があります。代替方法：1) データベースを追加する必要がある場合、または 2) .yml ファイルに auto_create_table パラメータを追加せずにテーブルを追加する必要がある場合は、以下の TD コマンドを実行してください。


```bash
td database:create dbname
td table:create dbname tblname
```

[TD Console](https://console.treasuredata.com/app/databases) を使用してデータベースとテーブルを作成することもできます。

`embulk preview load.yml` コマンドを使用してデータをプレビューできます。カラムの型やデータに問題がある場合は、`load.yml` ファイルを直接編集して再度プレビューして確認できます。`guess` オプションで満足のいく結果が得られない場合は、[CSV/TSV parser plugin options](http://www.embulk.org/docs/built-in.md#csv-parser-plugin) を使用して、要件に応じて `load.yml` のパラメータを手動で変更できます。


```
embulk preview load.yml
```

## ロードジョブの実行

最後に、以下のコマンドを実行してインポートジョブを発行します。


```
embulk run load.yml
```

データのサイズによっては、ジョブの完了に数分から数時間かかる場合があります。

## 付録

Bulk Import プログラム（td-import）を使用して TSV ファイルからデータをインポートすることもできます。ただし、td-import は積極的にメンテナンスされておらず、将来的に非推奨となる可能性があることに注意してください。そのため、Embulk の使用を強く推奨します。