INSERT · PostgreSQL 中文文档 9.3

# INSERT ## Name INSERT -- 在表中创建新行 ## Synopsis ``` [ WITH [ RECURSIVE ] _with_query_ [, ...] ] INSERT INTO _table_name_ [ ( _column_name_ [, ...] ) ] { DEFAULT VALUES | VALUES ( { _expression_ | DEFAULT } [, ...] ) [, ...] | _query_ } [ RETURNING * | _output_expression_ [ [ AS ] _output_name_ ] [, ...] ] ``` ## 描述 `INSERT`向表中插入新行。可以一次插入用值表达式声明的一行或多行，或者一个查询结果表现出来的零行或多个行。目标列表中的列/字段可以按任何顺序排列。如果完全没有列出任何字段名，那么缺省是全部字段，顺序是按照表声明的时候的顺序；如果`VALUES`子句或者`_query_` 里面只提供了`_N_`个字段，那么就是头`_N_`个字段。`VALUES` 子句或者`_query_`提供的数值是以从左到右的方式与明确或者隐含的字段列表关联的。每个没有在明确或者隐含的字段列表中出现的字段都将填充缺省值，如果有声明的缺省值则用声明的那个，如果没有则用 NULL 。如果每个字段的表达式不是正确的数据类型，系统将试图进行自动的类型转换。可选的`RETURNING`子句将导致`INSERT`计算和返回实际插入的行，它主要用于获取缺省的计算值(比如序列值)，不过，任何使用该表字段的表达式都是允许的。 `RETURNING`列表的语法都与`SELECT`的输出列表相同。要想向表中插入数据，你必须有`INSERT`权限。如果指定了一个字段列表，那么只需要在列表字段上的`INSERT`权限。使用`RETURNING` 子句需要要在`RETURNING`中提到的所有字段上的`SELECT`权限。如果你使用了`_query_`子句插入来自查询里的数据行，你还需要拥有在查询里使用的表或字段的`SELECT`权限。 ## 参数 `_with_query_` `WITH`子句允许声明一个或多个可以在`INSERT` 查询中通过名字引用的子查询。参阅[Section 7.8](#calibre_link-515)和 [SELECT](#calibre_link-104)获取详细信息。 `_query_`(`SELECT` 语句) 也包含一个`WITH`子句是可能的。在这种情况下，两套 `_with_query_`都可以在`_query_` 中引用，但是第二个优先，因为它嵌套更紧密。 `_table_name_` 现存表的名称(可以有模式修饰)。 `_column_name_` 通过`_table_name_`命名的表中的字段名。必要时，字段名可以有子字段名或者数组下标修饰。向一个复合类型中的某些字段插入数据的话，其它字段将是 NULL 。 `DEFAULT VALUES` 所有字段都会用它们的缺省值填充。 `_expression_` 赋予对应的 column 的一个有效表达式或值。 `DEFAULT` 对应的 column 将被它的缺省值填充。 `_query_` 一个查询(`SELECT`语句)，它提供插入的数据行。请参考[SELECT](#calibre_link-104) 语句获取语法描述。 `_output_expression_` `INSERT`命令在每一行都被插入之后用于计算输出结果的表达式。该表达式可以使用通过`_table_name_`命名的表的的任意字段。可以使用`*`返回被插入行的所有字段。 `_output_name_` 一个字段的输出名称。 ## 输出成功完成后，一条 `INSERT`命令返回一个下面形式的命令标签 ``` INSERT _oid_ _count_ ``` `_count_`是插入的行数。如果 `_count_`正好是一，并且目标表有 OID ，那么`_oid_`是赋予插入行的OID。否则`_oid_`是零。如果`INSERT`命令包含`RETURNING`子句，其结果将和一个`SELECT` 语句相同，包含那些基于该命令实际插入的行计算的、定义在`RETURNING`列表中的字段的值。 ## 例子向表`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`中，字段布局与`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; ``` ## 兼容性 `INSERT`语句与 SQL 标准兼容。但`RETURNING`子句是 PostgreSQL扩展，就像在`INSERT`中使用`WITH`。同样，省略字段名列表，但是并非所有字段都从`VALUES`子句或者`_query_` 填充的这种用法是标准不允许的。可能碰到的关于`_query_`子句特性的限制在 [SELECT](#calibre_link-104)语句中有相关文档。