INSERT(7)

NAME
INSERT - テーブルに新しい行を作成する

SYNOPSIS

INSERT INTO table [ ( column [, ...] ) ]
    { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }
    [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]

説明

INSERTはテーブルに新しい行を挿入します。 値式を使用して行（複数可）を挿入するだけでなく、問い合わせの結果を使って0行以上の行を挿入することもできます。

対象の列名はどのような順番でも指定できます。 列名リストが指定されなかった場合は、宣言時の順番に並べたテーブル内の全ての列がデフォルトとなります。 また、VALUES句やqueryでN列のみが指定された場合は、先頭のN列の名前がデフォルトとなります。 VALUES句やqueryで提供される値は、明示的または暗黙的な列リストと左から右への順で関連付けられます

明示的または暗黙的な列リストにない各列にはデフォルト値（デフォルト値が宣言されていればその値、未宣言ならばNULL）が挿入されます。

各列の式が正しいデータ型でない場合は、自動的に型の変換が行われます。

省略可能なRETURNING句により、INSERTは実際に挿入された各行に基づいて計算された値を返すようになります。 これは、通番のシーケンス番号など、デフォルトで与えられた値を取り出す時にかなり便利です。 しかし、そのテーブルの列を使用した式を指定することができます。 RETURNINGリストの構文はSELECTの出力リストと同一です。

テーブルに行を追加するには、そのテーブルに対してINSERT権限を持っている必要があります。 列リストが指定された場合は、列挙された列に対するINSERT権限のみが必要です。 RETURNING句を使用するには、RETURNINGで使用するすべての列に対するSELECT権限が必要です。 queryを使用して問い合わせ結果を元に行を挿入する場合は当然ながら、その問い合わせ内で使われる全てのテーブルまたは列に対してSELECT権限を持っている必要があります。

パラメータ

table
    既存のテーブルの名前です（スキーマ修飾名も可）。

column
    table内の列名です。

DEFAULT VALUES
    全ての列に、それぞれのデフォルト値が設定されます。

expression
    対応するcolumnに代入する有効な式または値を指定します。

DEFAULT
    対応するcolumnに、デフォルト値を設定します。

query
    挿入する行を提供する問い合わせ（SELECT文）を指定します。 構文の説明についてはSELECT [select(7)]文を参照してください。

output_expression
    各行が挿入された後、計算されINSERTにより返される式です。 この式にはtableの任意の列名を使用することができます。 挿入された行のすべての列を返す場合は*と記載してください。

output_name
    返される列で使用される名前です。

出力

正常に終了すると、INSERTは以下のようなコマンドタグを返します。

INSERT oid count

countは挿入された行数です。 countが正確に1であり、対象のテーブルがOIDを持つ場合、oidは挿入された行に割り当てられたOIDです。 その他の場合、oidは0となります。

INSERTコマンドがRETURNING句を持つ場合、その結果は、RETURNINGリストで定義した列と値を持ち、そのコマンドで挿入された行全体に対して計算を行うSELECT文の結果と似たものになるでしょう。

例

filmsテーブルに1行を挿入します。

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');

この例では、len列を省略しています。 したがって、ここにはデフォルト値NULLが入ります。

INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

3つ目の例では、日付列に対して値ではなくDEFAULTを使用します。

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

全てデフォルト値からなる行を挿入します。

INSERT INTO films DEFAULT VALUES;

複数行のVALUES構文を使用して複数行を挿入します。

INSERT INTO films (code, title, did, date_prod, kind) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');

この例では、filmsテーブルと同じ列レイアウトを持つtmp_filmsテーブルからfilmsテーブルへいくつか行を挿入します。

INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';

この例では、配列型の列に挿入しています。

-- 三目並べ用の3×3マスのゲーム盤を作成します。
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
--上の例の添え字は本当は必要ありません。
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

distributorsテーブルに単一行を挿入し、そのDEFAULT句により生成されたシーケンス番号を返します。

INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;

互換性

INSERTは標準SQLに準拠します。 ただし、RETURNING句はPostgreSQLの拡張です。 また、標準SQLでは、列名リストが省略された時に、VALUES句またはqueryで一部の列のみを指定することはできません。

制限される可能性があるquery句の機能については、SELECT [select(7)]にて記述されています。