描述

INSERT 用于在表中插入新行。可以通过值表达式指定一行或多行，或者通过查询结果指定零行或多行。

目标列名可以按任何顺序给出。如果根本没有给出列名列表，则默认情况下是表中所有列，按声明的顺序排列；或者，如果 VALUES 子句或 query 只提供了 N 个列名，则默认是前 N 个列名。由 VALUES 子句或 query 提供的这些值将从左到右与显式或隐式指定的列列表对应。

显式或隐式列列表中不存在的每一列都将用默认值填充，如果声明了默认值，则使用声明的默认值，否则使用 NULL。

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

INSERT 到没有唯一索引的表不会被并发活动阻止。具有唯一索引的表可能会被阻止，如果并发会话执行的操作锁定或修改与要插入的唯一索引值匹配的行；详细信息请参阅 第 63.5 节。可以使用 ON CONFLICT 指定一个替代操作，以代替引发唯一约束或排除约束冲突错误。（请参阅下面的 ON CONFLICT 子句。）

可选的 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 DO UPDATE 还要求对在 ON CONFLICT DO UPDATE 表达式或 condition 中读取的任何列具有 SELECT 权限。

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

参数

输出

成功完成时，INSERT 命令将返回一个命令标签，格式为

INSERT oid count

count 是插入或更新的行数。 oid 始终为 0（它以前是OID如果 count 恰好为一且目标表声明为 WITH OIDS，则分配给插入的行，否则为 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');

此示例将一些行从 tmp_films 表插入到 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 row 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 未填充所有列的情况。如果您偏好比 ON CONFLICT 更符合 SQL 标准的语句，请参阅 MERGE。

SQL 标准规定，只有在存在总是生成的标识列时才能指定 OVERRIDING SYSTEM VALUE。PostgreSQL 在任何情况下都允许此子句，如果它不适用则忽略它。

query 子句的可能限制已在 SELECT 下进行了说明。