[ WITH [ RECURSIVE ] with_query [, ...] ] 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権限を持っている必要があります。
WITH句により、INSERT問い合わせ内で名前により参照することができる1つ以上の副問い合わせを指定することができます。 項7.8とSELECTを参照してください。
query(SELECT文)ではまた、WITH句を含めることができます。 こうした場合、with_queryの集合との両方をquery内で参照することができます。 しかしより綿密に入れ子にされますので、第二の問い合わせは述語を取ります。
既存のテーブルの名前です(スキーマ修飾名も可)。
table内の列名です。 列名を副フィールドの名前や配列の添え字で修飾することができます。 (複合型の列の一部のフィールドのみを挿入しても他のフィールドはNULLのままです。)
全ての列に、それぞれのデフォルト値が設定されます。
対応するcolumnに代入する有効な式または値を指定します。
対応するcolumnに、デフォルト値を設定します。
挿入する行を提供する問い合わせ(SELECT文)を指定します。 構文の説明についてはSELECT文を参照してください。
各行が挿入された後、計算されINSERTにより返される式です。 この式にはtableの任意の列名を使用することができます。 挿入された行のすべての列を返す場合は*と記載してください。
返される列で使用される名前です。
正常に終了すると、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;
Acme社の顧客を担当する営業担当者の売り上げ数を増やし、ログテーブルに更新行全体と更新時刻を記録します。
WITH upd AS ( UPDATE employees SET sales_count = sales_count + 1 WHERE id = (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation') RETURNING * ) INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
INSERTは標準SQLに準拠します。 ただし、RETURNING句とINSERTでWITHが可能であることはPostgreSQLの拡張です。 また、標準SQLでは、列名リストが省略された時に、VALUES句またはqueryで一部の列のみを指定することはできません。
制限される可能性があるquery句の機能については、SELECTにて記述されています。