dsbulk

DataStax Enterpriseの一括読み込みおよびアンロード・ツール

DataStaxデータ・ローダーdsbulkは、さまざまなソースからのデータの読み込みと、データの転送、使用、またはストレージを目的としたDataStax Enterpriseからのデータのアンロードの両方に使用できます。2つのサブコマンド、loadおよびunloadは単純なサブコマンドです。両方のサブコマンドとも、オプションkeyspacetableまたはschema.queryに加えて、データ・ソースを必要とします。また、ユーザーがDSEデータ・ローダーの動作方法を調整するのに役立つさまざまなオプションも使用できます。このようなオプションには、動作が読み込みの場合は入力データから、動作がアンロードの場合はデータベース・データから、それぞれ推測された定義済みのデフォルト値が用意されています。ここで説明するオプションは、機能別にグループ分けされ、追加の要件を記載できます。たとえば、CSVデータを読み込むまたはアンロードする場合、読み込みまたはアンロードに使用するCSVデータ・ファイルのパスまたはURLを指定して、connector.csv.urlオプションを設定する必要があります。

スタンドアロン・ツールが、ディストリビューションのbinディレクトリー内からコマンドdsbulkを使用して、起動されます。このツールによって、すべての設定のインライン・ヘルプも提供されます。オプション値を指定する構成ファイルを使用するか、コマンドラインでオプションを指定できます。コマンドラインで指定されたオプションは、構成ファイルのオプション設定をオーバーライドします。

構文

dsbulk ( load | unload | count ) [options]
  (( -k | --keyspace ) keyspace_name 
  ( -t | --table ) table_name) 
  | ( --schema.query string )
  [ help | --help ]

オプションは、短い形式(-k keyspace_name)でも、長い形式(--schema.keyspace keyspace_name)でも使用できます。

表 1. 凡例
構文規則 説明
大文字 リテラル・キーワード。
小文字 リテラル以外。
Italics 変数値。有効なオプションまたはユーザー定義値と置き換えます。
[ ] 任意。角かっこ( [] )で任意のコマンド引数を囲みます。角かっこは入力しないでください。
( ) グループ。丸かっこ(( ))は、選択肢を含むグループを示します。丸かっこは入力しないでください。
| または。縦棒(|)で代替要素を区切ります。要素のいずれかを入力してください。縦棒は入力しないでください。
... 繰り返し可能。省略記号(...)は、構文要素を必要な回数だけ繰り返すことができることを示します。
'Literal string' 単一引用符( ' )でdsbulk文内のリテラル文字を囲みます。大文字を維持するには、単一引用符を使用します。
{ key:value } マップ・コレクション。中かっこ( { } )でマップ・コレクションまたはキーと値のペアを囲みます。コロンでキーと値を区切ります。
<datatype1,datatype2> セット、リスト、マップ、またはタプル。山かっこ(< >)で、セット、リスト、マップまたはタプル内のデータ型を囲みます。データ型をカンマで区切ります。
[ -- ] コマンドライン・オプションとコマンド引数は、2つのハイフン(--)で区切ります。この構文は、引数がコマンドライン・オプションと間違われる可能性がある場合に役立ちます。

一般的な用途

dsbulkおよび共通オプションに関する一般的なヘルプを取得します。
dsbulk help
helpサブコマンドを使用するconnector.csvなど、特定のdsbulkオプションに関するヘルプを取得します。
dsbulk help connector.csv
一般的なヘルプとともに、短いオプションを表示するには、--helpオプションを指定してdsbulk -c csvを実行します。
dsbulk -c csv --help

コマンドライン引数のエスケープと引用

すべてのオプション値は、コマンドラインを使用して指定されると、有効なHOCON構文であると見なされます。たとえば、制御文字、バックラッシュ文字、および二重引用符文字はすべて、適切にエスケープされる必要があります。たとえば、\tはタブ文字に対応するエスケープ・シーケンスで、\\はバックスラッシュ文字のエスケープ・シーケンスです。
dsbulk load -delim '\t' -url 'C:\\Users\\My Folder'
一般的に、特殊文字を含んでいる文字列値も、HOCON構文で要求されるように、二重引用符で適切に囲む必要があります。
dsbulk load -url '"C:\\Users\\My Folder"'
ただし、予想されるオプションの種類が文字列の場合は、便宜上、両側の二重引用符を省略できます。このように、1番目の例では二重引用符がないことに注目してください。同様に、引数がリストの場合、両側の角かっこを省略することができます。この場合、以下の2行は同等です。
dsbulk load --codec.nullStrings 'NIL, NULL'
dsbulk load --codec.nullStrings '[NIL, NULL]'
マップの方の引数に同じ方法が適用されます。すなわち、両側の中かっこを省略できます。以下の2行は同等です。
dsbulk load --connector.json.deserializationFeatures '{ USE_BIG_DECIMAL_FOR_FLOATS : true }'
dsbulk load --connector.json.deserializationFeatures 'USE_BIG_DECIMAL_FOR_FLOATS : true'

この糖衣構文は、文字列、リスト、またはマップの型のコマンドライン引数でのみ利用できます。他のすべてのオプションの種類と、構成ファイルで指定されたすべてのオプションは、HOCON構文に完全に準拠する必要があり、このようなオプションが適切にエスケープされ、引用されていることを確認するのは、ユーザーの責任です。

データの読み込みの例

dsbulkを使用したデータ読み込みの例

stdinから読み込まれたCSVデータから、キースペースks1のテーブルtable1にデータを読み込みます。
dsbulk load -k ks1 -t table1
ファイルexport.csvの読み込みに使用する/tmp/dsbulk_load.confから、キースペースks1のテーブルtable1に構成ファイルを読み込みます。
dsbulk load -f /tmp/dsbulk_load.conf --connector.csv.url export.csv -k ks1 -t table1
urlの短い形式のオプションを使用して、キースペースks1のテーブルtable1にファイルexport.csvを読み込みます。
dsbulk load -url export.csv -k ks1 -t table1
urlの短い形式のオプションとフィールド区切り文字としてのタブ文字を使用して、キースペースks1のテーブルtable1にファイルexport.csvを読み込みます。
dsbulk load -k ks1 -t table1 -url export.csv -delim '\t'
urlの長い形式のオプションを使用して、キースペースks1のテーブルtable1にファイル/tmp/export.csvを読み込みます。
dsbulk load --connector.csv.url file:///tmp/export.csv -k ks1 -t table1
注: file:///tmp/export.csvはローカルホスト、file://指定では空のホストから読み込むことに注意してください。
stdoutに解凍して、dsbulkのstdinにパイプすることで、gzipped CSVファイルからks1テーブルのテーブルtable1を読み込みます。
gzcat table1.csv.gz | dsbulk load -k ks1 -t table1
目的のクラスターに属するホスト(初期のコンタクト・ポイント)をいくつか指定して、ヘッダーのない状態でローカル・ファイルから読み込みます。-mが指定されたテーブル・カラムへの入力のマップ・フィールド・インデックスは以下のとおりです。
dsbulk load -url ~/export.csv -k ks1 -t table1 -h '10.200.1.3, 10.200.1.4' -header false -m '0=col1,1=col3'
クラスター・ホストについてポート9876を指定して、外部ソースURLから読み込みます。
dsbulk load -url https://192.168.1.100/data/export.csv -k ks1 -t table1 -h '10.200.1.3,10.200.1.4' -port 9876
ディレクトリーからすべてのcsvファイルを読み込みます。ファイルにはヘッダー行-header falseが含まれていません。-mが指定されたテーブル・カラムへの入力のマップ・フィールド・インデックスは以下のとおりです。
dsbulk load -url ~/export-dir -k ks1 -t table1 -header false -m '0=col1,1=col3'
クラスター・ホストにデフォルトのポートを指定して、conf/application.confでキースペース、テーブル、およびマッピングが設定されています。
dsbulk load -url https://192.168.1.100/data/export.csv -h '10.200.1.3,10.200.1.4'
CSVファイルからキースペースks1のテーブルtable1を読み込みます。このとき、フィールドの二重引用符文字は、二重引用符でエスケープされます。たとえば、"f1","value with ""quotes"" and more"のような行がCSVファイル内にあります。
dsbulk load -url ~/export.csv -k ks1 -t table1 -escape '\"'
テーブルへのコレクションの読み込み時に、特定の役に立ついくつかの簡素化が実行されます。CSVファイル内のコレクションで有効なJSONを使用するか、より単純な非準拠JSONを使用できます。たとえば、以下のテーブルについて考えます。
CREATE TABLE t1 (col1 set<int> PRIMARY KEY, col2 list<int>, col3 map<text,int>);
このパイプ区切りCSVファイルには有効なJSONが含まれており、読み込むことができます。
col1|col2|col3
[1,2,3]|[1,2,3]|{"key1":1,"key2":2}
また、この類似するCSVファイルも読み込むことができます。
col1|col2|col3
1,2,3|1,2,3|"key1":1,"key2":2
両側の角かっこと中かっこは、3番目のカラムで有効なJSONから省略されることに注意してください。
重要: JSONデータの簡素化は、ネストされたコレクションには機能しません。テーブルにlist<list<int>>型のカラムcol4が含まれている場合は、最も外側の構造で両側の文字を省略できます。例を次に示します。
col1,col2,col3,col4
[1,2,3]|[1,2,3]|{"key1":1,"key2":2}|[[1,2,3],[4,5,6]]
以下のように簡素化できます。
col1,col2,col3,col4
1,2,3|1,2,3|"key1":1,"key2":2|[1,2,3],[4,5,6]
ただし、内側のリスト項目はこれ以上簡素化できません。

データ・アンロードの例

dsbulkを使用したデータ・アンロードの例

アンロードとは、DataStax EnterpriseからCSVまたはJSONファイルにデータを抽出するプロセスのことです。読み込みとアンロードの両方で使用されるオプションの多くは同じです。

localhostコンタクト・ポイントを指定して、クラスター内のks1.table1テーブルからstdoutにデータをアンロードします。テーブル内のカラム名は、データ内のフィールド名にマップされます。フィールド名は出力時にヘッダー行に生成されます。
dsbulk unload -k ks1 -t table1
ks1.table1テーブルからstdoutにデータをアンロードして、結果をgzip形式で圧縮します。
dsbulk unload -k ks1 -t table1 | gzip > table1.gz
ローカル・ディレクトリー(存在しない場合があります)にデータをアンロードします。
dsbulk unload -url ~/data-export -k ks1 -t table1

終了コード

dsbulk用の終了コード

dsbulkコマンドには、呼び出しプロセスに戻される終了コードがあります。以下の値は、返される整数値をステータスに関連付けます。
整数値 ステータス値
0 STATUS_OK
1 STATUS_COMPLETED_WITH_ERRORS
2 STATUS_ABORTED_TOO_MANY_ERRORS
3 STATUS_ABORTED_FATAL_ERROR
4 STATUS_INTERRUPTED
5 STATUS_CRASHED