描述

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

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

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

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

对没有唯一索引的表执行INSERT不会被并发活动阻塞。 若并发会话执行的操作会锁定或修改与待插入唯一索引值匹配的行，则带有 唯一索引的表可能发生阻塞；详见Section 60.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还要求对任何值会被读取的列 具有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列表定义的列和值，它们是基于该命令插 入或更新的行计算出来的。

注解

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

示例

向表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。示例假设已经定义了一个唯一索引， 用于约束这样一个行子集上的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扩展，在 INSERT中使用WITH的能力以及 使用ON CONFLICT指定替代动作的能力也都是扩展。 此外，标准不允许省略列名列表却又不是所有列都由VALUES 子句或query填充的情况。

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

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