本文へスキップ
`Ctrl`+`K`

# 7.3.27. `load`

## 7.3.27.1. 概要

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

## 7.3.27.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.27.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.27.4. 引数

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

### 7.3.27.4.1. 必須引数

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

#### 7.3.27.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.27.4.1.2. `table`

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

### 7.3.27.4.2. 省略可能引数

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

#### 7.3.27.4.2.1. `columns`

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

#### 7.3.27.4.2.2. `ifexists`

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

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

#### 7.3.27.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.27.4.2.4. `each`

TODO

#### 7.3.27.4.2.5. `output_ids`

TODO

#### 7.3.27.4.2.6. `output_errors`

TODO

#### 7.3.27.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.27.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.27.6. 参考

> - スクリプト構文