[ WITH [ RECURSIVE ] with_query [, ...] ]
INSERT INTO table_name [ AS alias ] [ ( column_name [, ...] ) ]
    [ OVERRIDING { SYSTEM | USER } VALUE ]
    { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }
    [ ON CONFLICT [ conflict_target ] conflict_action ]
    [ RETURNING { * | output_expression [ [ AS ] output_name ] } [, ...] ]

where conflict_target can be one of:

    ( { index_column_name | ( index_expression ) } [ COLLATE collation ] [ opclass ] [, ...] ) [ WHERE index_predicate ]
    ON CONSTRAINT constraint_name

and conflict_action is one of:

    DO NOTHING
    DO UPDATE SET { column_name = { expression | DEFAULT } |
                    ( column_name [, ...] ) = [ ROW ] ( { expression | DEFAULT } [, ...] ) |
                    ( column_name [, ...] ) = ( sub-SELECT )
                  } [, ...]
              [ WHERE condition ]

说明

INSERT将新行插入表中。可以插入一个或多个由值表达式指定的行，或查询产生的零行或多行。

目标列名可以按任何顺序列出。如果根本没有给出列名列表，则默认为表的所有列按声明的顺序；或前N个列名（如果VALUES子句或query仅提供N个列）。VALUES子句或query提供的值从左到右与显式或隐式列列表相关联。

显式或隐式列列表中不存在的每个列都将填充默认值，可能是其声明的默认值，如果没有则为 null。

如果任意列的表达式的类型不正确，系统将会尝试自动转换类型。

INSERT到没有唯一索引的表中不会因并发活动而阻塞。如果有唯一索引的表可能会在并发会话执行锁定或修改与正在插入的唯一索引值匹配的行时发生阻塞；详细信息介绍于第 62.5 节。可以使用ON CONFLICT指定替代动作以引发唯一约束或排除约束冲突错误。（参见下文的ON CONFLICT 子句。）

可选的RETURNING子句让INSERT根据实际上插入（或 updated，如果使用了ON CONFLICT DO UPDATE子句）的每一行来计算并返回值。这主要用于获取由默认值（例如序列号）提供的行。然而，允许使用表列的任何表达式。RETURNING列表的语法与SELECT的输出列表相同。只有插入或更新成功的行才会返回。例如，如果行被锁定但未更新是因为ON CONFLICT DO UPDATE ... WHERE子句condition未得到满足，则不会返回该行。

为了向表中插入数据，用户必须有表的INSERT权限。如果存在ON CONFLICT DO UPDATE，还需要表的UPDATE权限。

如果指定了列列表，则您只需对列出的列拥有 INSERT 权限。同样， ON CONFLICT DO UPDATE 指定时，您只需对要更新的列拥有 UPDATE 权限。但是， ON CONFLICT DO UPDATE 还要求对在 ON CONFLICT DO UPDATE 表达式或 condition 中读取其值的任何列拥有 SELECT 权限。

使用 RETURNING 子句需要对 RETURNING 中提到的所有列拥有 SELECT 权限。如果您使用 query 子句从查询中插入行，那么您当然需要对查询中使用的任何表或列拥有 SELECT 权限。

参数

输出

成功完成后，INSERT 命令将返回以下形式的命令标记

INSERT oid count

count 是已插入或已更新的行数。如果 count 恰好为 1，且目标表声明为 WITH OIDS，则 oid 始终为 0（以前分配给已插入行，且 0 表示其他情况，但不再支持创建 WITH OIDS 表）。OID分配给已插入行，如果 count 恰好为 1，且目标表声明为 WITH OIDS，则 0 表示其他情况，但不再支持创建 WITH OIDS 表）。

如果 INSERT 命令包含一个 RETURNING 子句，结果将与一个 SELECT 语句类似，该语句包含 RETURNING 列表中定义的列和值，这些值计算自该命令插入或更新的行。

备注

如果指定表是分区表，则每行都将路由到适当的分区并插入其中。如果指定表是一个分区，则如果输入行之一违反分区约束，将会发生错误。

您可能还想考虑使用 MERGE，因为它允许在单一语句中混合 INSERT、UPDATE 和 DELETE。请参见 MERGE。

示例

将单行插入到表 film 中

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

在此示例中，len 列被省略，因此它将具有默认值

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

此示例使用 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');

此示例从具有与 film 相同列布局的表 tmp_film 中向表 film 中插入一些行

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

此示例插入到数组列

-- Create an empty 3x3 gameboard for noughts-and-crosses
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," "}}');

将单行插入到表 distributors 中，返回由 `DEFAULT` 子句生成的序列号

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

增加由 Acme Corporation 管理的帐户的业务员的销售额，并记录整个更新后的行以及当前时间在日志表中

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;

根据需要插入或更新新的分销商。假设已定义唯一索引以约束出现在 did 列中的值。请注意，特殊 excluded 表用于引用最初建议插入的值

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

插入分销商，或当现有已排除行 (在行插入触发器触发之前具有匹配的约束列或列的行) 存在时对建议插入的行不做任何处理。示例假设已定义唯一索引以约束出现在 did 列中的值

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

根据需要插入或更新新的分销商。示例假设已定义唯一索引以约束出现在 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';

-- Name a constraint directly in the statement (uses associated
-- index to arbitrate taking the DO NOTHING action)
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

如果可能，插入新的分销商；否则 DO NOTHING。示例假设已定义唯一索引以约束出现在 did 列中的一组行中，其中布尔列 is_active 计算结果为 true

-- 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"
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

兼容性

INSERT 符合 SQL 标准，但 RETURNING 子句是 PostgreSQL 扩展，因此可以将 WITH 与 INSERT 一起使用，并可以通过 ON CONFLICT 指定备用操作。另外，标准不允许列出列名但并非从 VALUES 子句或 query 中填充所有列。如果您更喜欢比 ON CONFLICT 更符合 SQL 标准的语句，请参阅 MERGE。

SQL 标准规定仅在生成始终存在的标识列时才能指定 OVERRIDING SYSTEM VALUE。无论哪种情况下，PostgreSQL 都允许该子句，如果它不可用，它会忽略它。

query 子句的可能限制记录在 SELECT 下。