15.2.7 INSERT Statement — MySQL 8.4

15.2.7 Оператор INSERT

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name
    [PARTITION (partition_name [, partition_name] ...)]
    [(col_name [, col_name] ...)]
    { {VALUES | VALUE} (value_list) [, (value_list)] ... }
    [AS row_alias[(col_alias [, col_alias] ...)]]
    [ON DUPLICATE KEY UPDATE assignment_list]

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name
    [PARTITION (partition_name [, partition_name] ...)]
    SET assignment_list
    [AS row_alias[(col_alias [, col_alias] ...)]]
    [ON DUPLICATE KEY UPDATE assignment_list]

INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name
    [PARTITION (partition_name [, partition_name] ...)]
    [(col_name [, col_name] ...)]
    { SELECT ...
      | TABLE table_name
      | VALUES row_constructor_list
    }
    [ON DUPLICATE KEY UPDATE assignment_list]

value:
    {expr | DEFAULT}

value_list:
    value [, value] ...

row_constructor_list:
    ROW(value_list)[, ROW(value_list)][, ...]

assignment:
    col_name =
          value
        | [row_alias.]col_name
        | [tbl_name.]col_name
        | [row_alias.]col_alias

assignment_list:
    assignment [, assignment] ...

INSERT вставляет новые строки в существующую таблицу. INSERT ... VALUES, INSERT ... VALUES ROW() и INSERT ... SET формы оператора вставляют строки на основе явно указанных значений. Форма INSERT ... SELECT вставляет строки, выбранные из другой таблицы или таблиц. Также можно использовать INSERT ... TABLE для вставки строк из одной таблицы. INSERT с клаузой ON DUPLICATE KEY UPDATE позволяет обновлять существующие строки, если вставка строки приведет к дублированию значения в UNIQUE индексе или PRIMARY KEY. Псевдоним строки с одним или несколькими необязательными псевдонимами столбцов может использоваться с ON DUPLICATE KEY UPDATE для ссылки на вставляемую строку.

Дополнительную информацию об INSERT ... SELECT и INSERT ... ON DUPLICATE KEY UPDATE см. в разделе 15.2.7.1, «Оператор INSERT ... SELECT» и разделе 15.2.7.2, «Оператор INSERT ... ON DUPLICATE KEY UPDATE».

В MySQL 8.4 ключевое слово DELAYED принимается, но игнорируется сервером. Причины этого см. в разделе 15.2.7.3, «Оператор INSERT DELAYED».

Для вставки в таблицу требуется привилегия INSERT для таблицы. Если используется клауза ON DUPLICATE KEY UPDATE и дублирование ключа приводит к выполнению UPDATE, то для столбцов, которые будут обновлены, требуется привилегия UPDATE. Для столбцов, которые только читаются, но не изменяются, достаточно привилегии SELECT (например, для столбца, упомянутого только в правой части присваивания col_name=expr в клаузе ON DUPLICATE KEY UPDATE).

При вставке в разграниченную таблицу можно управлять тем, какие разделы и подразделы принимают новые строки. Клауза PARTITION принимает список имен разделов или подразделов (или обоих) таблицы, разделенных запятыми. Если какие-либо из строк, которые должны быть вставлены данным оператором INSERT, не соответствуют одному из перечисленных разделов, оператор INSERT завершается с ошибкой Найдена строка, не соответствующая заданному набору разделов. Более подробная информация и примеры см. в разделе 26.5, «Выбор раздела».

tbl_name — это таблица, в которую следует вставить строки. Укажите столбцы, для которых оператор предоставляет значения следующим образом:

Укажите заключённый в скобки список разделённых запятыми имён столбцов после имени таблицы. В этом случае значение для каждого указанного столбца должно быть предоставлено списком VALUES, списком VALUES ROW() или оператором SELECT. Для формы INSERT TABLE количество столбцов в исходной таблице должно соответствовать количеству вставляемых столбцов.
Если вы не указываете список имён столбцов для INSERT ... VALUES или INSERT ... SELECT, значения для каждого столбца в таблице должны быть предоставлены списком VALUES, оператором SELECT или оператором TABLE. Если вы не знаете порядок столбцов в таблице, используйте DESCRIBE tbl_name для его определения.
Клауза SET указывает столбцы явно по имени вместе со значением, которое нужно назначить каждому из них.

Значения столбцов можно указать несколькими способами:

Если строгий режим SQL не включён, любой столбец, для которого явно не задано значение, устанавливается в его значение по умолчанию (явное или неявное). Например, если вы указываете список столбцов, не содержащий все столбцы таблицы, неуказанные столбцы устанавливаются в свои значения по умолчанию. Назначение значений по умолчанию описано в разделе 13.6, «Значения по умолчанию типов данных».

Если строгий режим SQL включён, оператор INSERT генерирует ошибку, если он не указывает явное значение для каждого столбца, для которого нет значения по умолчанию. См. раздел 7.1.11, «Режимы SQL сервера».
Если и список столбцов, и список VALUES пустые, INSERT создаёт строку, в которой каждый столбец устанавливается в своё значение по умолчанию:
```
INSERT INTO tbl_name () VALUES();
```
Если строгий режим не включён, MySQL использует неявное значение по умолчанию для любого столбца, у которого нет явно определённого значения по умолчанию. Если строгий режим включён, произойдёт ошибка, если у какого-либо столбца нет значения по умолчанию.
Используйте ключевое слово DEFAULT, чтобы явно установить столбец в его значение по умолчанию. Это упрощает написание операторов INSERT, которые присваивают значения всем, кроме нескольких столбцов, поскольку это позволяет избежать написания неполного списка VALUES, который не содержит значения для каждого столбца в таблице. В противном случае, необходимо предоставить список имён столбцов, соответствующих каждому значению в списке VALUES.
Если сгенерированный столбец вставляется явно, единственно допустимым значением является DEFAULT. Сведения о сгенерированных столбцах см. в разделе 15.1.20.8, «CREATE TABLE и сгенерированные столбцы».
В выражениях можно использовать DEFAULT(col_name) для получения значения по умолчанию для столбца col_name.
Преобразование типа выражения expr, предоставляющего значение столбца, может произойти, если тип данных выражения не соответствует типу данных столбца. Преобразование заданного значения может привести к различным вставленным значениям в зависимости от типа столбца. Например, вставка строки '1999.0e-2' в столбец INT, FLOAT, DECIMAL(10,6) или YEAR вставляет соответственно значения 1999, 19.9921, 19.992100 или 1999. Сохранённое значение в столбцах INT и YEAR равно 1999, так как преобразование строки в число рассматривает только ту часть исходной строки, которая может считаться допустимым целым числом или годом. Для столбцов FLOAT и DECIMAL преобразование строки в число рассматривает всю строку как допустимое числовое значение.
Выражение expr может ссылаться на любой столбец, который был задан ранее в списке значений. Например, это можно сделать, потому что значение для col2 относится к col1, которому ранее было присвоено значение:
```
INSERT INTO tbl_name (col1,col2) VALUES(15,col1*2);
```
Но следующее не является допустимым, потому что значение для col1 относится к col2, которому присваивается значение после col1:
```
INSERT INTO tbl_name (col1,col2) VALUES(col2*2,15);
```
Исключение возникает для столбцов, содержащих AUTO_INCREMENT значения. Поскольку AUTO_INCREMENT значения генерируются после других присваиваний значений, любая ссылка на столбец AUTO_INCREMENT в присваивании возвращает 0.

Операторы INSERT с использованием синтаксиса VALUES могут вставлять несколько строк. Для этого включите несколько списков разделённых запятыми значений столбцов, с списками, заключёнными в скобки и разделёнными запятыми. Пример:

INSERT INTO tbl_name (a,b,c)
    VALUES(1,2,3), (4,5,6), (7,8,9);

Каждый список значений должен содержать ровно столько значений, сколько требуется для вставки в строку. Следующее утверждение некорректно, так как оно содержит один список из девяти значений, а не три списка по три значения каждый:

INSERT INTO tbl_name (a,b,c) VALUES(1,2,3,4,5,6,7,8,9);

VALUE является синонимом для VALUES в данном контексте. Ни одно из них не подразумевает ничего о количестве списков значений или количестве значений в каждом списке. Оба могут использоваться, как при наличии одного списка значений, так и при наличии нескольких списков, независимо от количества значений в каждом списке.

Заявления INSERT с использованием синтаксиса VALUES также могут вставлять несколько строк. В этом случае каждый список значений должен быть заключен в ROW() (конструктор строки), как показано ниже:

INSERT INTO tbl_name (a,b,c)
    VALUES ROW(1,2,3), ROW(4,5,6), ROW(7,8,9);

Значение affected-rows для заявления INSERT может быть получено с помощью SQL-функции ROW_COUNT() или функции C API. См. раздел 14.15 «Функции информации», и .

Если вы используете заявление INSERT или INSERT ... SELECT с несколькими списками значений, или INSERT ... SELECT или INSERT ... TABLE, заявление возвращает строку информации в следующем формате:

Records: N1 Duplicates: N2 Warnings: N3

Если вы используете C API, строку информации можно получить, вызвав функцию . См. .

Records указывает количество обработанных строк заявлением. (Это не обязательно количество фактически вставленных строк, потому что Duplicates может быть отличным от нуля.) Duplicates указывает количество строк, которые не могли быть вставлены, потому что они дублировали значение какого-либо существующего уникального индекса. Warnings указывает количество попыток вставить значения столбцов, которые были проблемными. Предупреждения могут возникнуть в следующих условиях:

Вставка NULL в столбец, который был объявлен NOT NULL. Для многострочных заявлений INSERT или INSERT INTO ... SELECT заявлений столбец устанавливается в неявное значение по умолчанию для типа данных столбца. Это 0 для числовых типов, пустая строка ('') для строковых типов и значение «ноль» для типов дат и времени. INSERT INTO ... SELECT обрабатываются так же, как и многострочные вставки, поскольку сервер не проверяет результат набора из SELECT для проверки, возвращает ли он одну строку. (Для однострочного INSERT предупреждение не возникает, когда NULL вставляется в столбец NOT NULL. Вместо этого заявление завершается ошибкой.)
Установка числового столбца на значение, выходящее за пределы диапазона столбца. Значение усекается до ближайшей точки диапазона.
Назначение значения, такого как '10.34 a', числовому столбцу. Прицепленные нечисловые символы удаляются, и оставшаяся числовая часть вставляется. Если в строковом значении нет начальной числовой части, столбец устанавливается в 0.
Вставка строки в строковый столбец (CHAR, VARCHAR, TEXT или BLOB), превышающей максимальную длину столбца. Значение усекается до максимальной длины столбца.
Вставка значения в столбец даты или времени, которое не является допустимым для типа данных. Столбец устанавливается на соответствующее нулевое значение для типа.
Для INSERT примеров, включающих значения столбцов AUTO_INCREMENT, см. раздел 5.6.9 «Использование AUTO_INCREMENT».

Если INSERT вставляет строку в таблицу, имеющую столбец AUTO_INCREMENT, вы можете найти значение, использованное для этого столбца, с помощью SQL-функции LAST_INSERT_ID() или функции C API.

Примечание

Эти две функции не всегда ведут себя одинаково. Поведение INSERT заявлений относительно столбцов AUTO_INCREMENT обсуждается далее в разделе 14.15 «Функции информации», и .

Заявление INSERT поддерживает следующие модификаторы:

Если вы используете модификатор LOW_PRIORITY, выполнение INSERT откладывается до тех пор, пока другие клиенты не закончат чтение из таблицы. Это включает в себя других клиентов, которые начали чтение, пока существующие клиенты читают, и пока запрос INSERT LOW_PRIORITY ожидает. Поэтому клиент, который отправляет запрос INSERT LOW_PRIORITY, может ждать очень долго.

LOW_PRIORITY влияет только на движки хранения, использующие только блокировку на уровне таблицы (такие как MyISAM, MEMORY и MERGE).

Примечание

LOW_PRIORITY обычно не следует использовать с MyISAM таблицами, так как это отключает одновременные вставки. См. Раздел 10.11.3, “Одновременные вставки”.
Если вы укажете HIGH_PRIORITY, это переопределит эффект опции --low-priority-updates, если сервер был запущен с этой опцией. Это также приводит к тому, что одновременные вставки не используются. См. Раздел 10.11.3, “Одновременные вставки”.

HIGH_PRIORITY влияет только на движки хранения, использующие только блокировку на уровне таблицы (такие как MyISAM, MEMORY и MERGE).
Если вы используете модификатор IGNORE, игнорируются ошибки, которые возникают при выполнении запроса INSERT. Например, без IGNORE строка, дублирующая существующий индекс UNIQUE или значение PRIMARY KEY в таблице, вызывает ошибку дублирования ключа и запрос прерывается. С IGNORE строка отбрасывается, и ошибка не возникает. Игнорируемые ошибки генерируют предупреждения вместо этого.

IGNORE оказывает аналогичное действие на вставки в разнесённые таблицы, где не найдена ни одна таблица, соответствующая заданному значению. Без IGNORE такие запросы INSERT прерываются с ошибкой. При использовании INSERT IGNORE операция вставки беззвучно завершается для строк, содержащих несовпадение, но вставляет строки, которые соответствуют условию. Пример см. в Разделе 26.2.2, “Разбиение LIST”.

Преобразования данных, которые вызовут ошибки, прервут запрос, если IGNORE не указано. С IGNORE некорректные значения корректируются до ближайших значений и вставляются; генерируются предупреждения, но запрос не прерывается. Вы можете определить с помощью функции API C, сколько строк фактически было вставлено в таблицу.

Дополнительную информацию см. в Разделе «Влияние IGNORE на выполнение запроса».

Вы можете использовать REPLACE вместо INSERT, чтобы перезаписать старые строки. REPLACE является аналогом INSERT IGNORE при обработке новых строк, содержащих уникальные значения ключей, дублирующие старые строки: новые строки заменяют старые, а не отбрасываются. См. Раздел 15.2.12, “Запрос REPLACE”.
Если вы укажете ON DUPLICATE KEY UPDATE, и вставлена строка, которая приведет к дублированию значения в индексе UNIQUE или PRIMARY KEY, произойдет обновление UPDATE старой строки. Значение «затронутые строки» на строку равно 1, если строка вставляется как новая строка, 2, если существующая строка обновляется, и 0, если существующая строка устанавливается в свои текущие значения. Если вы укажете флаг CLIENT_FOUND_ROWS функции API C при подключении к mysqld, значение «затронутые строки» равно 1 (а не 0), если существующая строка устанавливается в свои текущие значения. См. Раздел 15.2.7.2, “Запрос INSERT ... ON DUPLICATE KEY UPDATE”.
INSERT DELAYED устарел в MySQL 5.6 и планируется к удалению. В MySQL 8.4 модификатор DELAYED принимается, но игнорируется. Используйте INSERT (без DELAYED) вместо этого. См. Раздел 15.2.7.3, “Запрос INSERT DELAYED”.