說明

INSERT 會將新的資料列插入資料表中。 可以插入由值運算式指定的一或多個資料列，或插入由查詢產生零或多個資料列。

目標欄位名稱可以依任何順序排列。 如果完全沒有提供欄位名稱清單，則預設為資料表中所有欄位依其宣告的順序排列；或者，如果 VALUES 子句或 query 僅提供 N 個欄位，則為前 N 個欄位名稱。 由 VALUES 子句或 query 提供的值會由左至右與明確或隱含的欄位清單相關聯。

未出現在明確或隱含欄位清單中的每個欄位都將填入預設值，可以是其宣告的預設值，如果沒有則為 null。

如果任何欄位的運算式不是正確的資料類型，將會嘗試自動類型轉換。

對缺少唯一索引的資料表執行 INSERT，不會因並行活動而受到阻擋。 如果並行工作階段執行鎖定或修改符合要插入的唯一索引值的資料列的動作，則具有唯一索引的資料表可能會受到阻擋；詳細資訊請參閱 第 62.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，則分配給插入列的 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');

此範例將一些列從與 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;

插入一個經銷商，或者對於在現有的、排除的列（在觸發列插入觸發器之前，具有匹配的受約束欄位或列的列）存在時建議插入的列，不執行任何操作。範例假設已定義一個唯一索引，該索引約束了 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。範例假設已定義一個唯一索引，該索引約束了在 is_active Boolean 欄位評估為 true 的列子集中，did 欄位中出現的值

-- 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 擴充功能，使用 WITH 與 INSERT 的能力，以及使用 ON CONFLICT 指定替代動作的能力也是如此。此外，省略欄位名稱清單，但並非所有欄位都從 VALUES 子句或 query 填充的情況，標準是不允許的。如果您更喜歡比 ON CONFLICT 更符合 SQL 標準的語句，請參閱 MERGE。

SQL 標準指定只有在始終產生的識別欄位存在時，才能指定 OVERRIDING SYSTEM VALUE。PostgreSQL 允許在任何情況下使用該子句，如果它不適用，則會忽略它。

query 子句的可能限制記錄在 SELECT 下。