描述

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

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

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

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

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

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

要向表中插入行，必须具有该表上的INSERT权限。如果存在ON CONFLICT DO UPDATE子句，还要求具有该表上的UPDATE权限。如果存在ON CONFLICT DO SELECT，则还要求具有该表上的SELECT权限。如果使用 ON CONFLICT DO SELECT FOR UPDATE/SHARE，则除了SELECT权限外，还要求至少对一列具有 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（过去，如果 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');

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

按照上例插入或更新新的分销商，并返回任何被更新的既有值以及插入的新数据。请注意，对于没有冲突的行，返回的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子句来限制实际会被更新的行（不过，任何未更新的现有行仍会被锁定）：

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

如果可能就插入新的分销商；否则返回现有的分销商行。示例假设已经定义了一个唯一索引，用于约束出现在did列中的值。这对获取或创建模式很有用：

INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
    ON CONFLICT (did) DO SELECT
    RETURNING *;

如果新分销商的 ID 不匹配，则插入它；否则，如果其名称不匹配，则返回现有行：

INSERT INTO distributors AS d (did, dname) VALUES (12, 'Micro Devices Inc')
    ON CONFLICT (did) DO SELECT WHERE d.dname != EXCLUDED.dname
    RETURNING *;

插入一个新分销商，或返回并锁定现有行以便更新。当你需要确保对该行的独占访问时，这很有用：

INSERT INTO distributors (did, dname) VALUES (13, 'Advanced Systems')
    ON CONFLICT (did) DO SELECT FOR UPDATE
    RETURNING *;

如果可能就插入新的分销商；否则执行 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填充的情况。如果你希望使用比ON CONFLICT更符合 SQL 标准的语句，请参见MERGE。

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

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