.\\" auto-generated by docbook2man-spec $Revision: 1.2 $
.TH "INSERT" "" "2007-05-04" "SQL - 言語" "SQLコマンド"
.SH NAME
INSERT \- テーブルに新しい行を作成する

.SH SYNOPSIS
.sp
.nf
INSERT INTO \fItable\fR [ ( \fIcolumn\fR [, ...] ) ]
    { DEFAULT VALUES | VALUES ( { \fIexpression\fR | DEFAULT } [, ...] ) [, ...] | \fIquery\fR }
    [ RETURNING * | \fIoutput_expression\fR [ AS \fIoutput_name\fR ] [, ...] ]
.sp
.fi
.SH "説明"
.PP
\fBINSERT\fRはテーブルに新しい行を挿入します。
値式を使用して行（複数可）を挿入するだけでなく、問い合わせの結果を使って0行以上の行を挿入することもできます。
.PP
対象の列名はどのような順番でも指定できます。
列名リストが指定されなかった場合は、宣言時の順番に並べたテーブル内の全ての列がデフォルトとなります。
また、VALUES句や\fIquery\fRで\fIN\fR列のみが指定された場合は、先頭の\fIN\fR列の名前がデフォルトとなります。
VALUES句や\fIquery\fRで提供される値は、明示的または暗黙的な列リストと左から右への順で関連付けられます
.PP
明示的または暗黙的な列リストにない各列にはデフォルト値（デフォルト値が宣言されていればその値、未宣言ならばNULL）が挿入されます。
.PP
各列の式が正しいデータ型でない場合は、自動的に型の変換が行われます。
.PP
省略可能なRETURNING句により、\fBINSERT\fRは実際に挿入された各行に基づいて計算された値を返すようになります。
これは、通番のシーケンス番号など、デフォルトで与えられた値を取り出す時にかなり便利です。
しかし、そのテーブルの列を使用した式を指定することができます。
RETURNINGリストの構文は\fBSELECT\fRの出力リストと同一です。
.PP
テーブルに行を追加するには、そのテーブルに対してINSERT権限を持っている必要があります。 
また、RETURNINGを使用するには、SELECT権限が必要です。
\fIquery\fRを使用して問い合わせ結果を元に行を挿入する場合は、その問い合わせ内で使われる全てのテーブルに対してSELECT権限を持っている必要があります。
.SH "パラメータ"
.TP
\fB\fItable\fB\fR
既存のテーブルの名前です（スキーマ修飾名も可）。
.TP
\fB\fIcolumn\fB\fR
\fItable\fR内の列名です。
.TP
\fBDEFAULT VALUES\fR
全ての列に、それぞれのデフォルト値が設定されます。
.TP
\fB\fIexpression\fB\fR
対応する\fIcolumn\fRに代入する有効な式または値を指定します。
.TP
\fBDEFAULT\fR
対応する\fIcolumn\fRに、デフォルト値を設定します。
.TP
\fB\fIquery\fB\fR
挿入する行を提供する問い合わせ（\fBSELECT\fR文）を指定します。
構文の説明についてはSELECT [\fBselect\fR(l)]文を参照してください。
.TP
\fB\fIoutput_expression\fB\fR
各行が挿入された後、計算され\fBINSERT\fRにより返される式です。
この式には\fItable\fRの任意の列名を使用することができます。
挿入された行のすべての列を返す場合は*と記載してください。
.TP
\fB\fIoutput_name\fB\fR
返される列で使用される名前です。
.SH "出力"
.PP
正常に終了すると、\fBINSERT\fRは以下のようなコマンドタグを返します。
.sp
.nf
INSERT \fIoid\fR \fIcount\fR
.sp
.fi
\fIcount\fRは挿入された行数です。
\fIcount\fRが正確に1であり、対象のテーブルがOIDを持つ場合、\fIoid\fRは挿入された行に割り当てられたOIDです。
その他の場合、\fIoid\fRは0となります。
.PP
\fBINSERT\fRコマンドがRETURNING句を持つ場合、その結果は、RETURNINGリストで定義した列と値を持ち、そのコマンドで挿入された行全体に対して計算を行う\fBSELECT\fR文の結果と似たものになるでしょう。
.SH "例"
.PP
filmsテーブルに1行を挿入します。
.sp
.nf
INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');
.sp
.fi
.PP
この例では、len列を省略しています。 
したがって、ここにはデフォルト値NULLが入ります。
.sp
.nf
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
.sp
.fi
.PP
3つ目の例では、日付列に対して値ではなくDEFAULTを使用します。
.sp
.nf
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');
.sp
.fi
.PP
全てデフォルト値からなる行を挿入します。
.sp
.nf
INSERT INTO films DEFAULT VALUES;
.sp
.fi
.PP
複数行の\fBVALUES\fR構文を使用して複数行を挿入します。
.sp
.nf
INSERT INTO films (code, title, did, date_prod, kind) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');
.sp
.fi
.PP
この例では、filmsテーブルと同じ列レイアウトを持つtmp_filmsテーブルからfilmsテーブルへいくつか行を挿入します。
.sp
.nf
INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';
.sp
.fi
.PP
この例では、配列型の列に挿入しています。
.sp
.nf
-- 三目並べ用の3×3マスのゲーム盤を作成します。
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
--上の例の添え字は本当は必要ありません。
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');
.sp
.fi
.PP
distributorsテーブルに単一行を挿入し、そのDEFAULT句により生成されたシーケンス番号を返します。
.sp
.nf
INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;
.sp
.fi
.SH "互換性"
.PP
\fBINSERT\fRは標準SQLに準拠します。
ただし、RETURNING句はPostgreSQLの拡張です。
また、標準SQLでは、列名リストが省略された時に、VALUES句または\fIquery\fRで一部の列のみを指定することはできません。
.PP
制限される可能性がある\fIquery\fR句の機能については、SELECT [\fBselect\fR(l)]にて記述されています。
