説明

<command>INSERT</command> inserts new rows into a table. One can insert one or more rows specified by value expressions, or zero or more rows resulting from a query. INSERTはテーブルに新しい行を挿入します。 値式を使用して行（複数可）を挿入すること、および、問い合わせの結果を使って0行以上の行を挿入することができます。

The target column names can be listed in any order. If no list of column names is given at all, the default is all the columns of the table in their declared order; or the first <replaceable>N</replaceable> column names, if there are only <replaceable>N</replaceable> columns supplied by the <literal>VALUES</literal> clause or <replaceable>query</replaceable>. The values supplied by the <literal>VALUES</literal> clause or <replaceable>query</replaceable> are associated with the explicit or implicit column list left-to-right. 対象の列名はどのような順番でも指定できます。 列名リストが指定されなかった場合は、テーブル内の全ての列を宣言時の順番に並べたものがデフォルトとして使われます。 また、VALUES句やqueryでN列のみが与えられた場合は、先頭のN列の名前が指定されたものとみなされます。 VALUES句やqueryで提供される値は、明示的または暗黙的な列リストと左から右への順で関連付けられます。

Each column not present in the explicit or implicit column list will be filled with a default value, either its declared default value or null if there is none. 明示的または暗黙的な列リストにない各列にはデフォルト値（デフォルト値が宣言されていればその値、未宣言ならばNULL）が挿入されます。

If the expression for any column is not of the correct data type, automatic type conversion will be attempted. 各列の式が正しいデータ型でない場合は、自動的に型の変換が行われます。

<command>INSERT</command> into tables that lack unique indexes will not be blocked by concurrent activity. Tables with unique indexes might block if concurrent sessions perform actions that lock or modify rows matching the unique index values being inserted; the details are covered in <xref linkend="index-unique-checks"/>. <literal>ON CONFLICT</literal> can be used to specify an alternative action to raising a unique constraint or exclusion constraint violation error. (See <xref linkend="sql-on-conflict"/> below.) 一意インデックスのないテーブルへのINSERTは同時実行中の処理によりブロックされることはありません。 挿入される一意インデックスの値と一致する行をロックまたは修正する動作を同時実行中のセッションがしている場合には、一意インデックスのあるテーブルはブロックします。詳細は62.5で扱っています。 ON CONFLICTは一意制約または排他制約について、違反のエラーを発生させるのに代わる動作を指定するのに使うことができます。 （以下のON CONFLICT句を参照してください。）

The optional <literal>RETURNING</literal> clause causes <command>INSERT</command> to compute and return value(s) based on each row actually inserted (or updated, if an <literal>ON CONFLICT DO UPDATE</literal> clause was used). This is primarily useful for obtaining values that were supplied by defaults, such as a serial sequence number. However, any expression using the table's columns is allowed. The syntax of the <literal>RETURNING</literal> list is identical to that of the output list of <command>SELECT</command>. Only rows that were successfully inserted or updated will be returned. For example, if a row was locked but not updated because an <literal>ON CONFLICT DO UPDATE ... WHERE</literal> clause <replaceable class="parameter">condition</replaceable> was not satisfied, the row will not be returned. RETURNING句を指定すると、INSERTは実際に挿入された（あるいはON CONFLICT DO UPDATE句によって更新された）各行に基づいて計算された値を返すようになります。 これは、通番のシーケンス番号など、デフォルトで与えられた値を取り出す時に主に便利です。 しかし、そのテーブルの列を使用した任意の式を指定することができます。 RETURNINGリストの構文はSELECTの出力リストと同一です。 挿入または更新に成功した行だけが返されます。 例えば、行がロックされていて、ON CONFLICT DO UPDATE ... WHERE句の conditionが満たされなかったために更新されなかった行は返されません。

You must have <literal>INSERT</literal> privilege on a table in order to insert into it. If <literal>ON CONFLICT DO UPDATE</literal> is present, <literal>UPDATE</literal> privilege on the table is also required. テーブルに行を追加するには、そのテーブルに対してINSERT権限を持っている必要があります。 ON CONFLICT DO UPDATEがある場合は、テーブルのUPDATE権限も必要です。

If a column list is specified, you only need <literal>INSERT</literal> privilege on the listed columns. Similarly, when <literal>ON CONFLICT DO UPDATE</literal> is specified, you only need <literal>UPDATE</literal> privilege on the column(s) that are listed to be updated. However, <literal>ON CONFLICT DO UPDATE</literal> also requires <literal>SELECT</literal> privilege on any column whose values are read in the <literal>ON CONFLICT DO UPDATE</literal> expressions or <replaceable>condition</replaceable>. 列リストを指定する場合は、列挙された列に対するINSERT権限のみが必要です。 同様に、ON CONFLICT DO UPDATEが指定されている場合、更新対象として列挙されている列についてのみ、UPDATE権限が必要です。 しかし、ON CONFLICT DO UPDATEは、値がON CONFLICT DO UPDATE式あるいはconditionで読み取られるすべての列についてSELECT権限も必要です。

Use of the <literal>RETURNING</literal> clause requires <literal>SELECT</literal> privilege on all columns mentioned in <literal>RETURNING</literal>. If you use the <replaceable class="parameter">query</replaceable> clause to insert rows from a query, you of course need to have <literal>SELECT</literal> privilege on any table or column used in the query. RETURNING句を使用するには、RETURNINGで使用するすべての列に対するSELECT権限が必要です。 queryを使用して問い合わせ結果を元に行を挿入する場合は当然ながら、その問い合わせ内で使われる全てのテーブルまたは列に対してSELECT権限を持っている必要があります。

パラメータ

出力

On successful completion, an <command>INSERT</command> command returns a command tag of the form 正常に終了すると、INSERTは以下のようなコマンドタグを返します。

INSERT oid count

The <replaceable class="parameter">count</replaceable> is the number of rows inserted or updated. <replaceable>oid</replaceable> is always 0 (it used to be the <acronym>OID</acronym> assigned to the inserted row if <replaceable>count</replaceable> was exactly one and the target table was declared <literal>WITH OIDS</literal> and 0 otherwise, but creating a table <literal>WITH OIDS</literal> is not supported anymore). countは挿入または更新された行数です。 oidは常に0です(countが正確に1であり、対象のテーブルがWITH OIDSと宣言されていた場合、挿入された行にOIDが、そうでなければ0が割り当てられていましたが、WITH OIDSでテーブルを作成することは今はもうサポートされていません)。

If the <command>INSERT</command> command contains a <literal>RETURNING</literal> clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the <literal>RETURNING</literal> list, computed over the row(s) inserted or updated by the command. INSERTコマンドがRETURNING句を持つ場合、その結果は、RETURNINGリストで定義した列と値を持ち、そのコマンドで挿入または更新された行全体に対して計算を行うSELECT文の結果と似たものになるでしょう。

注釈

If the specified table is a partitioned table, each row is routed to the appropriate partition and inserted into it. If the specified table is a partition, an error will occur if one of the input rows violates the partition constraint. 指定したテーブルがパーティションテーブルの場合、各行は適切なパーティションに回され、そちらに挿入されます。 指定したテーブルがパーティションの場合、挿入行にパーティションの制約に違反するものがあれば、エラーが発生します。

You may also wish to consider using <command>MERGE</command>, since that allows mixing <command>INSERT</command>, <command>UPDATE</command>, and <command>DELETE</command> within a single statement. See <xref linkend="sql-merge"/>. MERGEを使用すると、単一の文内でINSERT、UPDATE、DELETEを混在させることができます。 MERGEを参照してください。

例

Insert a single row into table <literal>films</literal>: filmsテーブルに1行を挿入します。

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

In this example, the <literal>len</literal> column is omitted and therefore it will have the default value: 次の例では、len列を省略しています。 したがって、ここにはデフォルト値が入ります。

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

This example uses the <literal>DEFAULT</literal> clause for the date columns rather than specifying a value: 次の例では、日付列に対して値を指定する代わりに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');

To insert a row consisting entirely of default values: 全てデフォルト値からなる行を挿入します。

INSERT INTO films DEFAULT VALUES;

To insert multiple rows using the multirow <command>VALUES</command> syntax: 複数行の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');

This example inserts some rows into table <literal>films</literal> from a table <literal>tmp_films</literal> with the same column layout as <literal>films</literal>: 次の例では、filmsテーブルと同じ列レイアウトを持つtmp_filmsテーブルからfilmsテーブルへいくつか行を挿入します。

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

This example inserts into array columns: 次の例では、配列型の列に挿入します。

-- Create an empty 3x3 gameboard for noughts-and-crosses

-- 三目並べ用の3×3マスのゲーム盤を作成します。
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');

-- The subscripts in the above example aren't really needed

--上の例の添え字は本当は必要ありません。
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

Insert a single row into table <literal>distributors</literal>, returning the sequence number generated by the <literal>DEFAULT</literal> clause: distributorsテーブルに一行を挿入し、そのDEFAULT句により生成されたシーケンス番号を返します。

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

Increment the sales count of the salesperson who manages the account for Acme Corporation, and record the whole updated row along with current time in a log table: 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 or update new distributors as appropriate. Assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column. Note that the special <varname>excluded</varname> table is used to reference values originally proposed for insertion: 新しい販売店(distributors)を適切に挿入または更新します。 did列に現れる値を制限する一意インデックスが定義されているものとします。 元々挿入されようとしていた値を参照するために、特別なexcludedテーブルが使用されていることに注意して下さい。

INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;

Insert a distributor, or do nothing for rows proposed for insertion when an existing, excluded row (a row with a matching constrained column or columns after before row insert triggers fire) exists. Example assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column: 販売店を挿入するか、あるいは挿入しようとした行について既存の除外行（before insertの行トリガを実行した後で制約列にマッチした行）がある場合は何もしません。 例ではdid列に現れる値を制限する一意インデックスがあるものとしています。

INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH')
    ON CONFLICT (did) DO NOTHING;

Insert or update new distributors as appropriate. Example assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column. <literal>WHERE</literal> clause is used to limit the rows actually updated (any existing row not updated will still be locked, though): 新しい販売店を適切に挿入または更新します。 例ではdid列に現れる値を制限する一意インデックスがあるものとしています。 実際に更新される行を制限するためにWHERE句が使われています（ただし、更新されない既存の行もすべてロックされます）。

-- Don't update existing distributors based in a certain ZIP code

-- 特定の郵便番号については既存の販売店を更新しません
INSERT INTO distributors AS d (did, dname) VALUES (8, 'Anvil Distribution')
    ON CONFLICT (did) DO UPDATE
    SET dname = EXCLUDED.dname || ' (formerly ' || d.dname || ')'
    WHERE d.zipcode <> '21201';


&#45;- Name a constraint directly in the statement (uses associated
&#45;- index to arbitrate taking the DO NOTHING action)

-- 文中で制約を直接指定します（DO NOTHINGの動作をする競合解決のため
-- 関連するインデックスを指定します）
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

Insert new distributor if possible; otherwise <literal>DO NOTHING</literal>. Example assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column on a subset of rows where the <literal>is_active</literal> Boolean column evaluates to <literal>true</literal>: 可能であれば新しい販売店を挿入しますが、できないときはDO NOTHINGとします。 この例では、is_activeという論理値の列がtrueである行という条件で、did列に一意インデックスが定義されているものとしています。

-- This statement could infer a partial unique index on "did"
-- with a predicate of "WHERE is_active", but it could also
-- just use a regular unique constraint on "did"

-- この文は"WHERE is_active"という述語を使って、部分インデックスを
-- 推定できますが、単に"did"上の通常の一意制約を使うこともできます
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

互換性

<command>INSERT</command> conforms to the SQL standard, except that the <literal>RETURNING</literal> clause is a <productname>PostgreSQL</productname> extension, as is the ability to use <literal>WITH</literal> with <command>INSERT</command>, and the ability to specify an alternative action with <literal>ON CONFLICT</literal>. Also, the case in which a column name list is omitted, but not all the columns are filled from the <literal>VALUES</literal> clause or <replaceable>query</replaceable>, is disallowed by the standard. If you prefer a more SQL standard conforming statement than <literal>ON CONFLICT</literal>, see <xref linkend="sql-merge"/>. INSERTは標準SQLに準拠しています。 ただし、RETURNING句、INSERTでWITHが可能であること、ON CONFLICTで代替の動作を指定できることはPostgreSQLの拡張です。 また、標準SQLでは、列名リストが省略された時に、VALUES句またはqueryで一部の列のみを指定することはできません。 ON CONFLICTよりも標準SQLにより準拠した文がお望みであれば、MERGEを参照してください。

The SQL standard specifies that <literal>OVERRIDING SYSTEM VALUE</literal> can only be specified if an identity column that is generated always exists. PostgreSQL allows the clause in any case and ignores it if it is not applicable. 標準SQLでは、必ず値を生成するIDENTITY列が存在する場合にのみOVERRIDING SYSTEM VALUEを指定できるとしています。 PostgreSQLではこの句はどのような場合でも指定でき、それが適用できないときには無視します。

Possible limitations of the <replaceable class="parameter">query</replaceable> clause are documented under <xref linkend="sql-select"/>. query句の制限については、SELECTにて記述されています。