7.3.26. load
#
7.3.26.1. 概要#
load
は、使用しているデータベースのテーブルにレコードを登録し、カラムの値を更新します。
7.3.26.2. 構文#
必須の引数は values
と table
だけです。残りは省略できます。:
load values
table
[columns=null]
[ifexists=null]
[input_type=json]
[each=null]
[output_ids=no]
[output_errors=no]
[lock_table=no]
このコマンドは特別なコマンドです。他のコマンドはすべてのパラメーターを1行で指定する必要がありますが、このコマンドは values
の値を別途指定することもできます。
コマンドラインスタイルを使っている場合は次のように values
の値を指定できます。:
load --table Bookmarks
[
{"_key": "http://groonga.org/", "title": "Groonga"},
{"_key": "http://mroonga.org/", "title": "Mroonga"}
]
[...]
は values
の値です。
HTTPスタイルを使っている場合はボディに values
を指定できます。
% curl \
--request POST \
--header "Content-Type: application/json" \
--data-raw '[{"_key": "http://groonga.org/"}]' \
http://localhost:10041/d/load?table=Bookmarks"
7.3.26.3. 使い方#
使い方を示すために使うスキーマ定義は以下の通りです。
実行例:
table_create Entries TABLE_HASH_KEY ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Entries content COLUMN_SCALAR Text
# [[0,1337566253.89858,0.000355720520019531],true]
パラメーター指定で Entries
テーブルにレコードを追加する例です。
実行例:
load \
--table Entries \
--values "[{\"_key\":\"Groonga\",\"content\":\"It's very fast!!\"}]"
# [[0,1337566253.89858,0.000355720520019531],1]
標準入力のデータを使って Entries
テーブルにレコードを追加する例です。
実行例:
load --table Entries
[
{"_key": "Groonga", "content": "It's very fast!!"}
]
# [[0,1337566253.89858,0.000355720520019531],1]
カラム更新中にテーブルをロックする例です。
実行例:
load --table Entries --lock_table yes
[
{"_key": "Groonga", "content": "It's very fast!!"}
]
# [[0,1337566253.89858,0.000355720520019531],1]
7.3.26.4. 引数#
このセクションではすべての引数について説明します。引数はカテゴリわけしています。
7.3.26.4.1. 必須引数#
いくつか必須の引数があります。
7.3.26.4.1.1. values
#
ロードする値を指定します。
ロードする値は input_type
フォーマットになっていないといけません。 input_type
に json
を指定した場合は次のいずれかのフォーマットにします。
角括弧スタイル:
[
[COLUMN_NAME1, COLUMN_NAME2, ...],
[VALUE1, VALUE2, ...],
[VALUE1, VALUE2, ...],
...
]
波括弧スタイル:
[
{"COLUMN_NAME1": VALUE1, "COLUMN_NAME2": VALUE2, ...},
{"COLUMN_NAME1": VALUE1, "COLUMN_NAME2": VALUE2, ...},
...
]
角括弧スタイルの [COLUMN_NAME1, COLUMN_NAME2, ...]
は columns パラメーターを指定していないときだけ有効です。
対象のテーブルが主キーを持つテーブルであった場合は、カラム名のどれかを _key
(主キーを示す疑似カラム名)にしなければいけません。
input_type
に apache-arrow
を指定した場合は Apache Arrow IPC Streaming Format を使わなければいけません。 Apache Arrow IPC File Format は使えません。
Apache Arrowを使うにはHTTPインターフェイスを使わないといけません。コマンドラインインターフェイスではApache Arrowを使えません。
HTTPリクエストヘッダーの Content-Type
に application/x-apache-arrow-streaming
を指定しなければいけません。
適切なレコードバッチサイズを選ばないといけません。Groongaはレコードバッチごとにデータをロードします。もし、とても大きいレコードバッチサイズを選んだら、Groongaは各レコードバッチのすべてのデータを受信するまでロードしはじめることができません。もし、とても小さいレコードバッチサイズを選ぶと、Groongaは随時データをロードできますがオーバーヘッドが大きいでしょう。適切なレコードバッチサイズはシステムによりますが、1024あたりが適切でしょう。
values
を指定していない場合、コマンドラインスタイルのときは標準入力から読み込んだ値を使い、HTTPスタイルのときはボディの値を使います。
7.3.26.4.1.2. table
#
レコードを追加しようとするテーブルの名前を指定します。
7.3.26.4.2. 省略可能引数#
いくつか省略可能な引数があります。
7.3.26.4.2.1. columns
#
テーブルに登録するレコードに値を設定するカラム名のリストを、カンマ区切りで指定します。
7.3.26.4.2.2. ifexists
#
追加する主キーのレコードがすでにテーブル中に存在するときに実行する式を スクリプト構文 で指定します。
ifexists
に式を指定し、その式の評価結果が true
のときは、他のカラム( _key
カラム以外のすべてのカラム)の値をすべて更新します。
7.3.26.4.2.3. input_type
#
values
のフォーマットを指定します。
HTTP POSTで input_type
を使うときは適切なHTTP Content-Type
ヘッダーの値も指定しなければいけないことに注意してください。
指定可能な型と Content-Type
の値は以下の通りです。
型 |
|
説明 |
---|---|---|
|
|
JSONフォーマットで これがデフォルトです。 |
|
|
バージョン 9.1.1 で追加. Apache Arrowフォーマットで |
7.3.26.4.2.4. each
#
TODO
7.3.26.4.2.5. output_ids
#
TODO
7.3.26.4.2.6. output_errors
#
TODO
7.3.26.4.2.7. lock_table
#
バージョン 8.0.6 で追加.
カラム更新中にテーブルをロックするかどうかを指定します。
デフォルト値は no
です。
もし、 load
や delete
などといった破壊的な変更をするコマンドを同時に実行すると、データベースが壊れる可能性があります。たとえば、 load
でレコードを更新中にそのレコードを delete
で削除すると load
は削除されたレコードを参照してしまうかもしれません。
更新対象のテーブルをロックすることで更新の衝突を防ぐことができますが、書き込み性能は下がります。
このパラメーターに yes
を指定するとカラム更新中は更新対象のテーブルをロックします。それぞれのレコードの更新手順は次のようになります。
更新対象のテーブルをロックする
更新対象のテーブルにレコードを追加する、あるいは、レコードを参照する
更新対象のテーブルのロックを解除する
lock_table
がyes
の場合は更新対象のテーブルをロックする対象レコードのカラムを更新する
lock_table
がyes
の場合は更新対象のテーブルのロックを解除する
7.3.26.5. 戻り値#
このコマンドは以下のフォーマットのレスポンスを返します。:
[THE_NUMBER_OF_LOADED_RECORDS]
このコマンドは コマンドバージョン 3以降のときは以下のフォーマットのレスポンスを返します。:
{
"n_loaded_records": THE_NUMBER_OF_LOADED_RECORDS,
"loaded_ids": [
LOADED_RECORD'S_ID1,
LOADED_RECORD'S_ID2,
...
],
"errors": [
{
"return_code": RETURN_CODE_FOR_1ST_RECORD,
"message": MESSAGE_FOR_1ST_RECORD
},
{
"return_code": RETURN_CODE_FOR_2ND_RECORD,
"message": MESSAGE_FOR_2ND_RECORD
},
...
]
}
output_ids が yes
のときだけ loaded_ids
を含みます。
output_errors が yes
のときだけ errors
を含みます。