描述

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

目标列名可以按任意顺序列出。如果根本未给出列名列表，则默认使用按声明顺序排列的全部列；或者如果 VALUES 子句或 query 只提供了 N 列，则默认使用按声明顺序排列的前 N 个列名。VALUES 子句或 query 提供的值，会按从左到右的顺序与显式或隐式列列表对应起来。

任何未出现在显式或隐式列列表中的列都会填入默认值；如果没有声明默认值，则填入空值。

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

对没有唯一索引的表执行 INSERT 不会被并发活动阻塞。若并发会话执行的操作会锁定或修改与待插入唯一索引值匹配的行，则带有唯一索引的表可能发生阻塞；详见第 61.5 节。ON CONFLICT 可用于指定一种替代动作，而不是报出违反唯一约束或排他约束的错误。（见下文 ON CONFLICT Clause。）

可选的 RETURNING 子句使 INSERT 基于每个实际插入的行（若使用了 ON CONFLICT DO UPDATE 子句，则也可能是更新后的行）计算并返回一个或多个值。这主要用于获取由默认值提供的值，例如 serial 序列号。不过，也允许使用任何引用该表列的表达式。RETURNING 列表的语法与 SELECT 的输出列表相同。只有成功插入或更新的行才会被返回。例如，如果某一行被锁定，但由于不满足 ON CONFLICT DO UPDATE ... WHERE 子句中的 condition 而未被更新，则该行不会被返回。

要向表中插入行，必须具有该表上的 INSERT 权限。如果存在 ON CONFLICT DO UPDATE 子句，还要求具有该表上的 UPDATE 权限。

如果指定了列列表，你只需要对所列列具有 INSERT 权限。类似地，在指定 ON CONFLICT DO UPDATE 时，你只需要对列出要更新的列具有 UPDATE 权限。不过，ON CONFLICT DO UPDATE 还要求具有 SELECT 权限，涵盖 ON CONFLICT DO UPDATE 表达式或 condition 中读取其值的任何列。

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

参数

输出

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

INSERT oid count

count 是插入或更新的行数。oid 始终为 0（过去，如果 count 恰好为 1 且目标表声明为 WITH OIDS，则它是分配给插入行的 OID，否则为 0；但现在已经不再支持创建 WITH OIDS 表）。

如果 INSERT 命令包含 RETURNING 子句，则结果将类似于一个 SELECT 语句，其中包含 RETURNING 列表定义的列和值，它们是基于该命令插入或更新的行计算出来的。

注解

如果指定的表是分区表，则每一行都会被路由到适当的分区并插入其中。如果指定的表本身就是一个分区，则只要输入行中有任意一行违反该分区约束，就会报错。

示例

向表 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';

这个示例向数组列插入值：

-- 为井字棋创建一个空的 3x3 棋盘
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- 上例中的下标实际上并非必需
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;

插入一个分销商；如果已存在一条会导致待插入行被排除的现有行（即在行级 BEFORE INSERT 触发器触发后，其受约束列与待插入行匹配的行），则对该待插入行不做任何操作。示例假设已经定义了一个唯一索引，用于约束出现在 did 列中的值：

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

视情况插入或更新新的分销商。示例假设已经定义了一个唯一索引，用于约束出现在 did 列中的值。这里使用 WHERE 子句来限制实际会被更新的行（不过，任何未更新的现有行仍会被锁定）：

-- 不更新位于某个邮政编码区域内的现有分销商
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';

-- 在语句中直接指定约束名称（使用关联的
-- 索引来仲裁是否采取 DO NOTHING 动作）
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

如果可能就插入新的分销商；否则执行 DO NOTHING。示例假设已经定义了一个唯一索引，用于约束这样一个行子集上的 did 列值：其中 is_active 布尔列计算结果为 true：

-- 这条语句可以推断出 "did" 上以 "WHERE is_active"
-- 为谓词的部分唯一索引，但也可以直接使用
-- "did" 上的普通唯一约束
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

兼容性

INSERT 符合 SQL 标准，但 RETURNING 子句是 PostgreSQL 扩展，在 INSERT 中使用 WITH 的能力以及使用 ON CONFLICT 指定替代动作的能力也都是扩展。此外，标准不允许省略列名列表却又不是所有列都由 VALUES 子句或 query 填充的情况。

SQL 标准规定，只有当存在一个定义为总是生成值的标识列时，才能指定 OVERRIDING SYSTEM VALUE。而 PostgreSQL 在任何情况下都允许该子句，并在它不适用时忽略它。

query 子句可能存在的限制见 SELECT。