[ 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 提供的值与显式或隐式列列表从左到右关联。

显式或隐式列列表中不存在的每一列都将填充默认值，即声明的默认值或（如果不存在）空值。

如果任何列的表达式不是正确的数据类型，将尝试自动类型转换。

INSERT 进入缺少唯一索引的表不会被并发活动阻塞。如果并发会话执行锁定或修改与正在插入的唯一索引值匹配的行，则带有唯一索引的表可能会阻塞；详情请参阅第 64.5 节。ON CONFLICT 可用于指定引发唯一约束或排除约束违规错误的替代操作。（请参见下面的ON CONFLICT 子句。）

可选的 RETURNING 子句会导致 INSERT 计算并返回基于实际插入（或更新，如果使用了 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 是插入或更新的行数。oid 始终为 0（如果 count 正好为 1 且目标表声明为 WITH OIDS，则它曾经是分配给插入行的 OID，否则为 0，但不再支持创建 WITH OIDS 表）。

如果 INSERT 命令包含 RETURNING 子句，则结果将类似于 SELECT 语句，其中包含 RETURNING 列表中定义的列和值，这些列和值是通过该命令插入或更新的行计算得出的。

说明

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

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

示例

向表 films 中插入一行

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');

此示例将一些行从表 tmp_films 插入到表 films 中，表 tmp_films 的列布局与 films 相同

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;

如果可能，插入新分销商；否则 不执行任何操作。示例假设已定义唯一索引，该索引约束出现在 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 下有记录。