描述

INSERT将新行插入到表中。我们可以 插入一个或多个由值表达式指定的行，或者插入来自查询的零行 或更多行。

目标列的名称可以以任意顺序列出。如果没有给出列名列表，则默认是以声明的顺序列出该表的所有列；或者如果N个列仅由VALUES子句或query提供，则为前N个列。VALUES子句或query提供的值会从左到右与显式或隐式列列表关联。

每个未出现在显式或隐式列列表中的列将被填充为默认值，若没有声明默认值则填充为null。

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

INSERT缺少唯一索引的表不会被并发活动阻塞。 如果并发会话执行锁定或修改与要插入的唯一索引值匹配的行的操作，则具有唯一索引的表可能会阻塞； 详细信息在第 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 UPDATEexpression 或WHERE子句condition中提到的任何列。

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

参数

输出

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

INSERT oid count

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

如果INSERT命令包含RETURNING子句， 其结果会类似于包含RETURNING列表中定义的列和值的 SELECT语句，这些结果是由该命令在被插入或更新行上 计算得到。

注释

如果指定的表是一个分区表，每一行都会被路由到合适的分区并且插入其中。 如果指定的表是一个分区，如果输入行之一违背该分区的约束则将发生错误。

您可能还希望考虑使用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');

这个例子从表tmp_films中插入一些行到表 films中，两个表具有相同的列布局：

INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';

这个例子插入数组列：

-- 为 noughts-and-crosses 游戏创建一个空的 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;

插入一个分销商，或者在一个被排除的行（具有一个匹配约束的列或者 会让行级前（或者后）插入触发器引发的列的行）存在时不处理要插入的行。 例子假设已经定义了一个唯一索引来约束出现在did列 中的值：

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

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

-- 不更新位于特定 ZIP 代码的现有分销商
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。 例子假设已经定义了一个唯一索引，它约束让is_active 布尔列为true的行子集上did列中的值：

-- 这个语句可能推断出一个在 "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标准的语句而不是ON CONFLICT，请参阅MERGE。

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

query子句可能的限制在 SELECT中有介绍。