INSERT文

INSERT文は、新しい行を作成して、指定した表に追加するために使用します。

構文

insert_statement ::= 
   [variable_declaration] 
   (INSERT | UPSERT) INTO table_name 
   [[AS] table_alias]
   ["(" id ("," id)* ")"] 
   VALUES "(" insert_clause ("," insert_clause)* ")"
   [SET TTL ttl_clause] 
   [returning_clause]

insert_clause ::= DEFAULT | expression

returning_clause ::= RETURNING select_list

セマンティクス

INSERTキーワードが使用されている場合、行は存在していない場合にのみ挿入されます。UPSERTキーワードが使用されている場合、行はすでに存在しない場合に挿入され、そうでない場合は新しい行によって既存の行が置き換えられます。

Insert文は、その文の残りの部分で使用される外部変数の宣言から開始できます。変数の宣言を参照してください。ただし、問合せとは異なり、外部変数は宣言せずに挿入で使用できます。これは、問合せの最適化が行われないため、挿入ではデータの問合せを行わず、外部変数のタイプを事前に知ることは重要ではないためです。

表名の後にオプションの列を指定できます。このリストには、表の列のサブセットの列名が含まれます。このサブセットには、すべての主キー列が含まれている必要があります。列リストが存在しない場合、デフォルトの列リストは、表のすべての列がCREATE TABLE文の項で指定された順序で含まれる列リストです。

列リストの列は、VALUES句の後にリストされた式(またはDEFAULTキーワード)に1対1で対応します(式/DEFAULTの数が列数と一致しない場合はエラーが発生します)。これらの式/DEFAULTによって、新しい行の関連する列の値が計算されます。具体的には、各式が評価され、その戻り値が関連する列のタイプにキャストされます。CASTは、CAST式の項の説明に従ってCAST式のように動作します。式が複数の項目を返す場合は、エラーが発生します。式で結果が返されない場合は、NULLがその式の結果として使用されます。式ではなく、DEFAULTキーワードがVALUESリストに表示される場合は、関連付けられた列のデフォルト値が、新しい行のその列の値として使用されます。デフォルト値は、列リストの列の数が表の列の合計数より少ない場合、欠落している列にも使用されます。

VALUESリストの式は、問合せ文とは異なり、外部変数を参照する場合があります。宣言セクションで宣言する必要はありません。

VALUESリストの後に、SET TTL句を使用して新しい行の有効期限を設定したり、UPSERTの場合は既存の行の有効期限を更新できます。CREATE TABLE文の項で説明しているように、すべての行に有効期限があります。有効期限は無限の場合があり、存続時間(TTL)の値を日数または時間数で指定したものとして計算されます。具体的には、N時間/日のTTL値で、Nが0より大きい場合、有効期限は現在の時間(UTC)にN時間/日を加えた時間として計算され、次の満時間/日に丸められます。たとえば、現在の時間が2017-06-01T10:05:30.0でNが3時間の場合、有効期限は2017-06-01T14:00:00.0になります。Nが0の場合、有効期限は無限です。

構文に示すように、SET TTL句には2つのフレーバがあります。USING TABLE DEFAULT構文を使用すると、TTL値は、CREATE TABLE文で指定した表のデフォルトのTTLに設定されます。それ以外の場合は、新しいTTL値を計算する式がSET TTLに含まれます。この式の結果が空の場合、表のデフォルトのTTLが使用されます。それ以外の場合、式は整数Nにキャストする単一の数値項目を返す必要があります。Nが負の場合は、0に設定されます。TTL式の右側で、キーワードHOURSまたはDAYSを使用してNが時間数と日数のどちらであるかを指定する必要があります。

挿入文にSET TTL句が含まれる場合は、前述の説明に従って有効期限が計算され、挿入または更新された行の有効期限になります。SET TTL句が使用されない場合、デフォルトの表のTTLを使用して挿入された行の有効期限が計算されますが、更新された行の有効期限は更新されません。

挿入文の最後の部分はRETURNING句です。存在しない場合、更新文の結果は、NumRowsInsertedという名前で、その値が挿入された行数(行がすでに存在する場合は0、それ以外の場合は1)である1つのフィールドを含むレコードです。それ以外の場合、RETURNING句は、SELECT句と同じように機能します。その場合、"*"を指定することもでき、行全体が返されます。または、返す必要がある内容を指定する式のリストを含めることができます。挿入が実際に行われない(行がすでに存在するため) INSERTの場合、RETURNING句は既存の行に影響を与えます。それ以外の場合、RETURNING句は新しい行に影響を与えます。

例7-1 行の挿入

次の文は、CREATE TABLE文からusers表に行を挿入します。DEFAULT句がexpenses列に使用されているため、この列の値はNULLに設定されます。

INSERT INTO users VALUES (
    10,
    "John",
    "Smith",
    [ {"first" : "Johny", "last" : "BeGood"} ],
    22,
    45000,
    { "street" : "Main", "number" : 10, "city" : "Reno", "state" : "NV"},
    [ 30, 55, 43 ],
    DEFAULT
);

INSERT INTO users VALUES (
    20,
    "Mary",
    "Ann",
    null,
    43,
    90000,
    { "street" : "Main", "number" : 89, "city" : "San Jose", "state" : "CA"},
    null,
    DEFAULT
);

INSERT INTO users VALUES (
    30,
    "Peter",
    "Paul",
    null,
    25,
    53000,
    { "street" : "Main", "number" : 3, "city" : "Fresno", "state" : "CA"},
    null,
    DEFAULT
);