本文へジャンプ

Embulk 出力プラグインガイド

Revision: 2.0.0-12154-62531f11

1 Embulk用GridDB出力プラグイン

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

1.1 概要

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

Embulk用GridDB出力プラグイン
Embulk用GridDB出力プラグインは入力プラグインがサポートするデータ形式を、読み込んで解析できます
  • プラグインのタイプ: 出力
  • レジューム実行: 不可 (処理失敗の場合、全データをクリーンし、再実行してください。)

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

1.2 検証環境

名前 バージョン
Embulk 0.9.x
Java Oracle JDK 8
Gradle Gradle 6.3
OS CentOS 7

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は対象外を意味します。

キー データタイプ 可能な値 デフォルト値 説明
type String griddb (必須) Embulk出力プラグイン名。Embulk用GridDB出力プラグイン"を意味する"griddb"を指定します。
mode_cluster String PROVIDER PROVIDER クラスタのモード。現在"PROVIDER"のみ対応。
provider_url String N/A (必須) PROVIDER方式で使用されるアドレズプロバイダのURL
cluster String N/A (必須) GridDBのクラスタの名前
database String public (必須) データを保存するGridDBデータベースの名前
container String N/A (必須) 対象コンテナの名前。テーブル名とも呼ばれます。
mode_insert Enumeration append, replace append - append: 存在するコンテナにデータを挿入します。
- replace: 存在する全データ (ドロップコンテナを除く)を削除後、新しいレコードを挿入します。
user String N/A (必須) GridDB管理者のユーザ名
password String N/A (必須) GridDB管理者のパスワード
batch_size Integer N/A 1000000 挿入時の単一バッチサイズ。データレコードのサイズがbatch_sizeを超える場合、データレコードはより小さなバッチに分割されます。GridDB出力プラグインは全データを一括挿入せずレコードをバッチ単位で挿入します。N_records/batch_size個に分割し、処理を分割単位ごとに実行します。
default_timezone String N/A UTC カラムタイプがTIMESTAMPでembulkタイプがstringの場合、カラム値はdefault_timezoneで設定した形式になります。各カラムのtimezonecolumn_optionsのオプションで上書きできます。
column_options Object N/A N/A ソースカラムのタイプと対象カラムのタイプのマップ
column_options/column_name String N/A N/A カラム名
column_options/column_name/
type
Enumeration string, long, double, float, boolean, timestamp (入力タイプと同一) カラムデータのタイプ
column_options/column_name/
timestamp_format
String N/A N/A 入力タイプがtimestampで出力タイプがstringの場合、このtimestamp_formatを使って文字列の値を形式化します。
timestamp形式の詳細は https://docs.oracle.com/javase/8/docs/api/index.html?java/text/SimpleDateFormat.html を参照。
column_options/column_name/
timezone
String N/A (default_timezoneと同一) 入力タイプがtimestampで出力タイプがstringの場合、timezoneはタイムスタンプの値の後ろにアペンド(付加)されます。
column_options/column_name/
time_precision
String MILLISECOND, MICROSECOND, NANOSECOND MILLISECOND MILLISECOND, MICROSECOND, NANOSECONDはそれぞれGridDBのデータ型のtimestamp, timestamp(6), timestamp(9)に変換されます。

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
    
  1. 作業ディレクトリを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_urlclusterの値は適切な値に変更してください。

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

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

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

id name price deleted join_date end_date
1 Café 10000.0 false 2020-07-14T00:00:00.000000+07:00 2015-07-12T15:00:00.000000UTC
2 北京烤鸭 3.14159265358979 true 2020-07-14T00:00:00.000000+07:00 2015-07-12T15:00:00.000000UTC
3 サーモン 0.66666666666666 false 2020-07-14T00:00:00.000000+07:00 2015-07-12T15:00:00.000000UTC

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

Column Input Type Output Type
id string long
name string string
price string double
deleted string boolean
join_date string timestamp(6)
end_date timestamp string

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

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

今度はconfig.yamlbatch_size1に変更します。コマンドを再実行後、端末で出力を見ると、データが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モードでは存在するコンテナに追加のデータを挿入するためです。

id name price deleted join_date end_date
1 Café 10000.0 false 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC
2 北京烤鸭 3.14159265358979 true 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC
3 サーモン 0.66666666666666 false 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC
1 Café 10000.0 false 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC
2 北京烤鸭 3.14159265358979 true 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC
3 サーモン 0.66666666666666 false 2020-07-14T02:00:00.000+09:00 2015-07-12T15:00:00.000000UTC

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