mysql.h


INSERT

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
      [INTO] tbl_name [(col_name,...)]
      VALUES ({expression | DEFAULT},...),(...),...
      [ ON DUPLICATE KEY UPDATE col_name=expression, ... ]

O

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
      [INTO] tbl_name
      SET col_name={expression | DEFAULT}, ...
      [ ON DUPLICATE KEY UPDATE col_name=expression, ... ]

O

INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
      [INTO] tbl_name [(col_name,...)]
      SELECT ...

INSERT inserta nuevas filas en una tabla existente. Los formatos INSERT ... VALUES e INSERT ... SET, insertas filas basándose en los valores especificados explícitamente. El formato The INSERT ... SELECT inserta filas seleccionadas de otra tabla o tablas. El formato INSERT ... VALUES con una lista de múltiples valores está soportada por MySQL desde la versión 3.22.5. La sintaxis INSERT ... SET está soportada por MySQL desde la versión 3.22.10.

tbl_name es la tabla donde se insertarán las filas. Las columnas para las que la sentencia proporciona valores se pueden especificar de las siguientes formas:

  • Las lista de nombres de columnas o la cláusula SET indican las columnas explícitamente.
  • Si no se especifica una lista de columnas para INSERT ... VALUES o INSERT ... SELECT, se deben proporcionar valores para todas las columnas en la lista VALUES() o por SELECT. Si no se conoce el orden de las columnas dentro de la tabla, usar DESCRIBE tbl_name para encontrarlo.

Los valores de columnas se pueden proporcionar de varias formas:

  • Si se está ejecutando MySQL en el modo estricto (strict mode), a cualquier columna para la que no se proporcione un valor explícitamente se le asignará su valor por defecto (explícito o implícito). Por ejemplo, si se especifica una lista de columnas que no contiene el nombre de todas las columnas de la tabla, a las columnas sin nombre le serán asignados sus valores por defecto. La asignación de valores por defecto se describe en CREATE TABLE. Si se quiere que las sentencias INSERT generen un error a no ser que se especifiquen falores de forma explícita para todas las columnas que no tengan un valor por defecto, se debe usar el modo STRICT.
  • Se puede usar la palabra clave DEFAULT para poner una columna a su valor por defecto de forma explícita. (Nuevo en MySQL 4.0.3.) Esto hace más sencillo escribir sentencias INSERT que asignan valores a casi todas las columnas, porque permite la escritura de una lista VALUES incompleta, que no incluye un valor para cada columna de la tabla. En otro caso, se debería escribir la lista de nombres de columnas correspondiente a cada valor en la lista VALUES. A partir de MySQL 4.1.0, se puede usar DEFAULT(col_name) como una forma más general que puede ser usada en expresiones para obtener valores por defecto de columnas.
  • Si tanto la lista de columnas como la de VALUES están vacías, INSERT crea una fila en la que cada columna tendrá su valor por defecto: 
    mysql> INSERT INTO tbl_name () VALUES();
  • Se puede especificar una expresión expr para proporcionar un valor de columna. Esto forzará complejas conversiones de tipo si el de la expresión no coincide con el tipo de la columna, y la conversión de un valor dado puede provocar diferentes valores insertados dependiendo del tipo de la columna. Por ejemplo, insertar la cadena '1999.0e-2' en una columna INT, FLOAT, DECIMAL(10,6) o YEAR producirá los valores 1999, 19.9921, 19.992100 y 1999. El motivo es que el valor almacenado en una columna INT y YEAR sea 1999 es que la conversión de cadena a entero mira sólo la parte inicial de la cadena que se pueda considerar un valor entero o un año válido. Para columnas en punto flotante o punto fijo, la conversión de cadena a punto flotante tiene en cuenta la cadena completa como un valor válido en coma flotante. Una expresión expr se puede referir a cualquier columna que se haya asignado previamente en la lista de valores. Por ejemplo, se puede hacer esto, ya que el valor de col2 se refiere a col1, que ya ha sido asignado: 
    mysql> INSERT INTO tbl_name (col1,col2) VALUES(15,col1*2);
    Pero no se puede hacer esto, porque el valor para col1 se refiere a col2, que se asigna después de col1: 
    mysql> INSERT INTO tbl_name (col1,col2) VALUES(col2*2,15);
    La excepción es para columnas que contengan valores autoincrementados. Esto es debido a que el valor AUTO_INCREMENT se genera después de la asignación de cualquier otro valor, así que cualquier referencia a una columna AUTO_INCREMENT devolverá un 0.

La sentencia INSERT soporta los modificadores siguientes:

  • Si se especifica la palabra clave DELAYED, el servidor coloca la fila o filas a insertar en un búfer, y el cliente lanza la sentencia INSERT DELAYED y puede continuar. Si la tabla está ocupada, el servidor guarda las filas. Cuando la tabla queda libre, empieza a insertar filas, verificando periódicamente para ver si hay nuevas peticiones de lectura para la tabla. Si las hay, la cola de inserción retardada se suspende hasta que la tabla quede libre de nuevo. DELAYED se añadió en MySQL 3.22.5.
  • Si se especifica la palabra clave LOW_PRIORITY, la ejecución de la sentencia INSERT se retrasa hasta que no haya clientes leyendo de la tabla. Esto incluye a otros clientes que empiecen a leer mientras existan clientes leyendo, y mientras la sentencia INSERT LOW_PRIORITY está esperando. Por lo tanto, es posible que un cliente que lance una sentencia INSERT LOW_PRIORITY permanezca esperando por mucho tiempo (eventualmente para siempre) en un entorno con muchas lecturas. (Esto contrasta con lo que sucede con INSERT DELAYED, que permite al cliente continuar inmediatamente). LOW_PRIORITY no debe ser usado con tablas MyISAM que no permiten inserciones concurrentes.
  • Si se especifica la palabra clave HIGH_PRIORITY, se anula el efecto de la opción --low-priority-updates si el servidor fue arrancado con esa opción. Esto también hace que no se puedan usar inserciones concurrentes. HIGH_PRIORITY fue añadido en MySQL 3.23.11.
  • El valor de filas afectadas por una sentencia INSERT se puede obtener usando la función del API C mysql_affected_rows().
  • Si se especifica la palabra IGNORE en una sentencia INSERT, los errores que se produzcan mientras se ejecuta la sentencia se tratan con avisos. Por ejemplo, sin IGNORE una fila que duplique un valor de clave PRIMARY o UNIQUE existente en la tabla provovará un error y la sentencia será abortada. Con IGNORE, el error se ignora y la fila no será insertada. Las conversiones de datos que produzcan errores abortaán la sentencia si no se especifica IGNORE. Con IGNORE, los valores inválidos se ajustarán al valor más próximos y se insertarán; se producirán avisos pero la sentencia no se aborta. Se puede determinar cuantas filas fueron insertadas mediante la función del API mysql_info.

Si se especifica la cláusula ON DUPLICATE KEY UPDATE (nueva en MySQL 4.1.0), y se inserta una fila que puede provocar un valor duplicado en una clave PRIMARY o UNIQUE, se realiza un UPDATE (actualización) de la fila antigua. Por ejemplo, si se declara una columna 'a' como UNIQUE y ya contiene el valor 1, las dos sentencias siguientes tienen el mismo efecto:

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 filas afectadas es 1 si la fila es insertada como un nuevo registro y 2 si se actualiza un registro ya existente.

Nota: si la columna 'b' en única también, la sentencia INSERT puede ser equivalente a esta sentecia 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 varias filas, sólo una será actualizada. En general, se debe intentar evitar el uso de de la cláusula ON DUPLICATE KEY en tablas con múltiples claves UNIQUE.

Desde MySQL 4.1.1 es posible usar la función VALUES(col_name) en una cláusula UPDATE para referirse a los valores de columna en la parte INSERT de una sentencia INSERT ... UPDATE. En otras palabras, VALUES(col_name) en una cláusula UPDATE se refiere al valor col_name que será insertado si no existe un conflicto de clave duplicada. Esta función es especialmente corriente en inserciones de varias filas. La función VALUES sólo tiene sentido en sentencias INSERT ... UPDATE y devuelve NULL en otro caso.

Ejemplo:

mysql> INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6)
    -> ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);

El comando anterior es idéntico a las dos sentencias siguientes:

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 se usa ON DUPLICATE KEY UPDATE, la opción DELAYED se ignora.

Se puede encontrar el valor usado para una columna AUTO_INCREMENT usando la función LAST_INSERT_ID(). Desde el API C, usar la función mysql_insert_id. Sin embargo, notar que las dos funciones no se comportan de forma idéntica en todas las circunstancias.

Si se usa una sentencia INSERT ... VALUES con una lista de múltiples valores o INSERT ... SELECT, la sentencia devuelve una cadena de información con este formato:

Records: 100 Duplicates: 0 Warnings: 0

Records indica el número de filas procesadas por la sentencia. (No es necesariamente el número de filas insertadas. "Duplicates" puede ser distinto de cero.) "Duplicates" indica el número de filas que no pudieron ser insertadas porque contienen algún valor para un índice único ya existente. "Warnings" indica el número de intentos de inserción de valores de columnas que han causado algún tipo de problemas. Se pueden producir "Warnings" bajo cualquiera de las siguientes condiciones:

  • Inserción de NULL en una columna declarada como NOT NULL. Para sentencias INSERT de varias filas o en sentencias INSERT ... SELECT, se asigna el valor por defecto apropiado al tipo de columna. Ese valor es 0 para tipos numéricos, la cadena vacía ('') para tipos cadena, y el valor "cero" para tipos de fecha y tiempo.
  • Asignación de un valor fuera de rango a una columna numérica. El valor se recorta al extremo apropiado del rango.
  • Asignación de un valor como '10.34 a' a un campo numérico. La parte añadida se ignora y se inserta sólo la parte numérica inicial. Si el valor no tiene sentido como un número, el valor asignado es 0.
  • Inserción de un valor a una columna de cadena (CHAR, VARCHAR, TEXT o BLOB) que exceda la longitud máxima para la columna. El valor se trunca a la longitud máxima de la columna.
  • Inserción de un valor dentro de una columna de fecha o tiempo que sea ilegal para el tipo de columna. Se asigna a la columna el valor apropiado de cero, según su tipo.

Si se usa el API C, la cadena de información se puede obtener mediante la función mysql_info.

Ver también: INSERT ... SELECT e INSERT DELAYED