描述

INSERT 向表中插入新行。可以插入由值表达式指定的一行或多行，也可以插入由查询得到的零行或多行。

目标列名可以按任意顺序列出。如果完全没有给出列名列表，则默认为表中按声明顺序排列的所有列；或者，在只给出了 N 列时，默认为前 N 个列名，这些列由 VALUES 子句或 query 提供。VALUES 子句或 query 提供的值会按从左到右的顺序与显式或隐式的列列表相关联。

显式或隐式列列表中没有出现的每一列都将被填充默认值，即它声明的默认值；如果没有默认值，则填充空值。

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

向缺少唯一索引的表执行 INSERT 不会被并发活动阻塞。具有唯一索引的表可能会发生阻塞，如果并发会话执行的操作锁定或修改了与正在插入的唯一索引值相匹配的行；详细信息见 Section 63.5。可以使用 ON CONFLICT 来指定一种替代动作，以代替引发唯一约束或排他约束冲突错误。（参见下文的 ON CONFLICT Clause。）

可选的 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 的所有形式还要求对任何被读取值的列拥有 SELECT 特权。这包括 conflict_target 中提到的任何列（包括仲裁者约束所引用的列），以及 ON CONFLICT DO UPDATE 的 expression 或 WHERE 子句的 condition 中提到的任何列。

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

参数

输出

成功完成时，INSERT 命令会返回如下形式的命令标签：

INSERT oid count

count 是被插入或更新的行数。oid 总是 0（过去，它是分配给被插入行的 OID，前提是 count 恰好为一且目标表被声明为 WITH OIDS，否则为 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');

这个例子从一个与 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;

按上文的方式插入或更新新的分销商，返回有关被更新的任何现有值的信息以及插入的新数据。注意，对于未发生冲突的行，old_did 和 old_dname 的返回值将为 NULL：

INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname
    RETURNING old.did AS old_did, old.dname AS old_dname,
              new.did AS new_did, new.dname AS new_dname;

插入一个分销商；当已存在一个被排除的行（在行级 BEFORE INSERT 触发器触发之后，受约束的一个或多个列与之匹配的行）时，对提议插入的行什么也不做。例子假设已经定义了一个唯一索引，用于约束 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。例子假设已经定义了一个唯一索引，用于在 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"
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 标准规定，只有当存在一个按 GENERATED ALWAYS 方式生成的标识列时，才能指定 OVERRIDING SYSTEM VALUE。PostgreSQL 在任何情况下都允许该子句，并在它不适用时忽略它。

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