INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[(col_name
,...)] VALUES ({expr
| DEFAULT},...),(...),... [ ON DUPLICATE KEY UPDATEcol_name
=expr
, ... ]
O:
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
SETcol_name
={expr
| DEFAULT}, ... [ ON DUPLICATE KEY UPDATEcol_name
=expr
, ... ]
O:
INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[(col_name
,...)] SELECT ... [ ON DUPLICATE KEY UPDATEcol_name
=expr
, ... ]
INSERT
inserta nuevos registros en una tabla
existente. Las formas INSERT ... VALUES
y
INSERT ... SET
del comando insertan registros
basados en valores explícitamente especificados. La forma
INSERT ... SELECT
inserta registros
seleccionados de otra tabla o tablas. INSERT ...
SELECT
se discute en Sección 13.2.4.1, “Sintaxis de INSERT ... SELECT
”.
tbl_name
es la tabla en que los
registros deben insertarse. Las columnas para las que el comando
proporciona valores pueden especificarse como sigue:
La lista de nombres de columna o la cláusula
SET
indican las columnas explícitamente.
Si no especifica la lista de columnas para INSERT
... VALUES
o INSERT ... SELECT
,
los valores para cada columna en la tabla deben
proporcionarse en la lista VALUES
o por
el SELECT
. Si no sabe el orden de las
columnas en la tabla, use DESCRIBE
para
encontrarlo.
tbl_name
Los valores de columna pueden darse de distintos modos:
Si no está ejecutando el modo estricto, cualquier columna
que no tenga un valor asignado explícitamente recibe su
valor por defecto (explícito o implícito). Por ejemplo, si
especifica una lista de columnas que no nombra todas las
columnas en la tabla, las no nombradas reciben sus valores
por defecto. Los valores por defecto asignados se describen
en Sección 13.1.5, “Sintaxis de CREATE TABLE
”. Consulte
Sección 1.7.6.2, “Restricciones (constraints) sobre datos inválidos”.
Si quiere que un comando INSERT
genere un
error a no ser que especifique explícitamente valores para
todas las columnas que no tienen un valor por defecto, debe
usar modo STRICT
. Consulte
Sección 5.3.2, “El modo SQL del servidor”.
Use DEFAULT
para asignar a una columna
explícitamente su valor por defecto. Esto hace más fácil
escribir comandos INSERT
que asignan
valores a todas las columnas excepto unas pocoas, ya que le
permite evitar la escritura de una lista de valores
VALUES
incompleta. De otro modo, tendría
que escribir la lista de los nombres de columna
correspondientes a cada valor en la lista
VALUES
.
En MySQL 5.0, puede usar
DEFAULT(
como forma más general que puede usarse en expresiones para
producir un valor por defecto de una columna.
col_name
)
Si la lista de columnas y la lista VALUES
están vacías, INSERT
crea un registro
con cada conjunto de columnas con sus valores por defecto:
mysql> INSERT INTO tbl_name
() VALUES();
En modo STRICT
obtendrá un error si una
columna no tiene un valor por defecto. De otro modo, MySQL
usará el valor implícito para cualquier columna sin un
valor explícito por defecto definido.
Puede especificar una expresión
expr
para proporcionar un valor
de columna. Esto puede involucar convesión de tipos si el
tipo de la expresión no coincide con el tipo de la columna,
y la conversión de un valor dado puede resultar en
distintos valores insertados dependiendo del tipo de
columna. Por ejmplo, insertar la cadena
'1999.0e-2'
en una columna
INT
, FLOAT
,
DECIMAL(10,6)
, o YEAR
resulta en los valores 1999
,
19.9921
, 19.992100
, y
1999
insertados, respectivamente. La
razón de que el valor almacenado en las columnas
INT
y YEAR
sea
1999
es que la conversión
cadena-a-entero consulta sólo el trozo de la parte inicial
de la cadena que se puede considerar como un entero válido
o año. Para las columnas de coma flotante o punto fijo, la
conversión cadena-a-coma-flotante considera la cadena
entera un valor válido.
Una expresión expr
puede
referirse a cualquier columna que se haya asignado antes en
una lista de valores. Por ejemplo, puede hacer esto porque
el valor para col2
se refiere a
col1
, que se ha asignado préviamente:
mysql> INSERT INTOtbl_name
(col1
,col2
) VALUES(15,col1
*2);
Pero lo siguiente no es legal, ya que el valor para
col1
se refiere a
col2
, que se asigna tras
col1
:
mysql> INSERT INTOtbl_name
(col1
,col2
) VALUES(col2
*2,15);
Una excepción involucra a columnas que contienen valores
AUTO_INCREMENT
. Como el valor
AUTO_INCREMENT
se genera tras otras
asignaciones de valores, cualquier referencia a una columna
AUTO_INCREMENT
en la asignación retorna
un 0.
El comando INSERT
soporta los siguientes
modificadores:
Si usa la palabra DELAYED
, el servidor
pone el registro o registros a ser insertados en un búffer,
y el cliente realizando el comando INSERT
DELAYED
puede continuar. Si la tabla está en uso,
el servidor trata los registros. Cuando la tabla se libera,
el servidor comienza a insertar registros, chequeando
periódicamente para ver si hay alguna petición de lectura
para la tabla. Si la hay, la cola de registros retardados se
suspende hasta que la tabla se libera de nuevo. Consulte
Sección 13.2.4.2, “Sintaxis de INSERT DELAYED
”.
Si usa la palabra LOW_PRIORITY
, la
ejecución de INSERT
se retrasa hasta que
no hay otros clientes leyendo de la tabla. Esto incluye a
otros clientes que comiencen a leer mientras que los
clientes existentes están leyendo, y meintras el comando
INSERT LOW_PRIORITY
está en espera. Es
posible, por lo tanto, para un cliente que realice un
comando INSERT LOW_PRIORITY
esperar
durante mucho tiempo (o incluso para siempre) en un entorno
de muchas lecturas. (Esto es un contraste de INSERT
DELAYED
, que deja al cliente continuar. Consulte
Sección 13.2.4.2, “Sintaxis de INSERT DELAYED
”.) Tenga en cuenta que
LOW_PRIORITY
no debe usarse normalmente
con tablas MyISAM
y que hacerlo
deshabilita inserciones concurrentes. Consulte
Sección 14.1, “El motor de almacenamiento MyISAM
”.
Si especifica HIGH_PRIORITY
, deshabilita
el efecto de la opción
--low-priority-updates
si el servidor se
arrancó con esa opción. Hace que las insecionces
concurrentes no se usen.
Los valores afectados por un INSERT
pueden usarse usando la función
mysql_affected_rows()
de la API de C.
Consulte Sección 24.2.3.1, “mysql_affected_rows()
”.
Si usa la palabra IGNORE
en un comando
INSERT
, los errores que ocurren mientras
se ejecuta el comando se tratan como advertencias. Por
ejemplo, sin IGNORE
, un registro que
duplique un índice UNIQUE
existente o
valor PRIMARY KEY
en la tabla hace que un
error de clave duplicada en el comando se aborte. Con
IGNORE
, el registro todavía no se
inserta, pero no se muestra error. Las conversionse de datos
dispararían errores y abortarían el comando si no se
sepecificara IGNORE
. Con
IGNORE
, los valores inválidaos se
ajustan al valor más cercano y se insertan; las
advertencias se producen pero el comando no se aborta. Puede
determinar con la función mysql_info()
de la API de C cuántos registros se insertan realmente en
la tabla.
Si especifica ON DUPLICATE KEY UPDATE
, y se
inserta un registro que duplicaría un valor en un índice
UNIQUE
o PRIMARY KEY
, se
realiza un UPDATE
del antiguo registro. Por
ejemplo, si la columna a
se declara como
UNIQUE
y contiene el valor
1
, los siguientes dos comandos tienen efectos
idénticos:
mysql> INSERT INTO table (a,b,c) VALUES (1,2,3) -> ON DUPLICATE KEY UPDATE c=c+1; mysql> UPDATE table SET c=c+1 WHERE a=1;
El valor de registros afectados es 1 si el registros se inserta como un nuevo registro y 2 si un valor existente se actualiza.
Nota: Si la columna
b
es única, el INSERT
sería equivalente a este comando UPDATE
:
mysql> UPDATE table SET c=c+1 WHERE a=1 OR b=2 LIMIT 1;
Si a=1 OR b=2
se cumple para varios
registros, sólo un registro se actualiza.
En general, debería intentar evitar usar una cláusula
ON DUPLICATE KEY
en tablas con claves únicas
múltiples.
MySQL 5.0 permite el uso de la función
VALUES(col_name)
en la cláusula
UPDATE
que se refiere a los valores de
columna de la porción INSERT
del comando
INSERT ... UPDATE
. En otras palabras,
VALUES(col_name)
en la cláusula
UPDATE
se refiere al valor de
col_name
que se insertarían, no
ocurre conflicto de clave duplicada. Esta función es
especialmente útil en inserciones de múltiples registros. La
función VALUES()
tiene sentido sólo en
comandos INSERT ... UPDATE
y retorna
NULL
de otro modo.
Ejemplo:
mysql> INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6) -> ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);
Este comando es idéntico a los siguientes dos comandos:
mysql> INSERT INTO table (a,b,c) VALUES (1,2,3) -> ON DUPLICATE KEY UPDATE c=3; mysql> INSERT INTO table (a,b,c) VALUES (4,5,6) -> ON DUPLICATE KEY UPDATE c=9;
Cuando usa ON DUPLICATE KEY UPDATE
, la
opción DELAYED
se ignora.
Puede encontrar el valor usado para una columna
AUTO_INCREMENT
usando la función SQL
LAST_INSERT_ID()
. Desde la API C, use la
función mysql_insert_id()
. Sin embargo,
debe tener en cuenta que las dos funciones no siempre se
comportan idénticamente. El comportamiento de comandos
INSERT
respecto a columnas
AUTO_INCREMENT
se discute en
Sección 12.9.3, “Funciones de información” y
Sección 24.2.3.34, “mysql_insert_id()
”.
Si usa un comando INSERT ... VALUES
con
listas de múltiples valores o INSERT ...
SELECT
, el comando retorna una cadena de información
en este formato:
Records: 100 Duplicates: 0 Warnings: 0
Records
indica el número de registros
procesados por el comando. (Este no es necesariamente el número
de registros realmente insertados, ya que
Duplicates
puede ser distinto a cero.)
Duplicates
indica el número de registros que
no pueden insertarse ya que duplicarían algunos valores de
índice únicos existentes Warnings
indicata
el número de intentos para insertar valores de columna que
fueron problemáticos por algo. Las advertencias pueden ocurrir
bajo cualquiera de las siguientes condiciones:
Insertar NULL
en una columna que se ha
declarado NOT NULL
. Para comandos
INSERT
de múltiples columnas o comandos
INSERT INTO... SELECT
, la columna se
asigna con el valor por defecto para el tipo de datos de la
columna. Este es 0
para tipos numéricos,
la cadena vacía (''
) para tipos de
cadenas, y el valor “cero” para tipos de fecha
y hora. Los comandos INSERT INTO ...
SELECT
se tratan del mismo modo que inserciones de
múltiples registros porque el servidor no examina el
resultado del SELECT
para ver si retorna
o no un único registro. (para un único registro
INSERT
, no hay ninguna advertencia cuando
NULL
se inserta en una columna
NOT NULL
. En lugar de eso, el comando
falla con un error.)
Poner en una columna numérica un valor fuera del rango de la columna. El valor se redondea al punto final del rango más cercano.
Asigne un valor tal como '10.34 a'
a una
columna numérica. El texto final se elimina y la parte
numérica se inserta. Si el valor de cadena no tiene parte
inicial numérica, la columna se pone a
0
.
Insertar una cadena en una columna de cadena
(CHAR
, VARCHAR
,
TEXT
, o BLOB
) que
excede la maxima longitud de la columna. El valor se trunca
a la máxima longitud de la columna.
Insertar un valor en una columna de fecha u hora que es ilegal para el tipo de la columna. La columna se asigna con el valor cero apropiado para el tipo.
Si usa la API de C, la cadena de información puede obtenerse
invocando la función mysql_info()
Consulte
Sección 24.2.3.32, “mysql_info()
”.
Ésta es una traducción del manual de referencia de MySQL, que puede encontrarse en dev.mysql.com. El manual de referencia original de MySQL está escrito en inglés, y esta traducción no necesariamente está tan actualizada como la versión original. Para cualquier sugerencia sobre la traducción y para señalar errores de cualquier tipo, no dude en dirigirse a mysql-es@vespito.com.