エクスポート/インポートツール

GridDBの エクスポート/インポート ツールでは、データベースの局所的な破壊に対して復旧を行う障害回復処理や、システム構成が変更された際のデータベースの移行(マイグレーション)処理などを実現するために、データベースやコンテナ単位での保存/復元機能を提供します。

出力データを取り扱いやすくするため、エクスポートツールはコンテナの種別に応じてロウデータファイルの出力形式を切り替えます。エクスポートコンテナ種別には以下の２種類があります。

データが順次蓄積され規模が増大する傾向があるコンテナを日付蓄積型コンテナ と呼びます。この種別の場合、日付単位でロウデータファイルを出力します。
上記以外のコンテナを登録更新型コンテナ と呼びます。この種別の場合、コンテナ単位でロウデータファイルを出力します。

具体的にはそれぞれに含まれるコンテナは以下になります。

コンテナ	テーブルパーティショニング	パーティショニングの種類	パーティショニングキー	エクスポートコンテナ種別
コレクション	あり	ハッシュパーティショニング	Timestamp型 Timestamp型以外	登録更新型コンテナ
コレクション	あり	インターバルパーティショニング	Timestamp型 Timestamp型以外	日付蓄積型コンテナ登録更新型コンテナ
コレクション	あり	インターバルハッシュパーティショニング	Timestamp型 Timestamp型以外	日付蓄積型コンテナ登録更新型コンテナ
コレクション	なし	－	Timestamp型 Timestamp型以外	登録更新型コンテナ
時系列コンテナ	あり	ハッシュパーティショニング	Timestamp型 Timestamp型以外	登録更新型コンテナ
時系列コンテナ	あり	インターバルパーティショニング	Timestamp型 Timestamp型以外	日付蓄積型コンテナ登録更新型コンテナ
時系列コンテナ	あり	インターバルハッシュパーティショニング	Timestamp型 Timestamp型以外	日付蓄積型コンテナ登録更新型コンテナ
時系列コンテナ	なし	－	－	日付蓄積型コンテナ

ファイル構成

エクスポートツールは、GridDBクラスタのコンテナおよびロウデータを、以下のファイルに保存します。コンテナ名を指定して特定コンテナのみエクスポートすることもできます。

コンテナデータファイル
- GridDBのコンテナ情報とロウデータを保存します。
- コンテナ単位に保存する形式と複数コンテナをまとめて保存する形式の２種類があります。
エクスポート実行情報ファイル
- エクスポート実行時の情報を保存します。エクスポートしたデータを、そのままGridDBクラスタに復元するために必要です。

インポートツールは、エクスポートデータを保存したコンテナデータファイルとエクスポート実行情報ファイルを読み込んで、コンテナおよびロウデータをGridDBに復元します。特定のコンテナデータを指定して、インポートすることもできます。

コンテナデータファイルとは

コンテナデータファイルは、コンテナ情報を記載した メタデータファイル と、コンテナに格納するデータを記載した ロウデータファイル からなります。

メタデータファイルは、コンテナのタイプや、スキーマ、設定されている索引情報を含むjson形式のファイルです。

ロウデータファイルには、コンテナの格納データをCSV形式で記載する CSVデータファイル と、zip形式で記載する バイナリデータファイル の2種類があります。

CSVデータファイル:
- コンテナのロウデータをCSVデータとして記載します。可読性が高く、汎用ツールでファイルを読み込んで編集することが可能です。
- ロウデータがBLOBや空間情報、配列などの特定の型の場合には、外部オブジェクトファイルにデータを記載し、CSVデータファイルには外部オブジェクトファイル名のみ記載します。外部オブジェクトファイルは、ロウデータ毎に作成します。
バイナリデータファイル：
- コンテナのロウデータをZip形式で記載します。gs_exportでのみ作成が可能です。 CSVデータファイルに比べてサイズが小さくなります。また外部オブジェクトファイルを作成する必要がないため、ファイル数が少なくて済みます。ただし、バイナリデータファイルには可読性はなく編集することはできません。

各ファイルの記述内容の詳細は、コンテナデータファイルの形式を参照してください。

登録更新型コンテナ の場合、コンテナ単位でロウデータファイルを出力します。コンテナデータファイルには、記載対象となるコンテナ数によって、以下の２種類があります。

シングルコンテナ構成：１つのコンテナに対して１つのコンテナデータファイルを持つ
マルチコンテナ構成：複数のコンテナを１つのコンテナデータファイルにまとめる

日付蓄積型コンテナ の場合、日付単位でロウデータファイルを出力します。

日付コンテナ構成：１コンテナのデータを１日毎に分割し、それぞれに１つのコンテナデータファイルを持つ。

エクスポートコンテナ種別	出力ファイル構成	説明
登録更新型コンテナ	シングルコンテナ構成	１コンテナ毎に１つのコンテナデータファイルを作成する構成
	マルチコンテナ構成	複数コンテナを１つのコンテナデータファイルにまとめた構成
日付蓄積型コンテナ	日付コンテナ構成	１コンテナのデータを１日毎に分割して１つのコンテナデータファイルを作成

以降では、各構成のコンテナデータファイルを シングルコンテナデータファイル 、 マルチコンテナデータファイル、日付コンテナデータファイル とそれぞれ記載します。

登録更新型コンテナの場合、シングルコンテナデータファイルで大量のコンテナを指定してエクスポートを実行すると、大量のメタデータファイルとロウデータファイルが作成されるため、管理が煩雑となります。一方、マルチコンテナデータファイルでは、大量のコンテナを指定しても出力されるのは１つのメタデータファイルとロウデータファイルのみです。

そこで、２つの構成は 用途に応じて使い分ける ことを推奨します。

シングルコンテナデータファイルは、以下のようなケースで利用します。

特定コンテナの現在のデータを出力し、データ解析したい。
既存のコンテナと同様のスキーマのコンテナを多数作成し、データを登録したい。

マルチコンテナデータファイルは、以下のようなケースで利用します。

特定コンテナ群のバックアップを採取したい。
異なるGridDBクラスタへデータベースを移行したい。

日付蓄積型コンテナの場合、出力ファイル構成は１種類のため、このような使い分けはありません。

エクスポート実行情報ファイルとは

エクスポート実行情報ファイルには、エクスポート実行時の日時、コンテナ数、コンテナ名などの情報を保存します。このファイルはエクスポートしたデータを、そのままGridDBクラスタに復元するために必要です。

【メモ】

エクスポート実行情報ファイルのファイル名は、gs_export.jsonです。
エクスポートしたコンテナデータファイルを手動で編集した場合、エクスポート実行情報は削除してください。情報の不一致により、登録エラーが発生する可能性があります。
エクスポート実行情報ファイルが存在しない場合のインポートでは、コンテナのメタデータファイルの指定が必須です。指定しない場合、インポートは失敗します。

エクスポート／インポートの実行環境の設定

エクスポート／インポートコマンドを実行するには、以下の設定が必要です。

プロパティファイルの設定

gsadmユーザで利用するGridDBクラスタ構成にあわせてプロパティファイルを設定します。プロパティファイルは、 /var/lib/gridstore/expimp/conf/gs_expimp.properties です。

プロパティファイルには以下のような設定項目があります。

パラメータ	必須	デフォルト値	説明
mode	必須	MULTICAST	接続方式の種類を指定します。指定を省略した場合はマルチキャスト方式になります。 MULTICAST ・・マルチキャスト方式 FIXED_LIST・・固定リスト方式 PROVIDER ・・プロバイダ方式
hostAddress	mode=MULTICASTの場合は必須	239.0.0.1	GridDBのクラスタ定義ファイル(gs_cluster.json)の/transaction/notificationAddressを指定します。エクスポート・インポートツールがクラスタにアクセスする際に利用するマルチキャストアドレスです。
hostPort	mode=MULTICASTの場合は必須	31999	GridDBのクラスタ定義ファイル(gs_cluster.json)の/transaction/notificationPortを指定します。エクスポート・インポートツールがクラスタにアクセスする際に利用するマルチキャストアドレスのポートです。
jdbcAddress	mode=MULTICASTの場合は必須	239.0.0.1	マルチキャスト方式を利用する場合は、GridDBのクラスタ定義ファイル(gs_cluster.json)の/sql/notificationAddressを指定します。
jdbcPort	mode=MULTICASTの場合は必須	41999	マルチキャスト方式を利用する場合は、GridDBのクラスタ定義ファイル(gs_cluster.json)の/sql/notificationPortを指定します。
notificationMember	mode=FIXED_LISTの場合は必須	－	固定リスト方式の接続方法を使用する場合は、各ノードのクラスタ定義ファイルgs_cluster.jsonに指定した/cluster/notificationMemberの/transaction/addressと/transaction/portを:で繋いで記述します。複数ノードの場合は、カンマで連結してください。例）192.168.0.100:10001,192.168.0.101:10001
jdbcNotificationMember	mode=FIXED_LISTの場合は必須	－	固定リスト方式の接続方法を使用する場合は、クラスタ定義ファイルgs_cluster.jsonの/cluster/notificationMemberの各ノードの/sql/addressと/sql/portを:で繋いで記述します。複数ノードの場合は、カンマで連結してください。例）192.168.0.100:20001,192.168.0.101:20001
notificationProvider.url	mode=PROVIDERの場合は必須	－	プロバイダ方式の接続方法を使用する場合は、クラスタ定義ファイルgs_cluster.jsonの/cluster/notificationProvider/urlを指定します。
restAddress	－	127.0.0.1	GridDBのノード定義ファイル(gs_node.json)の/system/listenerAddressを指定します。将来の拡張用のパラメータです。
restPort	－	10040	GridDBのノード定義ファイル(gs_node.json)の/system/listenerPortを指定します。将来の拡張用のパラメータです。
clusterName	必須	INPUT_YOUR_CLUSTER_NAME_HERE	クラスタ構成を組む(gs_joinclusterコマンドで指定）際に指定しているクラスタ名を指定します。
logPath	－	/var/lib/gridstore/log	エクスポート・インポートツールの実行時のエラー情報などのログを出力するディレクトリを指定します。ディレクトリ下に、gs_expimp-YYYYMMDD.log でログが出力されます。
commitCount	－	1000	インポートでコンテナデータを登録する際にデータを登録する単位として、ロウ件数を指定します。数値を大きくするとデータ処理のためのバッファが大きくなります。ロウサイズが小さい場合は数値を上げ、ロウサイズが大きい場合は数値を下げてください。データインポートの登録性能に影響するパラメータです。
transactionTimeout	－	2147483647	トランザクション開始から終了までの時間を指定します。大量データの登録・取得時には、データ量に合わせた大きな数値を設定する必要があります。デフォルトは、大量データ処理用に最大値が指定されています。(単位：秒)
failoverTimeout	－	10	ツールがノード障害を検知してからリトライを繰り返すフェイルオーバー時間を指定します。インポート/エクスポートの対象クラスタへの初期接続のタイムアウトにも用いられます。コンテナへの大量データ登録・取得などの処理を行う場合は、値を増やしてください。(単位：秒)
jdbcLoginTimeout	－	10	JDBCの初期接続のタイムアウト時間です。(単位：秒)
notificationInterfaceAddress	－	※OSに依存	複数のネットワークインターフェースがあるときにクラスタのネットワーク構成をマルチキャスト方式にする場合、マルチキャストパケットを受信するインターフェースのIPアドレスを指定します。
intervalTimeZone	－	GMT	エクスポート・インポートの対象のコンテナが日付蓄積型コンテナの場合に、エクスポート・インポートのコマンドのintervalsオプションのTimeZoneを設定します。TimeZone設定として、タイムゾーンまたはGMT+HH:mmフォーマットでTimeZoneを指定します。

エクスポートの機能

ここでは、エクスポート機能を利用する際に指定できるオプションについてエクスポートの使用例を元に説明します。

処理対象の指定

コンテナの指定方法

GridDBクラスタからコンテナを取り出すには、クラスタの全コンテナを指定する方法、データベースを指定する方法、コンテナを個別に指定する方法があります。

(1) 全てのコンテナの指定

クラスタ内の全てのデータベースの全てのコンテナが対象。
--allオプションを指定。
【例】
```
$ gs_export --all -u admin/admin
```
【メモ】
- 一般ユーザが実行する時、一般ユーザがアクセス権を持つ全データベース内のコンテナが対象になります。

(2) データベースの指定

指定したデータベースの全てのコンテナが対象。
--dbオプションでデータベース名を指定。複数のデータベース名を" "(ブランク)で区切って繰返し指定することも可能。

【例】

$ gs_export --db db001 db002 -u admin/admin　//DB名を列挙。DB内のコンテナ

【メモ】
- 一般ユーザが実行する時、--dbで指定したデータベースに対するアクセス権が無い場合は、エラーになります。(--forceを指定していると、処理は継続されます。)

(3) コンテナの個別指定

指定したコンテナが対象
コンテナ名を列挙
- --containerオプションで複数のコンテナ名を" "(ブランク)で区切って繰返し指定。
コンテナ名の正規表現指定
- --containerregexオプションでコンテナ名を正規表現で指定。指定にはJavaの正規表現が利用可能。正規表現で指定する場合は""（ダブルクォーテーション）で指定を括ります。

【例】

$ gs_export --container c001 c002 -u admin/admin　　　 //コンテナ名を列挙
$ gs_export --containerregex "^c0" -u admin/admin　　　//正規表現指定：コンテナ名がc0で始まるコンテナの指定

【メモ】
- --container/--containerregexオプションでは、--prefixdbオプションで対象のデータベース名を指定します。 --prefixdb オプションを省略した場合は、デフォルトの接続先データベース「public」内のコンテナが処理対象になります。
- 一般ユーザが実行する時、--container/--containerregexオプションで指定したコンテナが格納されているデータベースに対するアクセス権が無い場合は、エラーになります。(--forceを指定していると、処理は継続されます。)

ロウの指定方法

コンテナからエクスポートする際に、どのロウを出力するか条件を指定できます。条件の指定方法は、エクスポートコンテナ種別毎にそれぞれ以下の方法を用いることができます。

エクスポートコンテナ種別	指定の種別	方法
登録更新型コンテナ	検索クエリによる指定	コンテナ名と検索クエリを定義して指定
日付蓄積型コンテナ	タイムインターバルによる指定	取り出すロウのキー(TIMESTAMP型)についての日付範囲を指定

条件が指定されていないコンテナは、コンテナに格納されているすべてのロウがエクスポートされます。

◆検索クエリを用いた指定エクスポートコンテナ種別が登録更新型コンテナの場合に利用できる方法です。

--filterfileオプションで、コンテナ名と検索クエリを記述した定義ファイルを指定します。定義ファイルには、検索クエリを適用する対象のコンテナと、検索クエリを記述してください。

【例】実行例

$ gs_export -c c001 c002 -u admin/admin --filterfile filter1.txt
　　
$ gs_export --all -u admin/admin --filterfile filter2.txt

【例】定義ファイルの記述

^cont_month     :select * where time > 100  [改行]
^cont_minutes_.*:select * where flag = 0    [改行]
cont_year2014   :select * where timestamp > TIMESTAMP('2014-05-21T08:00:00.000Z') [改行]

【メモ】

コンテナは、Javaの正規表現で指定します。例) "container1"と記述すると、container1を含むコンテナが該当します(container10, container12など)。完全一致の場合は、"^container1$"と記述してください。
--allや-cオプションで指定されたエクスポート対象コンテナの中で、定義ファイルに記述された定義に当てはまらないコンテナは、すべてのロウがエクスポートされます。
コンテナと検索クエリの区切りは":"を指定し、コンテナと検索クエリは1行で記述してください。
コンテナが複数の定義に該当する場合、最初に記述された定義が適用されます。
ファイルはUTF-8で記述してください。
エクスポートのテスト機能を実行すると、定義ファイルの記述が正しいかを確認することができます。
ORDER BYは使用できません。

◆タイムインターバルによる指定エクスポートコンテナ種別が日付蓄積型コンテナの場合に利用できる方法です。

--intervals オプションで、取り出すロウの日付範囲を指定します。コンテナのキー（日付蓄積型コンテナの場合、TIMESTAMP型です）と比較します。

【例】実行例

$ gs_export -c tsc001 tsc002 -d ./2021/ --intervals 20210101:20211231

$ gs_export --all -u admin/admin -d ./20210131/ --intervals 20210101:20210131

【メモ】

タイムインターバルの指定を行わない場合、対象となるコンテナのすべての期間のデータが出力の対象となります。
--all ですべてのコンテナを指定しますが、そのうち、日付蓄積型コンテナのみが出力の対象となります。
複数のロウデータファイルが出力されるので、出力先のディレクトリを -d オプションにより合わせて指定することを推奨します。

ユーザ・アクセス権の指定方法

GridDBクラスタのユーザやアクセス権の情報もエクスポートすることができます。クラスタ上のすべてのデータを移行する場合にご利用ください。

--aclオプションと--allオプションまたは--dbオプションを指定。ただし、エクスポートできるユーザ情報は、一般ユーザのみです。管理ユーザの情報は別途移行（ユーザ定義ファイルをコピー）してください。

【例】

$ gs_export --all -u admin/admin --acl

$ gs_export --db db001 -u admin/admin --acl

【メモ】

管理ユーザで実行する必要があります。

ビューの指定方法

GridDBクラスタのビューもコンテナと合わせてエクスポートすることができます。

　--allオプションまたは--dbオプションを指定したとき、エクスポート対象のデータベースのビューがエクスポートされます。

$ gs_export --db public -u admin/admin
エクスポートを開始します
出力ディレクトリ : /tmp/export
     :
対象コンテナ数 : 5 ( 成功:5  失敗:0 )

対象ビュー数 : 15
エクスポートを終了しました

ロウデータファイルの出力形式の指定

ロウデータファイルの出力形式として、CSVデータファイル、もしくはバイナリデータファイルが指定できます。登録更新型コンテナ、および、日付蓄積型コンテナのいずれに対しても指定可能です。

CSVデータファイルでの出力
- --binaryオプションを指定せずにエクスポートを実行します。
バイナリデータファイルでの出力
- --binary [ファイルサイズ上限] オプションを指定します。
- 指定したファイルサイズ上限でバイナリデータファイルを分割してエクスポートします。
- ファイルサイズ上限はMbytes単位で指定します。ファイルサイズ上限の指定を省略するとサイズ上限は100Mbytesとなります。指定できる最大ファイルサイズは1,000Mbytesです。

【例】

$ gs_export -c c001 c002 -u admin/admin --binary
　　
$ gs_export --all -u admin/admin --binary 500       //500Mbytesごとにバイナリデータファイルを分割

コンテナデータファイル出力構成の指定

登録更新型コンテナをエクスポートする場合、出力するコンテナデータファイルの構成を指定できます。

コンテナ単位にコンテナデータファイルを作成するシングルコンテナデータファイル、もしくは全コンテナを１つのコンテナデータファイルに出力するマルチコンテナデータファイルが指定できます。

シングルコンテナデータファイルでの出力
- エクスポート時に--outオプションを指定しない場合、シングルコンテナデータファイルで出力されます。
マルチコンテナデータファイルでの出力
- --out [ファイル識別子] オプションを指定します。ファイル識別子の指定により、メタデータファイルのファイル名は「ファイル識別子_properties.json」となります。マルチコンテナデータファイルがCSVデータファイルの場合「ファイル識別子.csv」、バイナリデータファイルの場合「ファイル識別子_divN.mc」(Nは分割されたファイルの連番)となります。ファイル識別子の長さは20文字までです。
- --out [ファイル識別子] オプションでファイル識別子を省略した場合、ファイル識別子は実行した日時になります。（例：20131031_155015_810_properties.json ,20131031_155015_810.csv）

【例】

$ gs_export -c c001 c002 -u admin/admin --out test
　　
$ gs_export --all -u admin/admin --out           //日付でファイルが作成される

出力先の指定

コンテナデータファイルの出力先として、ディレクトリを指定できます。指定したディレクトリが存在しなかった場合にはディレクトリを作成します。ディレクトリの指定を省略した場合、コマンド実行時のカレントディレクトリにデータを出力します。出力先の指定は-dオプションを用います。

【例】

$ gs_export --all -u admin/admin --out test -d /tmp

【メモ】

既にコンテナデータファイルが存在するディレクトリは指定できません。

並列実行数の指定

エクスポートツールで並列にクラスタにアクセスしてデータを取得します。クラスタが複数のノードで構成されている場合に並列実行すると、ノードごとに並列アクセスするので高速に取得することができます。

--parallelオプションを指定することで、指定された数で並列実行を行います。並列実行を行うと、エクスポートデータは並列実行数と同じ数で分割されます。指定範囲は、2から32までです。

【メモ】

--parallelオプションは、バイナリ形式(--binaryオプション)、および、マルチコンテナ形式(--outオプション)を指定した場合のみ指定できます。

【例】

$ gs_export --all -u admin/admin --binary --out --parallel 4

テスト実行機能

利用者がコンテナをエクスポートする前に、正しくエクスポートが行えるかを評価することができます。

テスト実行指定
- 通常のエクスポートコマンドの利用に対して、--testオプションを追加するだけで、エクスポートシーケンスを確認することができます。確認のみで実際の取得処理は行わないので、ファイルは作成されません。
- テスト実行時、コンテナ名、パーティションID、ロウ数の情報を表示します。

【例】

$ gs_export -u admin/admin --all --test
エクスポートを開始します
[テストモード]
出力ディレクトリ : /var/lib/gridstore/export
対象コンテナ数  : 5

Name                                      PartitionId Row
------------------------------------------------------------------
public.container_2                                 15          10
public.container_3                                 25          20
public.container_0                                 35          10
public.container_1                                 53          10
public.container_4                                 58          20

対象コンテナ数 : 5 ( 成功:5  失敗:0 )

対象ビュー数 : 15
エクスポートを終了しました

エラー継続指定

別アプリケーションとのロック競合によってロウデータ取得エラーが発生した場合も、エクスポート処理を継続できます。

--forceオプションを指定することで、ロウデータ取得エラーが発生しても、次コンテナのロウデータからエクスポート処理を継続します。

【例】

$ gs_export --all -u admin/admin --force

【メモ】

エラーによって処理をスキップしたコンテナについても、不完全ですがコンテナデータファイルに情報を出力します。ただし、エクスポート実行ファイルには記録していないため、インポート処理されることはありません。ロウデータ取得エラー解決後、当該コンテナのエクスポート処理を再実行してください。
--forceオプションを指定していない場合、エラーが発生した時点で、エクスポート処理を終了します。

【例】

$ gs_export --all -u admin/admin

エクスポートを開始します
出力ディレクトリ : /var/lib/gridstore/export
対象コンテナ数  : 6

Name                                      PartitionId Row
------------------------------------------------------------------
public.container_2                                 15          10
public.container_3                                 25          20
[エラーが発生]

対象コンテナ数 : 6 ( 成功:2  失敗:1 未処理:3  )

エクスポートを終了しました

【注意】

--parallelオプションの指定時にエラーが発生しても、エクスポート処理がすぐに終了しない場合があります。

その他の機能

動作表示の詳細指定

--verboseオプションを指定することで、処理の詳細を表示することができます。

【例】

$ gs_export --containerregex "^c0" -u admin/admin --verbose
エクスポートを開始します
出力ディレクトリ : /data/exp
対象コンテナ数  : 4

public.c003 : 1
public.c002 : 1
public.c001 : 1
public.c010 : 1
ロウデータの取得を完了しました: time=[5080]

対象コンテナ数 : 4 ( 成功:4  失敗:0 )
エクスポートを終了しました

動作表示の抑止指定

--silentオプションを指定することで、処理状況の表示が抑制できます。

【例】

$ gs_export -c c002 c001 -u admin/admin --silent

インポートの機能

コンテナデータファイルのデータを、GridDBクラスタにインポートします。

インポート元データソースの種類

インポートツールの入力データソースには、以下があります。

コンテナデータファイル：エクスポート機能で保存したコンテナデータ、またはユーザが作成したコンテナデータ

コンテナデータファイルからのインポート

エクスポート機能でエクスポートしたデータ形式のデータをGridDBクラスタにインポートします。

処理対象の指定

コンテナデータファイルの中からインポートする処理対象のデータを指定する必要があります。

コンテナの指定方法

コンテナデータファイル内の全コンテナを指定する方法、データベースを指定する方法、コンテナを個別に指定する方法があります。

(1) 全てのコンテナの指定

全てのデータベースの全てのコンテナが対象
--allオプションを指定
【例】
```
$ gs_import --all -u admin/admin
```

(2) データベースの指定

指定したデータベースの全てのコンテナが対象。
データベース名を列挙
- --dbオプションで複数のデータベース名を" "(ブランク)で区切って繰返し指定。

【例】

$ gs_import --db db001 db002 -u admin/admin　//DB名を列挙。DB内のコンテナ

(3) コンテナの個別指定

指定したコンテナが対象。
コンテナ名を列挙
- --containerオプションで複数のコンテナ名を" "(ブランク)で区切って繰返し指定。
コンテナ名の正規表現指定
- --containerregexオプションでコンテナを正規表現で指定。指定にはJavaの正規表現が利用可能。正規表現で指定する場合は""（ダブルクォーテーション）で指定を括ります。

【例】

$ gs_import --container c001 c002 -u admin/admin　//コンテナ名を列挙
$ gs_import --containerregex "^c0" -u admin/admin　　　//正規表現指定：コンテナ名がc0で始まるコンテナの指定

【注意事項】

GridDB V3.2以前でエクスポートしたデータにNewSQL I/Fで作成したテーブルが含まれる場合、V3.5以降ではコレクションとしてインポートされます。また、テーブルの索引に設定されている索引名はインポートされません。

【メモ】

管理ユーザで実行する時、コンテナの格納先のデータベースが存在しない場合はデータベースを作成します。
一般ユーザが実行する時、コンテナの格納先のデータベースが存在しない場合、またはアクセス権が無い場合は、エラーになります。(--forceを指定していると、処理は継続されます。)
--container/--containerregexオプションを指定した場合、--prefixdbオプションで対象のデータベース名を指定します。 --prefixdbオプションを省略した場合は、デフォルトの接続先データベース「public」が処理対象になります。
コンテナデータファイルに格納されているコンテナ一覧は--listオプションで確認してください。

ユーザ・アクセス権の指定方法

エクスポート機能で--aclオプションを指定してエクスポートしたデータの場合、ユーザやアクセス権の情報もインポートすることができます。クラスタ上のすべてのデータを移行する場合にご利用ください。

--aclオプションと--allオプションまたは--dbオプションを指定。

【例】

$ gs_import --all --acl -u admin/admin

$ gs_import --db db001 --acl -u admin/admin

【メモ】

管理ユーザで実行する必要があります。
クラスタ上のすべてのデータを移行する場合にご利用ください。移行先にはデータベース・一般ユーザが存在しない状態で実行してください。

ビューの指定方法

エクスポート機能でビューをエクスポートしたデータの場合、コンテナデータと共にビューもインポートすることができます。

--allオプションまたは--dbオプションを指定したとき、インポート対象のデータベースのビューがインポートされます。

【メモ】

--replaceオプションが指定された場合、ビューのインポートは次の動作となります。
- 同名のコンテナが存在する場合はエラーとなります。--forceオプションを指定した場合もエラーとなります。
- 同名のビューが存在する場合は、既存のビューを削除し、新たにビューを作成します。
作成されたビューのうち、参照不可能なビューがあった場合、その旨が表示されます。

コンテナデータファイルの指定

インポートするコンテナデータファイルを指定します。日付蓄積型コンテナの場合にのみ、インポートする日付範囲の指定が可能です。

指定方法	エクスポートコンテナ種別	説明
ディレクトリを指定	登録更新型コンテナ	ディレクトリ内でインポートするコンテナを指定します
	日付蓄積型コンテナ	同上
タイムインターバルを指定	日付蓄積型コンテナ(のみ)	インポートする日付範囲を指定します

◆ディレクトリを指定

-dオプションでコンテナデータファイルの配置されているディレクトリを指定します。
ディレクトリの指定が省略された場合、コマンド実行時のカレントディレクトリのコンテナデータファイルが対象となります。

【例】

//カレントディレクトリから全コンテナを指定
$ gs_import --all -u admin/admin

//特定ディレクトリからデータベースを複数指定
$ gs_import --db db002 db001 -u admin/admin  -d /data/expdata

//特定ディレクトリからコンテナを複数指定
$ gs_import -c c002 c001 -u admin/admin  -d /data/expdata

【メモ】

コンテナデータファイルの手動作成等により、エクスポート実行情報ファイル(gs_export.json)が存在しない場合には、-fオプションでメタデータファイル(XXXXX_properties.json)を指定してください。-fオプションを指定しない場合、インポートは失敗します。

◆タイムインターバルを指定

--intervals オプションでインポートする日時範囲を指定します。
指定が省略された場合、すべての日時範囲（すべてのコンテナデータファイル）が対象となります。

【例】

//カレントディレクトリから全コンテナを指定し、指定した特定区間のデータのみをインポート
$ gs_import --all -u admin/admin --intervals 20210101:20211231

//特定ディレクトリからデータベースを複数指定し、指定した特定区間のデータのみをインポート
$ gs_import --db db002 db001 -u admin/admin -d ./2021/ --intervals 20210101:20211231

//特定ディレクトリからコンテナを複数指定し、指定した特定区間のデータのみをインポート
$ gs_import -c c002 c001 -u admin/admin  -d ./20210131/ --intervals 20210101:20210131

【メモ】

日付蓄積型コンテナのエクスポートデータが対象です。登録更新型コンテナに対しては指定できません。

コンテナ一覧の取得

コンテナデータファイル内に格納されたコンテナ情報をインポートする前に確認することができます。

【例】

$ gs_import --list
エクスポートデータファイルのコンテナ一覧を表示します
DB            Name              Type            FileName
public        container_2       COLLECTION      container_2.csv
public        container_0       TIME_SERIES     container_0.csv
public        container_1       COLLECTION      container_1.csv
userDB        container_1_db    TIME_SERIES     userDB.container_1_db.csv
userDB        container_2_db    TIME_SERIES     userDB.container_2_db.csv
userDB        container_0_db    COLLECTION      userDB.container_0_db.csv

データ登録オプション

インポートでは、特定のオプションの指定がないときは、登録しようとしたコンテナが既にGridDBクラスタ内に存在するとエラーとなります。次のオプションを指定することで、データの追加や、置き換えができます。データ登録では、登録に成功したコンテナ数と失敗したコンテナ数を表示します。

データの追加･更新

--appendオプションを指定することで、既存のコンテナへのデータ登録と更新ができます。
データの追加登録・更新ができるのは、既存のコンテナと登録しようとするコンテナのスキーマおよび索引の設定情報などのコンテナの定義情報が同一の場合のみです。

コンテナの種類に応じた登録の動作は以下となります。

コンテナの種類	Rowkey指定	動作
コレクション	有り	キーが等しいカラムは更新され、キーが異なるデータは追加される。
	無し	ロウデータはすべて追加登録される
時系列コンテナ	有り	時刻が既存の登録データより新しい場合、追加登録される。時刻が既存のものと同じ場合カラムデータが更新される。

時系列コンテナに対して同じ時刻のデータを追加登録した場合、既存のロウに上書き登録されます。ロウは増えません。
--schemaCheckSkipオプションを指定すると、既存コンテナの定義情報のチェックを行いません。新たに索引を追加してインポートする場合など、既存コンテナの定義と異なるデータをインポートする際にはこのオプションを指定してください。

コンテナの置き換え
- --replaceオプションを指定することで、既存のコンテナを削除し、新たにコンテナを作成しデータを登録します。

【例】

$ gs_import -c c002 c001 -u admin/admin  --append
..インポートを開始します（追記モード）
インポートを完了しました
成功:2  失敗:0
　
$ gs_import -c c002 c001 -u admin/admin  --replace　　 //特定のディレクトリから
..インポートを開始します（再配置モード）
インポートを完了しました
成功:2  失敗:0
　
$ gs_import --all  -u admin/admin  -d /datat/expdata   --replace

エラー継続指定

コンテナデータファイルのユーザ編集ミスによって特定のロウデータで登録エラーが発生した場合も、インポート処理を継続できます。

--forceオプションを指定することで、ロウデータの登録エラーが発生しても、次コンテナのロウデータからインポート処理を継続します。

【例】

$ gs_import --all -u admin/admin -d /data/expdata --force

【メモ】

エラーが発生したコレクションは、コンテナデータファイル修正後、コンテナ置き換えオプション（--replace）を指定して再登録してください。
--forceオプションを指定していない場合、エラーが発生した時点で、インポート処理を終了します。

【例】

$ gs_import --all -u admin/admin

インポートを開始します
対象コンテナ数  : 6

Name                                      PartitionId Row
------------------------------------------------------------------
public.container_2                                 15          10
public.container_3                                 25          20
[エラーが発生]

対象コンテナ数 : 6 ( 成功:2  失敗:1 未処理:3  )

インポートを終了しました

【注意】

--parallelオプションの指定時にエラーが発生しても、インポート処理がすぐに終了しない場合があります。

その他の機能

動作表示の詳細指定

--verboseオプションを指定することで、処理の詳細を表示することができます。

進捗状況の出力指定

--progressオプションと値を指定することで、importで登録したロウ数を指定した値の間隔でログ出力することができます。

【例】

$ gs_import --all -u admin/admin --progress 10000

[gs_importのログ]
container_1: 10000 rows imported.
container_1: 20000 rows imported.
container_1: 30000 rows imported.
      ：
  　　：
  　　：

コマンド/オプション仕様

エクスポートコマンド

コマンド一覧

コマンド	オプション/引数
gs_export	-u｜--user ユーザ名/パスワード --all ｜ --db データベース名 [データベース名] ｜ ( --container コンテナ名 [コンテナ名] … ｜ --containerregex 正規表現 [正規表現] …) 　　　　　　 [-d｜--directory 出力先ディレクトリパス] 　　　　　　 [--out [ファイル識別子] 　　　　　　 [--binary [ファイルサイズ]] 　　　　　　 [--filterfile 定義ファイル名] 　　 [--intervals YYYYMMdd:YYYYMMdd]　　　　 [--parallel 並列実行数] 　　　　　　 [--acl] 　　　　　　 [--prefixdb データベース名] 　　　　　　 [--force] 　　　　　　 [-t｜--test] 　　　　　　 [-v｜--verbose] 　　　　　　 [--silent] [--schemaOnly]
gs_export	--version
gs_export	[-h｜--help]

オプション仕様

オプション	必須	説明
-u｜--user ユーザ/パスワード	〇	認証に使用するユーザ、パスワードを指定します。
--all	〇	クラスタの全コンテナをエクスポート対象とします。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
--db	〇	指定されたデータベース上のすべてのコンテナをエクスポート対象とします｡--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
-c｜--container コンテナ名 …	〇	エクスポート対象となるコンテナを指定します。ブランク区切りで複数指定可能です。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
--containerregex 正規表現 …	〇	エクスポート対象となるコンテナを正規表現で指定します。ブランク区切りで複数指定可能です。正規表現を使用する場合はダブルクォートで囲んで指定します。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。--containerオプションとの併用可能です。
-d｜--directory 出力先ディレクトリパス		エクスポート先のディレクトリパスを指定します。デフォルトはカレントディレクトリです。
--out [ファイル識別子]		出力データのファイル形式をマルチコンテナ形式とする場合に指定します。省略した場合は、シングルコンテナ形式となります。ファイル識別子の長さは20文字までです。ファイル識別子が指定された場合はファイル識別子を含むファイル名として、省略された場合は、出力開始日時をファイル名として出力します。
--binary [ファイルサイズ]		ロウデータファイルの出力形式をバイナリ形式とする場合に指定します。省略した場合は、CSV形式となります。出力ファイルサイズはMB単位で指定します。デフォルトは、100MBです。指定範囲は1から1000(1GB)までです。
--filterfile 定義ファイル名		ロウを取り出す検索クエリを記述した定義ファイルを指定します。省略した場合は、すべてのロウがエクスポートされます。
--intervals YYYYMMdd:YYYYMMdd		エクスポート対象のコンテナが日付蓄積型コンテナの場合に、エクスポートで取り出すロウの期間を指定します。指定方法は「YYYYMMdd:YYYYMMdd」フォーマットで左に開始日、右に終了日を指定します。省略した場合は、すべてのロウがエクスポートされます。filterfileオプションと同時に指定することはできません。
--parallel 並列実行数		指定された数で並列実行を行います。並列実行を行うと、エクスポートデータは並列実行数と同じ数で分割されます。マルチコンテナ形式の場合(--outオプションを指定した場合)のみ指定できます。指定範囲は、2から32までです。
--acl		データベース、ユーザ、アクセス権の情報もエクスポートします。管理者ユーザで、かつ --allオプションまたは--dbオプションを指定している場合のみ指定できます。
--prefixdb データベース名		--containerオプションを指定した場合に、コンテナのデータベース名を指定します。省略した場合は、デフォルトデータベースのコンテナが処理対象になります。
--force		エラーが発生しても処理を継続します。エラー内容は処理終了後に一覧表示されます。
-t｜--test		テストモードでツールを実行します。
-v｜--verbose		動作表示を詳細出力します。
--silent		動作表示を出力しません。
--schemaOnly		コンテナの定義のみエクスポートします。ロウデータはエクスポートしません。
--version		ツールのバージョンを表示します。
-h｜--help		ヘルプメッセージとしてコマンド一覧を表示します。

【メモ】

-t(--test)オプションを指定した場合、クエリを実行しフェッチまでを実施します。コンテナデータファイルの作成は行いません。
-v(--verbose)オプションを指定した場合、処理中のメッセージを表示します。省略した場合は、エラー時のみメッセージを表示します。
-d(--directory)オプションで指定したディレクトリパスが存在しない場合、--outオプションで指定したファイル名が存在しない場合、それぞれディレクトリやファイルを作成します。
-c(--container)オプションを指定した場合、コンテナ名にJavaの正規表現を指定することができます。詳細は、Javaの「クラス Pattern」を参照してください。
--intervalsオプションで、指定時に開始時刻や終了時刻が分からない場合は明らかに小さな値(19700101)や大きな値(99991231)を指定してください。

インポートコマンド

コマンド一覧

コマンド	オプション/引数
gs_import	-u｜--user ユーザ名/パスワード --all ｜ --db データベース名 [データベース名] ｜ ( --container コンテナ名 [コンテナ名] … ｜ --containerregex 正規表現 [正規表現] …) --db データベース名 [データベース名] [--append｜--replace] [-d｜--directory インポート対象ディレクトリパス] [-f｜--file ファイル名 [ファイル名…]] [--intervals YYYYMMdd:YYYYMMdd] [--count コミット数] [--progress 出力間隔] [--acl] [--prefixdb データベース名] [--force] [--schemaCheckSkip] [-v｜--verbose] [--silent]
gs_import	-l｜--list [-d｜--directory ディレクトリパス] [-f｜--file ファイル名 [ファイル名…]]
gs_import	--version
gs_import	[-h｜--help]

オプション仕様

オプション	必須	説明
-u｜--user ユーザ/パスワード	〇	認証に使用するユーザ、パスワードを指定します。
--all	〇	インポート元のファイルの全コンテナをインポート対象とします。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
--db	〇	指定されたデータベース上のすべてのコンテナをインポート対象とします｡--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
-c｜--container コンテナ名 …	〇	インポート対象となるコンテナを指定します。ブランク区切りで複数指定可能です。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。
--containerregex 正規表現 …	〇	インポート対象となるコンテナを正規表現で指定します。ブランク区切りで複数指定可能です。正規表現を使用する場合はダブルクォートで囲んで指定します。--all、--containerまたは--containerregex、--dbオプションのいずれかの指定が必要です。--containerオプションとの併用可能です。
--append		既存のコンテナに、データを追加登録・更新します。
--replace		既存のコンテナを削除して再作成します。
-d｜--directory ディレクトリパス		インポート元のディレクトリパスを指定します。デフォルトはカレントディレクトリです。
-f｜--file ファイル名 [ファイル名…]		インポート対象となるコンテナデータファイルを指定します。複数指定可能です。省略時は-d(--directory)で指定したディレクトリまたはカレントディレクトリのすべてのコンテナデータファイルを対象とします。
--intervals YYYYMMdd:YYYYMMdd		インポート対象となるコンテナが日付蓄積型コンテナの場合に、インポートで取り出すロウデータファイルの期間を指定します。指定方法は「YYYYMMdd:YYYYMMdd」フォーマットで左に開始日、右に終了日を指定します。省略した場合は、すべてのロウデータファイルがインポートされます。
--count コミット数		入力データを一括コミットするまでの入力件数を指定します。
--progress 出力間隔		登録したロウ数をログ出力する間隔を指定します。
--acl		データベース、ユーザ、アクセス権の情報もインポートします。--aclオプションを指定してエクスポートしたデータに対して、管理者ユーザで、かつ --allオプションまたは--dbオプションを指定している場合のみ指定できます。
--prefixdb データベース名		--containerオプションを指定した場合に、コンテナのデータベース名を指定します。省略した場合は、デフォルトデータベースのコンテナが処理対象になります。
--force		エラーが発生しても処理を継続します。エラー内容は処理終了後に一覧表示されます。
--schemaCheckSkip		--appendオプションを指定した場合に、既存コンテナとのスキーマチェックを行いません。
-v｜--verbose		動作表示を詳細出力します。
--silent		動作表示を出力しません。
-l｜--list		指定したインポート対象のコンテナの一覧を表示します。
--version		ツールのバージョンを表示します。
-h｜--help		ヘルプメッセージとしてコマンド一覧を表示します。

【メモ】

-l(--list)が指定されており、-d(--directory)、-f(--file)オプション以外のオプションが指定されているとオプション引数エラーとなります。
-v(--verbose)オプションを指定した場合、処理中のメッセージを表示します。省略した場合は、エラー時のみメッセージを表示します。
--containerregexオプションを指定した場合、コンテナ名にJavaの正規表現を指定することができます。正規表現の詳細は、Javaの「クラス Pattern」を参照してください。
--intervalsオプションで、指定時に開始日付や終了日付が分からない場合は明らかに小さな値(19700101)や大きな値(99991231)を指定してください。

コンテナデータファイルの形式

コンテナデータファイルを構成するそれぞれのファイル形式を以下に示します。

メタデータファイル

コンテナ情報をJSON形式で格納します。格納するコンテナ情報を以下に示します。

項目	説明
コンテナ名	コンテナの名称です。
コンテナ種別	コレクションまたは時系列コンテナを指定します。
スキーマ情報	ロウを構成するカラム集合の情報です。カラム名、データ型、カラム制約を指定します。
索引設定情報	コンテナに設定する索引種別の情報です。索引設定の有無。ツリー索引、空間索引等の種別を指定します。
ロウキー設定情報	コレクションの場合、ロウキーを設定します。時系列コンテナの場合、ロウキー設定なしであるか、デフォルトが設定されている場合はその値が有効となります。
テーブルパーティショニング情報	テーブルパーティショニングの定義情報を指定します。
タイムインターバル情報	日付蓄積型コンテナの場合、日付ごとに分割したロウデータファイルの情報を指定します。

以下にメタ情報のJSON形式のタグとデータ項目を示します。利用者が新規に作成する際に必須となるタグについても記載します(タグの設定条件）。

タグ名	項目	説明	設定条件
共通パラメータ
database	データベース名	データベース名	任意　省略した場合は"public"
container	コンテナ名	コンテナ名	必須
containerType	コンテナ種別	COLLECTION/TIME_SERIES のいずれかを指定	必須
containerFileType	コンテナデータファイル種別	csv/binary のいずれかを指定	必須
containerFile	コンテナデータファイル名	ファイル名	任意
dataAffinity	データアフィニティ名	データアフィニティの名前を指定	任意
partitionNo	パーティション	空文字列で未設定	任意　エクスポート時出力される。(インポート時は指定不要。指定しても値は利用されない。）
columnSet	カラム情報セット、(スキーマ情報)	既存コンテナへのデータ追加時は、カラム情報が合致している必要あり	必須
columnName	カラム名		必須
type	データ型	BOOLEAN/ STRING/ BYTE/ SHORT/ INTEGER/ LONG/ FLOAT/ DOUBLE/ TIMESTAMP/ GEOMETRY/ BLOB/ BOOLEAN[]/ STRING[]/ BYTE[]/ SHORT[]/ INTEGER[]/ LONG[]/ FLOAT[]/ DOUBLE[]/ TIMESTAMP[] のいずれかを指定	必須
notNull	NOT NULL制約	true/false　のどちらかを指定	任意　省略した場合は"false"
rowKeyAssigned	ロウキー設定(*1)	true/false　のいずれかを指定 rowKeySetと同時指定はエラー	任意　省略した場合は"false"
rowKeySet	ロウキーカラム名セット	ロウキーのカラム名を配列形式で指定既存コンテナへのデータ追加時は、ロウキーが合致している必要あり	任意　(*2)
indexSet	索引情報セット	カラム毎に設定可能。存在しないカラム名は無視/エラー出力はする	任意
columnNames	カラム名セット	カラム名を配列形式で指定	任意(indexSet指定時は必須)
type	索引種別	TREE ( STRING/ BOOLEAN/ BYTE/ SHORT/ INTEGER/ LONG/ FLOAT/ DOUBLE/ TIMESTAMP ) 、 SPATIAL ( GEOMETRY )のいずれかを指定	任意　(indexSet指定時は必須)
indexName	索引名	索引名	任意　nullを指定した場合や省略した場合は未設定
テーブルパーティショニング情報
tablePartitionInfo	テーブルパーティショニング情報	インターバル-ハッシュパーティショニングの場合は、インターバル、ハッシュの順番で以下の情報を配列形式で記述します	任意
type	テーブルパーティショニング種別	指定する値は次の2種類ハッシュ:HASH、インターバル:INTERVAL	tablePartitionInfoを記載した場合は必須
column	パーティショニングキー	指定できるカラムの型は type=HASHの場合制限なし type=INTERVALの場合 BYTE型,SHORT型,INTEGER型,LONG型,TIMESTAMP型	tablePartitionInfoを記載した場合は必須
divisionCount	ハッシュの分割数	(type=HASHの場合のみ有効)ハッシュの分割数	type=HASHの場合は必須
intervalValue	分割基準値	(type=INTERVALの場合のみ有効)分割する間隔	type=INTERVALの場合は必須
intervalUnit	分割単位	(type=INTERVALの場合のみ有効)単位 DAY	type=INTERVAL,パーティショニングキーがTIMESTAMP型の場合は必須
インターバルまたはインターバル-ハッシュパーティショニングのみのパラメータ
expirationType	期限解放種別	パーティション期限解放を指定する場合は"partition"を指定	任意
expirationTime	解放対象の有効期限の基準とする経過期間	整数値を指定	expirationType指定時は必須
expirationTimeUnit	時間情報のENUM	DAY/ HOUR/ MINUTE/ SECOND/ MILLISECONDのいずれかを指定	expirationType指定時は必須
タイムインターバル情報
timeIntervalInfo	タイムインターバル情報	日付蓄積型コンテナの場合は、以下の情報を配列形式で記述します	任意
containerFile	コンテナデータファイル名	ファイル名	timeIntervalInfoを記載した場合は必須
boundaryValue	期間	コンテナデータの開始の日付	timeIntervalInfoを記載した場合は必須
データパーティション配置情報
intervalWorkerGroup	区間グループ番号	データパーティション配置を決定するグループ番号	任意
intervalWorkerGroupPosition	区間グループノード補正値	区間グループで決定したデータパーティションの処理ノードを補正する値	任意

*1 : V4.2以前のメタデータファイルに出力される情報です。V4.3以降ではrowKeySetを使用してください。
*2 : containerTypeがTIME_SERIESかつrowKeyAssignedがfalseである場合は必須です。

【メモ】

メタデータファイルは、文字コードUTF-8で記載します。
シングルコンテナデータファイルのメタデータファイルには、コンテナのメタ情報がjsonで記述されます。
マルチコンテナデータファイルのメタデータファイルには、コンテナのメタ情報がjsonの配列で記述されます。
エクスポートした場合、メタデータファイルのファイル名は以下の規則で命名されます。
- シングルコンテナ形式の場合
  - データベース名.コンテナ名_properties.json
  - ファイル名のデータベース名とコンテナ名の文字列はURLエンコードします。「エンコードしたデータベース名.エンコードしたコンテナ名」の文字長が140文字を超える場合は、140文字までで文字列を切り、最後に識別子(連番)を追加します。
  - 例)
```
次の3つのコンテナをエクスポートした時、
・データベース「db1」、コンテナ「container_・・・_2017/08/01」(140文字以上のコンテナ名)
・データベース「db1」、コンテナ「container_・・・_2017/09/01」(140文字以上のコンテナ名)
・データベース「db2」、コンテナ「container_・・・_2017/10/01」(140文字以上のコンテナ名)

メタデータファイルのファイル名は下記のようになります。(エンコードした文字列を140文字までで切り、連番を付加します）
db1.container・・・2017%2f08_0_properties.json
db1.container・・・2017%2f09_1_properties.json
db2.container・・・2017%2f10_2_properties.json
```
- マルチコンテナ形式の場合
  - --outオプションでファイル識別子を指定: ファイル識別子_properties.json
  - --outオプションでファイル識別子を省略: YYYYMMDD_HHmmss_SSS_properties.json

【注意】

ロウデータファイルをバイナリ形式でエクスポートした場合、メタデータファイルの編集は行わないでください。

【例１】シングルコンテナデータファイルでのコレクションの記述例 (public.c001_properties.json）

1つのコレクションを記述しています。

{
    "container": "c001",
    "containerFile": "public.c001.csv",
    "containerFileType": "csv",
    "containerType": "COLLECTION",
    "columnSet": [
        { "columnName": "COLUMN_ID",  "type": "INTEGER" },
        { "columnName": "COLUMN_STRING", "type": "STRING"}
    ],
    "indexSet": [
        { "columnName": "COLUMN_ID", "type": "TREE"},
        { "columnName": "COLUMN_STRING", "type": "TREE" }
    ],
    "rowKeyAssigned": true
}

【例２】マルチコンテナデータファイルでのコレクションおよび時系列コンテナの記述例 (public.container01_properties.json）

コレクションおよび時系列コンテナの場合

[
    {
        "container": "c001",
        "containerType": "collection",
        "containerFileType":"csv",
        "containerFile":"public.container01.csv",
        "rowKeyAssigned":true,
        "columnSet": [
            { "columnName": "COLUMN_FLAG", "type": "BOOLEAN" },
            { "columnName": "COLUMN_BLOB_DATA", "type": "BLOB" },
            { "columnName": "COLUMN_STRING", "type": "STRING" }
        ],
        "indexSet":[
            { "columnName":" COLUMN_STRING ", "indexType": "TREE" }
        ]
    },
    {
        "container": "c002",
        "containerType": "timeSeries",
        "containerFileType":"csv",
        "containerFile":"public.container01.csv",
        "rowKeyAssigned":true,
        "dataAffinity":"month",
        "columnSet": [
            { "columnName": "COLUMN_TIMESTAMP", "type": "TIMESTAMP" },
            { "columnName": "COLUMN_FLAG", "type": "BOOLEAN" },
            { "columnName": "COLUMN_BLOB_DATA", "type": "BLOB" },
            { "columnName": "COLUMN_INTEGER", "type": "INTEGER" }
        ],
        "indexSet":[
            { "columnName":" COLUMN_FLAG ", "indexType": "TREE" }
        ]
    }
]

【例３】テーブルパーティショニングの場合の記述例

ハッシュパーティショニングの場合（テーブルパーティショニング情報の部分のみ抜粋）
```
  "tablePartitionInfo":{
      "type": "HASH",
      "column": "column03",
      "divisionCount": 16
  }
```

インターバルパーティショニングの場合（テーブルパーティショニング情報の部分のみ抜粋）

  "tablePartitionInfo":{
      "type": "INTERVAL",
      "column": "timecolumn05",
      "intervalValue": 20,
      "intervalUnit": "DAY"
  }

インターバル-ハッシュパーティショニングの場合（テーブルパーティショニング情報の部分のみ抜粋）

  "tablePartitionInfo":[
       {
           "type": "INTERVAL",
           "column": "timecolumn05",
           "intervalValue": 10,
           "intervalUnit": "DAY"
       },
       {
           "type": "HASH",
           "column": "column03",
           "divisionCount": 16
       }
  ]

【メモ】

インターバル-ハッシュパーティショニングの場合、tablePartitionInfo以下にインターバル、ハッシュパーティションの順で記載する必要があります。逆の場合はエラーになります。

【例４】日付蓄積型コンテナの場合の記述例

タイムインターバル情報の部分のみ抜粋

  "timeIntervalInfo":[
    {
      "containerFile": "public.container01_2023-01-01_2023-01-02.csv",
      "boundaryValue": "2023-01-01T00:00:00.000+0000"
    }
  ]

【メモ】

区間グループ番号、区間グループノード補正値をユーザが配置指定した場合、メタ情報がjsonに記述されます。

【例１】データパーティション配置の記述例

区間グループ番号を1、区間グループノード補正値を1として、ユーザがデータパーティション配置指定した場合

{
  "version":"5.4.0",
  "database":"public",
  "container":"c001",
  "containerType":"COLLECTION",
  "containerFileType":"csv",
  "partitionNo":1,
  "columnSet":[
      { "columnName":"dt", "type":"TIMESTAMP", "notNull":true },
      { "columnName":"val", "type":"LONG", "notNull":true }
  ],
  "intervalWorkerGroup":1,
  "intervalWorkerGroupPosition":1,
  "rowKeySet":[
      "dt"
  ],
  "indexSet":[
      {
          "columnNames":[
              "dt"
          ],
          "type":"TREE",
          "indexName":null
      }
  ],
  "tablePartitionInfo":{
      "type":"INTERVAL",
      "column":"dt",
      "intervalValue":"1",
      "intervalUnit":"DAY"
  }
}

ロウデータファイル(バイナリデータファイル)

ロウデータファイル（バイナリデータファイル）はzip形式であり、gs_exportでのみ作成が可能です。可読性はなく、編集もできません。

ロウデータファイル(CSVデータファイル)

ロウデータファイル（CSVデータファイル）はCSV形式であり、コンテナデータファイル情報部にはロウの定義であるメタデータファイルへの参照を記述します。

【メモ】

CSVデータファイルは、文字コードUTF-8で記載します。

＜CSVデータファイルの形式＞

１.ヘッダ部（1～2行目）

ヘッダ部は、エクスポート時に出力される情報です。インポート時にヘッダ情報は不要です。

文頭に「#」を付与し区別します。フォーマットは以下とします。
```
"#(日時情報)(空白)GridDBリリースバージョン"
"#User:(ユーザ名)"
```

【例】

"#2017-10-01T17:34:36.520+0900 GridDB V4.0.00"
"#User:admin "

２.コンテナデータファイル情報部（3行目以降）

メタデータファイルへの参照を記述します。

文頭に「%」を付与し区別します。一行のフォーマットは以下とします。
```
"%","メタデータファイルのファイル名"
```

３.コンテナ名情報部（コンテナ情報部の直後）

ロウデータファイルに含まれているデータベース名、コンテナ名を記述します。エクスポートコンテナ種別により書式が異なります。

エクスポートコンテナ種別	コンテナ名情報部の書式
登録更新型コンテナ	データベース名とコンテナ名を記載
日付蓄積型コンテナ	データベース名とコンテナ名＋日付範囲を記載

◆データベース名とコンテナ名

文頭に「$」を付与し、データベース名とコンテナ名を記載します。
```
"$","データベース名.コンテナ名"
```

◆データベース名とコンテナ名＋日付範囲

文頭に「$」を付与し、データベース名とコンテナ名＋「日付範囲」を記載します。
「日付範囲」は開始の日付と終了の日付を"_"(アンダースコア)で連結した文字列になります。具体的には以下の例を参照してください。
```
"$","データベース名.コンテナ名_YYYY-MM-dd_YYYY-MM-dd"
```

４.ロウデータ部（コンテナ名情報部以降）

ロウデータ本体の記述です。

コンテナに登録したい数だけロウデータを記述します。

"値","値","値",．．（カラム定義個数）
"値","値","値",．．（カラム定義個数）
　　：
　　：　　　　//登録したいロウの数だけ記述する
　　：

【メモ】

ロウデータに含まれるバックスラッシュ\とダブルクォーテーション"は、それぞれバックスラッシュでエスケープして記述します。
カラムのデータ型がTIMESTAMPの場合、値は「yyyy-MM-dd'T'HH:mm:ss.SSSZ」形式で指定します。
- 例: "2016-12-25T00:22:30.000+0900"

４.コメント部

コメント部はCSVデータファイルのヘッダ部以外であればどこでも記述できます。

文頭に「#」を付与し区別します。

【メモ】

シングルコンテナデータファイルのCSVデータファイルは以下で構成されます。
- 　１.ヘッダ部　,２.コンテナデータファイル情報部　,３.ロウデータ部
マルチコンテナデータファイルのCSVデータファイルは以下で構成されます。
- 　１.ヘッダ部　,２.コンテナデータファイル情報部　,３.ロウデータ部(複数）

＜ファイル名形式＞

エクスポートツールで出力するCSVデータファイルのファイル名は以下となります。

シングルコンテナ形式の場合
- データベース名.コンテナ名.csv
- ファイル名のデータベース名とコンテナ名の文字列はURLエンコードします。「エンコードしたデータベース名.エンコードしたコンテナ名」の文字長が140文字を超える場合は、140文字までで文字列を切り、最後に識別子(連番)を追加します。
マルチコンテナ形式の場合
- --outオプションでファイル識別子を指定: ファイル識別子.csv
- --outオプションでファイル識別子を省略: YYYYMMDD_HHmmss_SSS.csv

【例】CSVデータファイル(外部オブジェクトファイル含む）の記述例メタデータファイル　例１の場合のデータの記述

"#2017-10-01T11:19:03.437+0900  GridDB V4.0.00"
"#User:admin"
"%","public.c001_properties.json"
"$","public.c001"
"1","Tokyo"
"2","Kanagawa"
"3","Osaka"

CSVデータファイルのロウの一部に以下のデータが含まれるとき、外部オブジェクトとしてCSVデータファイルとは別に外部オブジェクトファイルを用意します。外部データファイルの参照をCSVファイルの対象カラムに以下のように記載します。　 "@データ型:”（ファイル名称）

BLOBデータ
- BLOBデータとして該当するカラムの“値”部分に“@BLOB:”＋（ファイル名称）と記載します。
- ファイル名称部分は、ファイル名＋“.blob”　という形式です。
- バイナリファイルをファイル名称部分の規則にあわせて配置します。
空間情報
- 空間情報データとして該当する“値”部分に“@GEOMETRY:”＋（ファイル名称）と記載します。
- ファイル名称部分は、ファイル名＋“.geometry”という形式です。
- 外部オブジェクトファイルに空間列を記載します。
- 文字コードUTF-8で記載します。
配列型（BOOLEAN[]/ STRING[]/ BYTE[]/ SHORT[]/ INTEGER[]/ LONG[]/ FLOAT[]/ DOUBLE[]/ TIMESTAMP[]）
- 配列型データとして該当する“値”部分に“@(データ型)_ARRAY:”+（ファイル名称）と記載します。
- ファイル名称部分は、ファイル名＋“.(データ型)_array”という形式です。
- 文字列化したデータ長が100文字を超えている場合、外部オブジェクトファイルへ配列型データを記載します。
- 文字コードUTF-8で記載します。
文字列情報
- 文字列データとして該当する“値”部分に“@STRING:”+（ファイル名称）で記載します。
- ファイル名称部分は、ファイル名＋“.string”　という形式です。
- 文字列データ長が100文字を超えている、もしくは復帰(\r)を含む場合に、外部オブジェクトファイルへ文字列データを記載します。
- 文字コードUTF-8で記載します。

外部オブジェクトファイルをエクスポートしたとき、エクスポート時の外部オブジェクトファイル名は、以下の規則に従い作成されます。

シングルコンテナ形式の場合
- データベース名.コンテナ名_ROW番号_COLUMN番号.データ型
- ROW番号、COLUMN番号はコンテナのデータの順序番号を示し、番号0から採番されます。
- 例)コンテナのカラムがByte配列の場合、外部オブジェクトファイルはデータベース名.コンテナ名_ROW番号_COLUMN番号.byte_arrayとなります。
マルチコンテナ形式の場合
- --outオプションでファイル識別子を指定　ファイル識別子_データベース名.コンテナ名_ROW番号_COLUMN番号.データ型
- --outオプションでファイル識別子を省略　日時_データベース名.コンテナ名_ROW番号_COLUMN番号.データ型
ファイル名のデータベース名とコンテナ名の文字列はURLエンコードします。「エンコードしたデータベース名.エンコードしたコンテナ名」の文字長が140文字を超える場合は、140文字までで文字列を切り、最後に識別子(連番)を追加します。

インポートで利用する外部オブジェクトファイルのファイル名は任意です。CSVデータファイルの該当カラムに、@データ型:任意のファイル名で記載します。

【例】外部オブジェクトファイルの命名例

//BYTE配列を3カラム目に持つ　コレクション(colb)をエクスポートした場合
　
10月  4 12:51 2017 public.colb.csv
10月  4 12:51 2017 public.colb_0_3.byte_array
10月  4 12:51 2017 public.colb_1_3.byte_array
10月  4 12:51 2017 public.colb_2_3.byte_array
10月  4 12:51 2017 public.colb_3_3.byte_array
10月  4 12:51 2017 public.colb_4_3.byte_array
10月  4 12:51 2017 public.colb_properties.json

【例】シングルコンテナデータファイルでの外部オブジェクトファイルの記述

メタデータファイル　public.col01_properties.json

{
        "version": "4.0.0",
        "container": "col01",
        "containerFile": "public.col01.csv",
        "containerFileType": "csv",
        "containerType": "COLLECTION",
        "columnSet": [
            { "columnName": "name","type": "string"  },
            { "columnName": "status", "type": "boolean"},
            { "columnName": "count", "type": "long" },
            { "columnName": "lob", "type": "byte[]"
            }
        ],
        "indexSet": [
            {
                "columnName": "name",
                "type": "TREE"
            },
            {
                "columnName": "count",
                "type": "TREE"
            }
        ],
        "rowKeyAssigned": true
}

CSVデータファイル　public.col01.csv

"#2017-10-01T19:41:35.320+0900  GridDB V4.0.00"
"#User:admin"
"%","public.col01_properties.json"　
"$","public.col01"
"name02","false","2","@BYTE_ARRAY:public.col01_0_3.byte_array"

外部オブジェクトファイル　public.col01_03.byte_array
```
1,10,15,20,40,70,71,72,73,74
```

Files

Specification_ja.md

Latest commit

History

Specification_ja.md

File metadata and controls

エクスポート/インポートツール

ファイル構成

コンテナデータファイルとは

エクスポート実行情報ファイルとは

エクスポート／インポートの実行環境の設定

プロパティファイルの設定

エクスポートの機能

処理対象の指定

コンテナの指定方法

ロウの指定方法

ユーザ・アクセス権の指定方法

ビューの指定方法

ロウデータファイルの出力形式の指定

コンテナデータファイル出力構成の指定

出力先の指定

並列実行数の指定

テスト実行機能

エラー継続指定

その他の機能

インポートの機能

インポート元データソースの種類

コンテナデータファイルからのインポート

処理対象の指定

コンテナの指定方法

ユーザ・アクセス権の指定方法

ビューの指定方法

コンテナデータファイルの指定

コンテナ一覧の取得

データ登録オプション

エラー継続指定

その他の機能

コマンド/オプション仕様

エクスポートコマンド

インポートコマンド

コンテナデータファイルの形式

メタデータファイル

ロウデータファイル(バイナリデータファイル)

ロウデータファイル(CSVデータファイル)