Sentencia INSERT

Invocación

Esta sentencia se puede incorporar a un programa de aplicación o emitir mediante el uso de sentencias de SQL dinámico. Se trata de una sentencia ejecutable que puede prepararse de forma dinámica.

Autorización

No se comprueban los privilegios GROUP para las sentencias INSERT estáticas.

Si el destino de la operación de inserción es un apodo, los privilegios para el objeto en la fuente de datos no se consideran hasta que la sentencia se ejecuta en la fuente de datos. En ese momento, el ID de autorización que se ha utilizado para conectarse con la fuente de datos debe disponer de los privilegios necesarios para realizar la operación en el objeto en la fuente de datos. El ID de autorización de la sentencia puede correlacionarse con un ID de autorización distinto en la fuente de datos.

Sintaxis

columnas-inclusión

Descripción

INTO nombre-tabla, nombre-vista, apodo o (selección completa)

Identifica el objeto de la operación de inserción. El nombre debe identificar uno de los objetos siguientes:

• Una tabla, vista o apodo que existe en el servidor de aplicaciones
• Una tabla o vista en el servidor remoto que se especifica mediante un nombre-objeto-remoto

El objeto no debe ser una tabla de catálogo, una tabla de consulta materializada mantenida por el sistema, una vista de una tabla de catálogo o una vista de sólo lectura, a menos que se haya definido un activador INSTEAD OF para la operación de inserción de la vista del asunto. Las filas que se insertan en un apodo se colocan en el objeto de fuente de datos al que hace referencia el apodo.

Si el objeto de la operación insertar es una selección completa, la selección completa se debe poder insertar, tal como se define en el elemento Notas de las vistas que se pueden insertar en la descripción de la sentencia CREATE VIEW.

Si el objeto de la operación de inserción es un apodo, los valores de variable de indicador ampliado DEFAULT y UNASSIGNED no deben utilizarse (SQLSTATE 22539).

Si no existe ningún activador INSTEAD OF para la operación de inserción en esta vista, no podrá insertarse un valor en una columna de vista que se haya obtenido de los elementos siguientes:

• Una constante, expresión o función escalar
• La misma columna de tabla base que otra columna de la vista.

Si el objeto de la operación de inserción es una vista con dichas columnas, debe especificarse una lista de nombres de columna y dicha lista no debe identificar estas columnas.

Una fila podrá insertarse en una vista o una selección completa que se ha definido utilizando UNION ALL si la fila satisface las restricciones de comprobación de exactamente una de las tablas base subyacentes. Si una fila satisface las restricciones de comprobación de más de una tabla, o no satisface la de ninguna tabla, se devolverá un error (SQLSTATE 23513).

Una fila no se puede insertar en una vista o selección completa que se haya definido con UNION ALL si alguna tabla base de la vista contiene un activador BEFORE y el activador BEFORE contiene una operación UPDATE, DELETE o INSERT o invoca una rutina que contiene ese tipo de operaciones (SQLSTATE 42987).

(nombre-columna,...)

Especifica las columnas para las que se proporcionan valores de inserción. Cada nombre debe identificar una columna de la tabla, vista o apodo especificado, o una columna de la selección completa. La misma columna no se puede identificar más de una vez. Si las variables de indicador ampliado no están habilitadas, no puede identificarse una columna que no pueda aceptar la inserción de valores (por ejemplo, una columna basada en una expresión).

La omisión de la lista de columnas es una especificación implícita de una lista en la que cada columna de la tabla (que no está oculta implícitamente) o vista, o cada elemento de la lista de selección de la selección completa se identifica en orden de izquierda a derecha. Esta lista se establece cuando se prepara la sentencia y, por lo tanto, no incluye las columnas que se han añadido a la tabla después de preparar la sentencia.

columnas-include

Especifica un conjunto de columnas que se incluyen, junto con las columnas de nombre-tabla o nombre-vista, en la tabla de resultados intermedia de la sentencia INSERT cuando está anidada en la cláusula FROM de una selección completa. Las columnas-include se añaden al final de la lista de columnas especificadas para nombre-tabla o nombre-vista.

INCLUDE

Especifica una lista de columnas que se van a incluir en la tabla de resultados intermedia de la sentencia INSERT. Esta cláusula sólo se puede especificar si la sentencia INSERT está anidada en la cláusula FROM de la selección completa.

nombre-columna

Especifica una columna de la tabla de resultados intermedia de la sentencia INSERT. El nombre no puede coincidir con el nombre de otra columna include ni de una columna en nombre-tabla o nombre-vista (SQLSTATE 42711).

tipo-datos

Especifica el tipo de datos de la columna include. El tipo de datos debe ser uno que reciba soporte de la sentencia CREATE TABLE.

VALUES

Especifica una o varias filas de valores que se deben insertar.

Cada fila especificada en la cláusula VALUES debe ser asignable a la lista de columnas implícita o explícita y las columnas identificadas en la cláusula INCLUDE, a menos que se utilice una variable de fila. Cuando se especifica una lista de valores de fila en paréntesis, el primer valor se inserta en la primera columna de la lista, el segundo valor en la segunda columna, etc. Cuando se especifica una expresión de fila, el número de campos en el tipo de fila debe coincidir con el número de nombres en la lista de columnas implícitas o explícitas.

expresión

Una expresión puede ser cualquier expresión definida en el tema Expresiones. Si la expresión es un tipo de fila, no debe aparecer entre paréntesis. Si la expresión es una variable, la variable del lenguaje principal puede incluir una variable de indicador o, en el caso de una estructura de sistema principal, una matriz de indicador, que esté habilitada para las variables de indicador ampliado. Si las variables de indicador ampliado están habilitadas, no deben utilizarse los valores para la variable de indicador ampliado por omisión (-5) o no asignado (-7) (SQLSTATE 22539) si cualquiera de las afirmaciones siguientes es cierta:

• La expresión es más compleja que una sola variable del lenguaje principal con conversiones explícitas.
• La columna de destino tiene un tipo de datos de tipo estructurado.

NULL

Especifica el valor nulo y sólo debe especificarse para las columnas con posibilidad de nulos.

DEFAULT

Especifica que se debe utilizar el valor por omisión. El resultado de especificar DEFAULT depende del modo en que se haya definido la columna, del siguiente modo:

• Si la columna se definió como columna generada basándose en una expresión, el sistema genera el valor de la columna de acuerdo con esa expresión.
• Si se utiliza la cláusula IDENTITY, el gestor de bases de datos genera el valor.
• Si se utiliza la cláusula ROW CHANGE TIMESTAMP, el gestor de bases de datos genera el valor para cada fila insertada como una indicación de fecha y hora que es exclusiva para cada partición de tabla en la partición de base de datos.
• Si se utiliza la cláusula WITH DEFAULT, el valor insertado será el valor tal como se ha definido para la columna (consulte cláusula-por-omisión en CREATE TABLE).
• Si se utiliza la cláusula NOT NULL y no la cláusula GENERATED, o no se utiliza WITH DEFAULT o se utiliza DEFAULT NULL, no se puede especificar la palabra clave DEFAULT para esa columna (SQLSTATE 23502).
• Cuando la inserción se realice en un apodo, la palabra clave DEFAULT se pasará por medio de la sentencia INSERT a la fuente de datos sólo si la fuente de datos da soporte a la palabra clave DEFAULT en su sintaxis de lenguaje de consulta.

expresión-fila

Especifica cualquier expresión de fila del tipo descrito en "Expresiones de fila" que no incluya un nombre de columna. El número de campos de la fila debe coincidir con el destino de la inserción y cada campo de la fila debe poderse asignar a la columna correspondiente.

WITH expresión-tabla-común

Define una expresión de tabla común para utilizarla con la selección completa que va a continuación.

selección completa

Especifica un conjunto de filas nuevas en la forma de la tabla de resultados de una selección completa. Puede haber una, más de una o ninguna. Si la tabla de resultados está vacía, SQLCODE se establece en +100 y SQLSTATE se establece en '02000'.

Cuando el objeto base de INSERT y el objeto base de la selección completa o cualquier subconsulta de la selección completa, son la misma tabla, la selección completa se evalúa por completo antes de insertar alguna fila.

El número de columnas de la tabla de resultados debe ser igual al número de nombres de la lista de columnas. El valor de la primera columna del resultado se inserta en la primera columna de la lista, el segundo valor en la segunda columna, etcétera.

Si la expresión que especifica el valor de una columna de resultados es una variable, la variable de lenguaje principal puede incluir una variable de indicador que esté habilitada para las variables de indicador ampliado. Si las variables de indicador ampliado están habilitadas y la expresión es más que una sola variable de lenguaje principal o una variable de lenguaje principal que se vaya a convertir de forma explícita, los valores DEFAULT o UNASSIGNED de variable de indicador ampliado (SQLSTATE 22539) no deben utilizarse. Los efectos de los valores DEFAULT o UNASSIGNED se aplican a las columnas de destino correspondientes de la selección completa.

WITH

Especifica el nivel de aislamiento en el que se ejecuta la sentencia.

RR

Lectura repetible

RS

Estabilidad de lectura

CS

Estabilidad del cursor

UR

Lectura no confirmada

El nivel de aislamiento por omisión de la sentencia es el nivel de aislamiento del paquete en el que está enlazada la sentencia. La cláusula WITH no afecta a los apodos, que siempre utilizan el nivel de aislamiento por omisión de la sentencia.

Normas

• Activadores: Las sentencias INSERT pueden dar lugar a que se ejecuten activadores. Un activador puede dar lugar a que se ejecuten otras sentencias o a que se generen condiciones de error basadas en los valores insertados. Si una operación de inserción en una vista da lugar a que se ejecute un activador INSTEAD OF, se comprobarán la validez, la integridad referencial y las restricciones de las actualizaciones que se han realizado en el activador y no las de la vista que ha dado lugar a la ejecución del activador o sus tablas subyacentes.
• Valores por omisión: El valor insertado en cualquier columna que no esté en la lista de columnas es el valor por omisión de la columna o nulo. Las columnas que no permiten valores nulos y no están definidas con NOT NULL WITH DEFAULT deben incluirse en la lista de columnas. De manera similar, si se inserta en una vista, el valor insertado en cualquier columna de la tabla base que no esté en la vista es el valor por omisión de la columna o nulo. De ahí que todas las columnas de la tabla base que no estén en la vista deben ser un valor por omisión o permitir valores nulos. El único valor que se puede insertar en una columna generada que se ha definido con la cláusula GENERATED ALWAYS es DEFAULT (SQLSTATE 428C9).
• Longitud: Si el valor de inserción de una columna es un número, la columna debe ser una columna numérica con la capacidad de representar la parte entera del número. Si el valor de inserción de una columna es una serie, la columna debe ser una columna de serie con un atributo de longitud que como mínimo sea tan grande como la longitud de la serie, o una columna de indicación de fecha y hora si la serie representa una fecha, hora o indicación de fecha y hora.
• Asignación: Los valores de inserción se asignan a las columnas de acuerdo con normas de asignación específicas.
• Validez: Si la tabla nombrada, o la tabla base de la vista nombrada, tiene uno o varios índices de unicidad, cada fila insertada en la tabla debe ajustarse a las restricciones impuestas por dichos índices. Si se nombra una vista cuya definición incluye WITH CHECK OPTION, cada fila insertada en la vista debe ajustarse a la definición de la vista. Para obtener información acerca de las normas que rigen esta situación, consulte CREATE VIEW.
• Integridad de referencia: Para cada restricción definida en una tabla, cada valor de inserción que no sea nulo de la clave foránea debe ser igual al valor de clave primaria de la tabla padre.
• Restricción de comprobación: Los valores de inserción deben cumplir las condiciones de control de las restricciones de comprobación definidas en la tabla. En una sentencia INSERT para una tabla con restricciones de comprobación definidas, se evalúan las condiciones de restricción una vez para cada fila que se inserta.
• Valores XML: Un valor que se inserta en una columna XML debe ser un documento XML con el formato correcto (SQLSTATE 2200M).
• Política de seguridad: si se protege la tabla identificada o la tabla base de la vista identificada con una política de seguridad, el ID de autorización de la sesión debe tener las credenciales de control de acceso basado en etiquetas (LBAC) que permiten:
  • Acceso de grabación a todas las columnas protegidas para las que se ha proporcionado explícitamente un valor de datos (SQLSTATE 42512)
  • Acceso de grabación para cualquier valor explícito proporcionado para una columna DB2SECURITYLABEL para las políticas de seguridad que se han creado con la opción RESTRICT NOT AUTHORIZED WRITE SECURITY LABEL (SQLSTATE 23523)

  El ID de autorización de la sesión también debe tener otorgada una etiqueta de seguridad para acceso de grabación para la política de seguridad si se utiliza un valor implícito para una columna DB2SECURITYLABEL (SQLSTATE 23523), lo cual puede suceder cuando:

  • No se proporciona explícitamente un valor para la columna DB2SECURITYLABEL
  • Se proporciona explícitamente un valor para la columna DB2SECURITYLABEL pero el ID de autorización de la sesión no tiene acceso de grabación para dicho valor y la política de seguridad se crea con la opción OVERRIDE NOT AUTHORIZED WRITE SECURITY LABEL
• Uso de variable de indicador ampliado: Si se habilita, los valores de variable de indicador negativos fuera del rango entre -1 y -7 no pueden ser una entrada (SQLSTATE 22010). Además, si se habilitan, los valores DEFAULT y UNASSIGNED de variable de indicador ampliado no deben aparecer en contextos en los que no estén soportados (SQLSTATE 22539).
• Variables de indicador ampliado: En una sentencia INSERT, un valor UNASSIGNED tiene como efecto establecer una columna en su valor por omisión.

  Si la columna de destino es una columna definida como GENERATED ALWAYS, se le debe asignar la palabra clave DEFAULT o los valores DEFAULT o UNASSIGNED basados en una variable de indicador ampliado (SQLSTATE 428C9).

Ejemplos

• Ejemplo 1:  Inserte un nuevo departamento con las siguientes especificaciones en la tabla DEPARTMENT:
  • El número de departamento (DEPTNO) es 'E31'
  • El nombre de departamento (DEPTNAME) es 'ARCHITECTURE'
  • Dirigido por (MGRNO) una persona con el número '00390'
  • Informa al departamento (ADMRDEPT) 'E01'.

     INSERT INTO DEPARTMENT
       VALUES ('E31', 'ARCHITECTURE', '00390', 'E01')

• Ejemplo 2:  Inserte un nuevo departamento en la tabla DEPARTMENT como en el ejemplo 1, pero no asigne ningún director al nuevo departamento.

     INSERT INTO DEPARTMENT (DEPTNO, DEPTNAME, ADMRDEPT )
       VALUES ('E31', 'ARCHITECTURE', 'E01')

• Ejemplo 3:  Inserte dos nuevos departamentos utilizando una sentencia en la tabla DEPARTMENT como en el ejemplo 2, pero no asigne ningún director al nuevo departamento.

     INSERT INTO DEPARTMENT (DEPTNO, DEPTNAME, ADMRDEPT)
       VALUES ('B11', 'PURCHASING', 'B01'),
              ('E41', 'DATABASE ADMINISTRATION', 'E01')

• Ejemplo 4:  Cree una tabla temporal MA_EMP_ACT con las mismas columnas que la tabla EMP_ACT. Cargue MA_EMP_ACT con las filas de la tabla EMP_ACT con un nuevo número de proyecto (PROJNO) que empieza por las letras 'MA'.

     CREATE TABLE MA_EMP_ACT
              ( EMPNO CHAR(6)  NOT NULL, 
               PROJNO CHAR(6)  NOT NULL, 
               ACTNO SMALLINT  NOT NULL, 
               EMPTIME DEC(5,2), 
               EMSTDATE DATE, 
               EMENDATE  DATE )
     INSERT INTO MA_EMP_ACT
       SELECT * FROM EMP_ACT
         WHERE SUBSTR(PROJNO, 1, 2) = 'MA'

• Ejemplo 5:  Utilice una sentencia del programa C para añadir un esqueleto de proyecto a la tabla PROJECT. Obtenga el número de proyecto (PROJNO), nombre de proyecto (PROJNAME), número de departamento (DEPTNO) y empleado responsable (RESPEMP) de las variables del lenguaje principal. Utilice la fecha actual como la fecha de inicio del proyecto (PRSTDATE). Asigne un valor null a las restantes columnas de la tabla.

     EXEC SQL INSERT INTO PROJECT (PROJNO, PROJNAME, DEPTNO, RESPEMP, PRSTDATE)
       VALUES (:PRJNO, :PRJNM, :DPTNO, :REMP, CURRENT DATE);

• Ejemplo 6:  Especifique una sentencia INSERT como referencia-tabla-cambio-datos dentro de una sentencia SELECT. Defina una columna include adicional cuyos valores se especifican en la cláusula VALUES, que luego se utiliza como una columna de clasificación para las filas insertadas.

     SELECT INORDER.ORDERNUM
       FROM NEW TABLE (INSERT INTO ORDERS(CUSTNO)INCLUDE (INSERTNUM INTEGER)
         VALUES(:CNUM1, 1), (:CNUM2, 2)) InsertedOrders
       ORDER BY INSERTNUM;

• Ejemplo 7: Utilice una sentencia del programa C para añadir un documento a la tabla DOCUMENTS. Obtenga valores para la columna ID del documento (DOCID) y la columna de datos del documento (XMLDOC) desde una variable del lenguaje principal que se vincula con un SQL TYPE IS XML AS BLOB_FILE.

     EXEC SQL INSERT INTO DOCUMENTS
       (DOCID, XMLDOC) VALUES (:docid, :xmldoc)

• Ejemplo 8: para las siguientes sentencias INSERT, suponga que la tabla SALARY_INFO está definida con tres columnas y que la última columna es una columna ROW CHANGE TIMESTAMP implícitamente oculta. En la sentencia siguiente, se hace referencia explícita a la columna implícitamente oculta en la lista de columnas y se proporciona un valor para dicha columna en la cláusula VALUES.

     INSERT INTO SALARY_INFO (LEVEL, SALARY, UPDATE_TIME)
       VALUES (2, 30000, CURRENT TIMESTAMP)

  La sentencia siguiente INSERT utiliza una lista de columnas implícitas. Una lista de columnas implícitas no incluye columnas implícitamente ocultas, de manera que la cláusula VALUES sólo contiene valores para las otras dos columnas.

     INSERT INTO SALARY_INFO VALUES (2, 30000)

  En este caso, la columna UPDATE_TIME debe definirse para que tenga un valor por omisión y el valor por omisión se utiliza para la fila que se inserta.