Описание

INSERT вставляет новые строки в таблицу. Можно вставить одну или несколько строк, указанных выражениями значений, или ноль или более строк, полученных из запроса.

Имена целевых столбцов могут быть перечислены в любом порядке. Если вообще не указан список имен столбцов, то по умолчанию используются все столбцы таблицы в их объявленном порядке; или первые N имен столбцов, если в VALUES или query указано только N столбцов. Значения, указанные в VALUES или query, связываются с явным или неявным списком столбцов слева направо.

Каждая колонка, отсутствующая в явном или неявном списке колонок, будет заполнена значением по умолчанию, либо ее объявленным значением по умолчанию, либо значением null, если такового нет.

Если выражение для любого столбца не является правильным типом данных, будет попытка автоматического преобразования типов.

INSERT в таблицы, не имеющие уникальных индексов, не будет блокироваться параллельной активностью. Таблицы с уникальными индексами могут быть заблокированы, если параллельные сессии выполняют действия, которые блокируют или изменяют строки, соответствующие уникальным значениям индекса, которые вставляются; подробности описаны в Раздел 61.5. ON CONFLICT может использоваться для указания альтернативного действия вместо возникновения ошибки нарушения ограничения уникальности или исключения (см. ON CONFLICT Clause ниже).

Необязательное предложение 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 также требует привилегию SELECT на любой столбец, значения которого считываются в выражениях ON CONFLICT DO UPDATE или condition.

Использование предложения RETURNING требует наличия привилегии SELECT на все столбцы, упомянутые в RETURNING. Если вы используете предложение 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');

Этот пример вставляет несколько строк в таблицу 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. Пример предполагает, что уникальный индекс был определен, ограничивающий значения, появляющиеся в столбце 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 - это расширение Tantor SE-1C, а также возможность использовать WITH с INSERT и возможность указать альтернативное действие с помощью ON CONFLICT. Кроме того, стандарт запрещает опускать список имен столбцов, если не все столбцы заполняются из VALUES или query. Если вы предпочитаете использовать более соответствующее стандарту SQL-операторы, вместо ON CONFLICT, см. MERGE.

Согласно стандарту SQL, OVERRIDING SYSTEM VALUE может быть указан только в том случае, если существует столбец идентификатора, который всегда генерируется. В PostgreSQL это предложение разрешено в любом случае и игнорируется, если оно не применимо.

Возможные ограничения внутри предложения query документированы в разделе SELECT.