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 の値は以下の通りです。

型

Content-Type

説明

json

application/json

JSONフォーマットで values を指定するときに使います。

これがデフォルトです。

apache-arrow

application/x-apache-arrow-streaming

Added in version 9.1.1.

Apache Arrowフォーマットで values を指定するときに使います。

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#

Added in version 8.0.6.

カラム更新中にテーブルをロックするかどうかを指定します。

デフォルト値は no です。

もし、 load や delete などといった破壊的な変更をするコマンドを同時に実行すると、データベースが壊れる可能性があります。たとえば、 load でレコードを更新中にそのレコードを delete で削除すると load は削除されたレコードを参照してしまうかもしれません。

更新対象のテーブルをロックすることで更新の衝突を防ぐことができますが、書き込み性能は下がります。

このパラメーターに yes を指定するとカラム更新中は更新対象のテーブルをロックします。それぞれのレコードの更新手順は次のようになります。

  1. 更新対象のテーブルをロックする

  2. 更新対象のテーブルにレコードを追加する、あるいは、レコードを参照する

  3. 更新対象のテーブルのロックを解除する

  4. lock_table が yes の場合は更新対象のテーブルをロックする

  5. 対象レコードのカラムを更新する

  6. 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 を含みます。

7.3.26.6. 参考#