INSERT

INSERT добавляет в таблицу одну или несколько строк.

Синтаксис

INSERT INTO table_name [(column_name [, ...])]
{ VALUES (expression [, ...]) [, ...] | select_query }
[ON CONFLICT [(column_name [, ...])]
    DO { NOTHING | UPDATE SET column_name = expression [, ...] }]
[RETURNING expression [, ...]]

Описание

Список столбцов сопоставляет входные значения с целевыми столбцами. Пропущенные столбцы получают DEFAULT, генерируемое значение или NULL, если он допустим. Источником может быть INSERT SELECT или CTE с последующим SELECT.

Параметры

Ширина каждой строки VALUES должна совпадать с целевым списком. ON CONFLICT DO NOTHING пропускает конфликтующую строку. DO UPDATE обращается к предлагаемой строке как excluded.column_name. RETURNING вычисляется для реально вставленных или обновлённых строк.

Результат

Без RETURNING клиент получает число затронутых строк. RETURNING формирует набор строк без гарантированного порядка.

Поведение в транзакции

Оператор атомарен целиком, включая многострочный ввод и обработку конфликтов. Он входит в активную транзакцию либо выполняется как одна autocommit-транзакция.

Ошибки и ограничения

Ошибки типов, NOT NULL, CHECK, внешнего ключа и уникальности отклоняют оператор. Навигационные пути доступны только для чтения и не могут быть целевыми столбцами или выражениями записи. Обработка конфликтов ограничена формами из матрицы.

Права

Обычной сессии нужны CONNECT, USAGE схемы и INSERT для каждого целевого столбца. Выражения, SELECT-источники и чтение в DO UPDATE дополнительно требуют SELECT; для изменяемых при конфликте столбцов нужен UPDATE.

Пример

CREATE TABLE ref_insert (id INTEGER PRIMARY KEY, title TEXT NOT NULL);
INSERT INTO ref_insert (id, title) VALUES (1, 'draft'), (2, 'review')
RETURNING id, title;

См. также

См. Изменение данных, UPDATE и Управление доступом.