13.2.5 INSERT Statement — MySQL 5.7

13.2.5 Оператор 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)] ...
    [ON DUPLICATE KEY UPDATE assignment_list]

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
    [INTO] tbl_name
    [PARTITION (partition_name [, partition_name] ...)]
    SET assignment_list
    [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 ...
    [ON DUPLICATE KEY UPDATE assignment_list]

value:
    {expr | DEFAULT}

value_list:
    value [, value] ...

assignment:
    col_name = value

assignment_list:
    assignment [, assignment] ...

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

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

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

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

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

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

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

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

Если режим строгой SQL не включен, любой столбец, для которого явно не указано значение, устанавливается в свое значение по умолчанию (явное или неявное). Например, если вы указываете список столбцов, который не содержит все столбцы таблицы, неименованные столбцы устанавливаются в свои значения по умолчанию. Назначение значений по умолчанию описано в разделе 11.6 «Значения по умолчанию типов данных». См. также раздел 1.6.3.3 «Ограничения на некорректные данные».
Если режим строгой SQL включен, оператор INSERT генерирует ошибку, если он не указывает явное значение для каждого столбца, не имеющего значения по умолчанию. См. раздел 5.1.10 «Режим SQL сервера».
Если и список столбцов, и список VALUES пусты, INSERT создаёт строку, устанавливая каждый столбец в свое значение по умолчанию:
```
INSERT INTO tbl_name () VALUES();
```
Если режим строгой SQL не включён, MySQL использует неявное значение по умолчанию для любого столбца, для которого явно не определено значение по умолчанию. Если режим строгой SQL включен, возникает ошибка, если у любого столбца нет значения по умолчанию.
Используйте ключевое слово DEFAULT, чтобы явно установить столбец в его значение по умолчанию. Это упрощает написание операторов INSERT, которые присваивают значения всем, кроме нескольких столбцов, так как это позволяет избежать написания неполного списка VALUES, который не включает значение для каждого столбца в таблице. В противном случае вам нужно предоставить список имен столбцов, соответствующих каждому значению в списке VALUES.
Если вставляется сгенерированный столбец, единственно допустимое значение — DEFAULT. Подробности о сгенерированных столбцах см. в разделе 13.1.18.7 «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 в данном контексте. Ни один из них не подразумевает ничего о количестве списков значений или количестве значений в каждом списке. Оба можно использовать как для одного списка значений, так и для нескольких, независимо от количества значений в каждом списке.

END_OF_DOCUMENT_MARKER ```

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

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

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 см. в Разделе 3.6.9, «Использование AUTO_INCREMENT».

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

Примечание

Эти две функции не всегда ведут себя идентично. Поведение операторов INSERT по отношению к столбцам AUTO_INCREMENT более подробно описано в Разделе 12.15, «Функции информации», и .

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

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

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

Примечание

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

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

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

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

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

Можно использовать REPLACE вместо INSERT для перезаписи старых строк. REPLACE является аналогом INSERT IGNORE при обработке новых строк, содержащих уникальные значения ключей, которые дублируют старые строки: новые строки заменяют старые, а не отбрасываются. См. Раздел 13.2.8, «Оператор REPLACE».
Если вы укажете ON DUPLICATE KEY UPDATE, и строка вставляется, что приведет к дублированию значения в индексе UNIQUE или PRIMARY KEY, происходит обновление UPDATE старой строки. Значение affected-rows на строку равно 1, если строка вставляется как новая строка, 2, если существующая строка обновляется, и 0, если существующая строка устанавливается в текущие значения. Если вы укажете флаг CLIENT_FOUND_ROWS функции C API при подключении к mysqld, значение affected-rows равно 1 (не 0), если существующая строка устанавливается в текущие значения. См. Раздел 13.2.5.2, «Оператор INSERT ... ON DUPLICATE KEY UPDATE».
INSERT DELAYED устарел в MySQL 5.6 и должен быть удален. В MySQL 5.7 модификатор DELAYED принимается, но игнорируется. Используйте INSERT (без DELAYED) вместо него. См. Раздел 13.2.5.3, «Оператор INSERT DELAYED».

Заявление INSERT, влияющее на разбиение таблицы с использованием механизма хранения, такого как MyISAM, который использует блокировки на уровне таблицы, блокирует только те разделы, в которые фактически вставляются строки. (Для механизмов хранения, таких как InnoDB, которые используют блокировку на уровне строк, блокировка разделов не происходит.) Дополнительную информацию см. в разделе 22.6.4, «Разбиение и блокировки».