7.3.24. load

7.3.24.1. 概要

load は、使用しているデータベースのテーブルにレコードを登録し、カラムの値を更新します。

7.3.24.2. 構文

必須の引数は valuestable だけです。残りは省略できます。:

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.24.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.24.4. 引数

このセクションではすべての引数について説明します。引数はカテゴリわけしています。

7.3.24.4.1. 必須引数

いくつか必須の引数があります。

7.3.24.4.1.1. values

ロードする値を指定します。

ロードする値は input_type フォーマットになっていないといけません。 input_typejson を指定した場合は次のいずれかのフォーマットにします。

角括弧スタイル:

[
[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 (主キーを示す疑似カラム名)にしなければいけません。

values を指定していない場合、コマンドラインスタイルのときは標準入力から読み込んだ値を使い、HTTPスタイルのときはボディの値を使います。

7.3.24.4.1.2. table

レコードを追加しようとするテーブルの名前を指定します。

7.3.24.4.2. 省略可能引数

いくつか省略可能な引数があります。

7.3.24.4.2.1. columns

テーブルに登録するレコードに値を設定するカラム名のリストを、カンマ区切りで指定します。

7.3.24.4.2.2. ifexists

追加する主キーのレコードがすでにテーブル中に存在するときに実行する式を スクリプト構文 で指定します。

ifexists に式を指定し、その式の評価結果が true のときは、他のカラム( _key カラム以外のすべてのカラム)の値をすべて更新します。

7.3.24.4.2.3. input_type

values の入力フォーマットを指定します。現在のところ json のみサポートしています。つまり、 values のフォーマットはJSONでなければいけません。

デフォルト値は json です。

7.3.24.4.2.4. each

TODO

7.3.24.4.2.5. output_ids

TODO

7.3.24.4.2.6. output_errors

TODO

7.3.24.4.2.7. lock_table

バージョン 8.0.6 で追加.

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

デフォルト値は no です。

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

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

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

  1. 更新対象のテーブルをロックする
  2. 更新対象のテーブルにレコードを追加する、あるいは、レコードを参照する
  3. 更新対象のテーブルのロックを解除する
  4. lock_tableyes の場合は更新対象のテーブルをロックする
  5. 対象レコードのカラムを更新する
  6. lock_tableyes の場合は更新対象のテーブルのロックを解除する

7.3.24.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_idsyes のときだけ loaded_ids を含みます。

output_errorsyes のときだけ errors を含みます。

7.3.24.6. 参考