INSERT

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

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

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

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

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

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

也可以考虑使用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;

如果可能就插入新的分销商；否则执行 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。