描述

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 下進行了說明。