add

概要

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 を指定せずに tablevalues だけを指定します。

{
  "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 (空文字)

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

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

{
  "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

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

レスポンス

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

true

エラーの種類

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

MissingTableParameter

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

MissingPrimaryKeyParameter

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

InvalidValue

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

UnknownTable

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

UnknownColumn

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