INSERT
Создает новые строки в таблице.
Синтаксис
[WITH [ RECURSIVE ] <with_query> [, ...]]
INSERT INTO <table_name> [( <column_name> [, ...] )]
{DEFAULT VALUES | VALUES ( {<expression> | DEFAULT} [, ...] ) [, ...] | <query>}
[RETURNING * | <output_expression> [[AS] <output_name> ] [, ...]]Описание
Команда INSERT добавляет новые строки в таблицу. Можно вставить одну или несколько строк, сформированных выражениями значений, либо ноль или более строк, полученных в результате выполнения дополнительного запроса.
Имена целевых столбцов могут быть перечислены в любом порядке. Если список имен столбцов отсутствует, по умолчанию используются все столбцы таблицы в указанном порядке; либо первые N столбцов, если от выражения VALUES или query поступает только N столбцов. Значения, получаемые от выражения VALUES или query, связываются с явно или неявно определенным списком столбцов слева направо.
Каждый столбец, отсутствующий в явно или неявно указанном списке столбцов, будет заполнен значением по умолчанию, если для него объявлено значение по умолчанию, либо NULL в противном случае.
Если выражение для какого-либо столбца определяет значение неподходящего типа данных, система попытается автоматически привести его к нужному типу.
С необязательным выражением RETURNING команда INSERT вычислит и вернет значения для каждой фактически вставленной строки. Это в первую очередь полезно для получения значений, присвоенных по умолчанию, например, порядкового номера записи. Однако в этом выражении допускается любое выражение, использующее столбцы таблицы. Синтаксис списка RETURNING идентичен синтаксису выходного списка оператора SELECT.
Для вставки данных в таблицу необходимо иметь привилегию INSERT. Если указан список столбцов, привилегия INSERT требуется только для перечисленных столбцов. Использование выражения RETURNING требует наличия привилегии SELECT для всех столбцов, перечисленных в RETURNING. Если для добавления строк применяется query, для всех таблиц или столбцов, задействованных в этом запросе, необходимо иметь привилегию SELECT.
Параметры
| Параметр | Описание |
|---|---|
with_query |
Выражение Запрос ( |
table_name |
Имя существующей таблицы (опционально указанное со схемой) |
column_name |
Имя столбца в таблице, указанной параметром |
DEFAULT VALUES |
Все столбцы будут заполнены значениями по умолчанию |
expression |
Выражение или значение, которое нужно присвоить соответствующему столбцу |
DEFAULT |
Соответствующий столбец будет заполнен значением по умолчанию |
query |
Запрос ( |
output_expression |
Выражение, которое вычислит и вернет команда |
output_name |
Имя, назначаемое возвращаемому столбцу |
Выводимая информация
В случае успешного выполнения команды INSERT возвращается сообщение вида:
INSERT <oid> <count>
Здесь count — количество вставленных строк. Если значение count равно 1 и целевая таблица имеет OID, то oid — это OID, присвоенный вставленной строке. В противном случае значение oid равно 0.
Если команда 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');В этом примере в таблицу films вставляются некоторые строки из таблицы tmp_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, как и возможность использования WITH с INSERT. Кроме того, стандарт не допускает ситуацию, когда список имен столбцов опущен, но не все столбцы заполняются значениями из выражения VALUES или query.
Возможные ограничения выражения query описаны в статье SELECT.