add

概要
APIの形式
- HTTP
- REST
- Fluentd
パラメータの構文
使い方
パラメータの詳細
- table
- key
- values
レスポンス
エラーの種類

概要

add は、テーブルにレコードを登録します。対象のテーブルが主キーを持っており、同じキーのレコードが既に存在している場合には、既存レコードのカラムの値を更新します。

APIの形式

HTTP

リクエスト先: (ドキュメントルート)/droonga/add
リクエストメソッド: POST
リクエストのURLパラメータ: なし。
リクエストのbody: パラメータのハッシュ。
レスポンスのbody: レスポンスメッセージ。

REST

対応していません。

Fluentd

形式: Request-Response型。コマンドに対しては必ず対応するレスポンスが返されます。
リクエストの type: add
リクエストの body: パラメータのハッシュ。
レスポンスの type: add.result

パラメータの構文

対象のテーブルが主キーを持つ場合：

{
  "table"  : "<テーブル名>",
  "key"    : "<レコードの主キー>",
  "values" : {
    "<カラム1の名前>" : <値1>,
    "<カラム2の名前>" : <値2>,
    ...
  }
}

対象のテーブルが主キーを持たない場合：

{
  "table"  : "<テーブル名>",
  "values" : {
    "<カラム1の名前>" : <値1>,
    "<カラム2の名前>" : <値2>,
    ...
  }
}

使い方

本項の説明では以下のような2つのテーブルが存在している事を前提として、典型的な使い方を通じて add コマンドの使い方を説明します。

Personテーブル（主キー無し）:

name	job (Jobテーブルを参照)
Alice Arnold	announcer
Alice Cooper	musician

Jobテーブル（主キー有り）:

_key	label
announcer	announcer
musician	musician

主キーを持たないテーブルにレコードを追加する

主キーを持たないテーブルにレコードを追加する場合は、 key を指定せずに table と values だけを指定します。

{
  "type" : "add",
  "body" : {
    "table"  : "Person",
    "values" : {
      "name" : "Bob Dylan",
      "job"  : "musician"
    }
  }
}

=> {
     "type" : "add.result",
     "body" : true
   }

add は再帰的に動作します。別のテーブルを参照しているカラムについて、参照先のテーブルに存在しない値を指定した場合、エラーにはならず、参照先のテーブルにも同時に新しいレコードが追加されます。例えば、以下はテーブルに存在しない主キー doctor を伴って Person テーブルにレコードを追加します。

{
  "type" : "add",
  "body" : {
    "table"  : "Person",
    "values" : {
      "name" : "Alice Miller",
      "job"  : "doctor"
    }
  }
}

=> {
     "type" : "add.result",
     "body" : true
   }

この時、Jobテーブルには主キーだけが指定された新しいレコードが自動的に追加されます。

_key	label
announcer	announcer
musician	musician
doctor	(空文字)

主キーを持つテーブルにレコードを追加する

主キーを持つテーブルにレコードを追加する場合は、 table、key、values のすべてを指定します。

{
  "type" : "add",
  "body" : {
    "table"  : "Job",
    "key"    : "writer",
    "values" : {
      "label" : "writer"
    }
  }
}

=> {
     "type" : "add.result",
     "body" : true
   }

既存レコードのカラムの値を更新する

主キーを持つテーブルに対する、既存レコードの主キーを伴う add コマンドは、既存レコードのカラムの値の更新操作と見なされます。

{
  "type" : "add",
  "body" : {
    "table"  : "Job",
    "key"    : "doctor",
    "values" : {
      "label" : "doctor"
    }
  }
}

=> {
     "type" : "add.result",
     "body" : true
   }

主キーを持たないテーブルのレコードに対しては、値の更新操作はできません（常にレコードの追加と見なされます）。

パラメータの詳細

`table`

概要: レコードを登録するテーブルの名前を指定します。
値: テーブル名の文字列。
省略時の既定値: なし。このパラメータは必須です。

`key`

概要: レコードの主キーを指定します。
値: 主キーとなる文字列。
省略時の初期値: Nなし。対象のテーブルが主キーを持つ場合、このパラメータは必須です。主キーがない場合、このパラメータは無視されます。

既に同じ主キーを持つレコードが存在している場合は、レコードの各カラムの値を更新します。

対象のテーブルが主キーを持たない場合は、指定しても単に無視されます。

`values`

概要: レコードの各カラムの値を指定します。
値: カラム名をキー、カラムの値を値としたハッシュ。
省略時の初期値: null

指定されなかったカラムの値は登録・更新されません。

レスポンス

このコマンドは、レコードを正常に追加または更新できた場合、真偽値 true をbody 、200 を statusCode としたレスポンスを返します。以下はレスポンスの body の例です。

true

エラーの種類

このコマンドは一般的なエラーに加えて、以下のエラーを場合に応じて返します。

`MissingTableParameter`

table パラメータの指定を忘れていることを示します。ステータスコードは 400 です。

`MissingPrimaryKeyParameter`

主キーが存在するテーブルに対して、key パラメータの指定を忘れていることを示します。ステータスコードは 400 です。

`InvalidValue`

カラムに設定しようとした値が不正である（例：位置情報型や整数型のカラムに通常の文字列を指定した、など）事を示します。ステータスコードは 400 です。

`UnknownTable`

指定されたデータセット内に、指定されたレコードが存在していない事を示します。ステータスコードは 404 です。

`UnknownColumn`

指定されたカラムがテーブルに存在しない未知のカラムである事を示します。ステータスコードは 400 です。