Embulk 出力プラグインガイド

Revision: 2.0.0-12154-62531f11

1 Embulk用GridDB出力プラグイン

Embulk 用GridDB出力プラグインはデータレコードをGridDBのデータベースにロードします。

1.1 概要

Embulk用GridDB出力プラグインは他のデータベース（またはデータファイル）のデータをGridDBのデータベースに転送します。

• プラグインのタイプ: 出力
• レジューム実行: 不可 (処理失敗の場合、全データをクリーンし、再実行してください。)

注: Embulkの使用方法の詳細は https://github.com/embulk/embulk を参照。

1.2 検証環境

1.3 構成

1.3.1 構成ファイル

Embulk用GridDB出力プラグインは構成ファイル(config.yaml)により構成できます。このファイルは YAML形式で書き込まれます。この構成ファイルのサンプルを下記に示します。ここでは "out:"の部分がGridDB出力プラグインに対応します。

in:
    type: file
    path_prefix: sample_file.csv
    parser:
        type: csv
        columns:
          - {name: column1, type: long }
          - {name: column2, type: string }
          - {name: column3, type: double }

out:
    type: griddb
    mode_cluster: PROVIDER
    provider_url: http://example.com/my_cluster.json
    cluster: myCluster
    database: myDB
    container: myContainer
    user: admin
    password: admin
    mode_insert: replace
    column_options:
        column1: { type: long    }
        column2: { type: string  }
        column3: { type: double  }

注: 上記サンプルの"in:の部分が Embulk入力プラグインに対応します。Embulkの構成の詳細は https://www.embulk.org/docs/built-in.html を参照。

下記の表にGridDB出力プラグインの全オプション(上記の"out:"の部分のオプション) を示します。N/Aは対象外を意味します。

1.3.2 環境の準備

1. Embulkを https://github.com/embulk/embulk/releases/ からダウンロードします。

   embulk.jarファイルに実行権限を付与します。

   $ chmod +x ./embulk.jar
   

2. JDK 1.8.0 (開発版)をインストールします。

• RHEL系 (RedHat, Centos, Fedora等):

  # yum install java-1.8.0-openjdk-devel
  

• Debian系 (Debian, Ubuntu, Linux Mint等):

  # apt-get install openjdk-8-jdk
  

3. 作業ディレクトリをembulk-output-griddbディレクトリに変更します。次のコマンドを実行します。

   $ gradle package
   

注: 必要に応じてステップ3の前にgradle.propertiesにプロキシサーバの設定を行って下さい。

以上でプラグインは利用可能になります。

1.4 例

以下のファイルとディレクトリを準備します:

test
├── product.csv
├── config.yaml
└── embulk-output-griddb

• product.csv

"id","name","price","deleted","join_date","end_date"
"1","Café","10000.000000000000001","false","2020-07-14 00:00:00.000 +07:00","2015-07-12 15:00:00"
"2","北京烤鸭","3.14159265358979","true","2020-07-14 00:00:00.000 +07:00","2015-07-12 15:00:00"
"3","サーモン" ,"0.66666666666666","false","2020-07-14 00:00:00.000 +07:00","2015-07-12 15:00:00"

• config.yaml

in:
    type: file
    path_prefix: product.csv
    parser:
        charset: UTF-8
        newline: LF
        type: csv
        delimiter: ','
        quote: '"'
        trim_if_not_quoted: false
        skip_header_lines: 1
        allow_extra_columns: false
        allow_optional_columns: false
        columns:
          - {name: id,       type: string }
          - {name: name,     type: string }
          - {name: price,    type: string }
          - {name: deleted,  type: string }
          - {name: join_date, type: string }
          - {name: end_date,      type: timestamp, format: "%Y-%m-%d %H:%M:%S.%N" }

out:
    type: griddb
    mode_cluster: PROVIDER
    provider_url: http://example.com/api/griddb/mycluster.json
    cluster: mycluster
    database: public
    container: product
    user: admin
    password: admin
    mode_insert: replace
    batch_size: 1
    column_options:
        id:         { type: long      }
        name:       { type: string    }
        price:      { type: double    }
        deleted:    { type: boolean   }
        join_date:  { type: timestamp }
        end_date:   { type: string, timestamp_format: yyyy-MM-dd HH:mm:ss.SSSSSSXXX, timezone: UTC, time_precision: MICROSECOND }

注: 上記のprovider_urlとclusterの値は適切な値に変更してください。

プラグインを起動します:

$ ./embulk.jar run -L ./embulk-output-griddb/ config.yaml

publicデータベース内の結果を見るとproductという名前のコンテナが作成されたことが分かります。

この例では各カラム(Column)の入力タイプ(Input Type)と出力タイプ(Output Type)が次のように定義されています。

idカラム、nameカラム、priceカラム、deletedカラムおよびjoin_dateカラムは入力タイプと出力タイプはそろえるのがよいが、そろっていなくてもembulk-output-griddbコマンドは出力先情報をもとに、適切なデータタイプに変換できます。 end_dateカラムは入力タイプがtimestampで出力タイプがstringの場合にカスタム形式でタイプスタンプを表示するためのカラムです。column_options はtimestamp_formatをyyyy-MM-dd HH:mm:ss.SSSSSSXXXに、 timezoneをUTCにそれぞれ設定しているため、end_dateカラムは結果として2015-07-12T15:00:00.000000UTCとなります。

注意: タイムスタンプの表記はRFC3339の仕様に従う必要があります。従わない場合は、出力データは入力データのタイムスタンプ形式に応じて変換されます。

今度はconfig.yamlのbatch_sizeを1に変更します。コマンドを再実行後、端末で出力を見ると、データが3バッチに分割されていることが分かります。

[INFO] (0015:task-0000): put rows:0-1
[INFO] (0015:task-0000): convert STRING:Café
[INFO] (0015:task-0000): convert TIMESTAMP:2020-07-14 00:00:00.000
[INFO] (0015:task-0000): convert STRING:2015-07-12 15:00:00
[INFO] (0015:task-0000): put rows success:1-1
[INFO] (0015:task-0000): put rows:1-2
[INFO] (0015:task-0000): convert STRING:北京烤鸭
[INFO] (0015:task-0000): convert TIMESTAMP:2020-07-14 00:00:00.000
[INFO] (0015:task-0000): convert STRING:2015-07-12 15:00:00
[INFO] (0015:task-0000): put rows success:2-2
[INFO] (0015:task-0000): put rows:2-3
[INFO] (0015:task-0000): convert STRING:サーモン
[INFO] (0015:task-0000): convert TIMESTAMP:2020-07-14 00:00:00.000
[INFO] (0015:task-0000): convert STRING:2015-07-12 15:00:00
[INFO] (0015:task-0000): put rows success:3-3
[INFO] (0015:task-0000): Finish page: 3

次にmode_insertを"append"に変更し、コマンドを再実行します。 データベース内の結果を見るとproductコンテナには3つではなく6つのレコードがあることが分かります。これはappendモードでは存在するコンテナに追加のデータを挿入するためです。

2 参考文献

1. Embulk on GitHub - https://github.com/embulk/embulk
2. Embulkホームページ - https://www.embulk.org/
3. Embulkドキュメンテーション - https://www.embulk.org/docs/built-in.html#csv-parser-plugin