Descripción

INSERT inserta nuevas filas en una tabla. Se pueden insertar una o más filas especificadas por expresiones de valor, o cero o más filas resultantes de una consulta.

Los nombres de las columnas de destino se pueden enumerar en cualquier orden. Si no se proporciona ninguna lista de nombres de columnas, el valor por omisión son todas las columnas de la tabla en su orden declarado; o los primeros N nombres de columnas, si la cláusula VALUES o la consulta solo proporcionan N columnas. Los valores proporcionados por la cláusula VALUES o la consulta se asocian con la lista de columnas explícita o implícita de izquierda a derecha.

Cada columna que no esté presente en la lista de columnas explícita o implícita se llenará con un valor por omisión, ya sea su valor por omisión declarado o nulo (null) si no hay ninguno.

Si la expresión para cualquier columna no es del tipo de datos correcto, se intentará una conversión automática de tipo.

El comando INSERT en tablas que carecen de índices únicos no se bloqueará por la actividad concurrente. Las tablas con índices únicos podrían bloquearse si las sesiones concurrentes realizan acciones que bloquean o modifican filas que coinciden con los valores del índice único que se están insertando; los detalles se tratan en la Section 63.5. Se puede usar ON CONFLICT para especificar una acción alternativa a lanzar un error de violación de restricción única o de restricción de exclusión (consulta la ON CONFLICT Clause más abajo).

La cláusula opcional RETURNING hace que INSERT calcule y devuelva los valores basados en cada fila insertada realmente (o actualizada, si se utilizó una cláusula ON CONFLICT DO UPDATE). Esto es principalmente útil para obtener valores suministrados por valores por omisión, como un número de secuencia serial. Sin embargo, se permite cualquier expresión que utilice las columnas de la tabla. La sintaxis de la lista RETURNING es idéntica a la de la lista de salida de SELECT. Solo se devolverán las filas que se hayan insertado o actualizado correctamente. Por ejemplo, si una fila se bloqueó pero no se actualizó porque no se cumplió la condición de una cláusula ON CONFLICT DO UPDATE ... WHERE, la fila no se devolverá.

Debes tener el privilegio INSERT en una tabla para poder insertar en ella. Si ON CONFLICT DO UPDATE está presente, también se requiere el privilegio UPDATE en la tabla.

Si se especifica una lista de columnas, solo necesitas el privilegio INSERT en las columnas indicadas. Del mismo modo, cuando se especifica ON CONFLICT DO UPDATE, solo necesitas el privilegio UPDATE en las columnas que se listan para ser actualizadas. Sin embargo, todas las formas de ON CONFLICT también requieren el privilegio SELECT en cualquier columna cuyos valores se lean. Esto incluye cualquier columna mencionada en destino_conflicto (incluyendo las columnas a las que hace referencia la restricción árbitro), y cualquier columna mencionada en una ON CONFLICT DO UPDATE expresión, o en una condición de la cláusula WHERE.

El uso de la cláusula RETURNING requiere el privilegio SELECT en todas las columnas mencionadas en RETURNING. Si utilizas la cláusula de consulta para insertar filas a partir de una consulta, por supuesto necesitas tener el privilegio SELECT en cualquier tabla o columna utilizada en la consulta.

Parámetros

Salidas

Al completarse con éxito, un comando INSERT devuelve una etiqueta de comando de la forma

INSERT oid cantidad

La cantidad es el número de filas insertadas o actualizadas. oid es siempre 0 (solía ser el OID asignado a la fila insertada si la cantidad era exactamente uno y la tabla de destino se declaraba WITH OIDS, y 0 de lo contrario, pero la creación de una tabla WITH OIDS ya no se admite).

Si el comando INSERT contiene una cláusula RETURNING, el resultado será similar al de una sentencia SELECT que contiene las columnas y los valores definidos en la lista RETURNING, calculados sobre la(s) fila(s) insertada(s) o actualizada(s) por el comando.

Notas

Si la tabla especificada es una tabla particionada, cada fila se enruta a la partición adecuada y se inserta en ella. Si la tabla especificada es una partición, se producirá un error si una de las filas de entrada viola la restricción de partición.

También puedes considerar el uso de MERGE, ya que permite mezclar INSERT, UPDATE y DELETE dentro de una sola sentencia. Consulta la MERGE.

Ejemplos

Insertar una sola fila en la tabla films:

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes');

En este ejemplo, la columna len se omite y, por lo tanto, tendrá el valor por omisión:

INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

Este ejemplo utiliza la cláusula DEFAULT para las columnas de fecha en lugar de especificar un valor:

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes');
INSERT INTO films (code, title, did, date_prod, kind)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

Para insertar una fila que consiste enteramente en valores por omisión:

INSERT INTO films DEFAULT VALUES;

Para insertar varias filas utilizando la sintaxis VALUES de múltiples filas:

INSERT INTO films (code, title, did, date_prod, kind) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');

Este ejemplo inserta algunas filas en la tabla films desde una tabla tmp_films con el mismo diseño de columnas que films:

INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';

Este ejemplo inserta en columnas de matriz (array):

-- Crear un tablero de tres en línea (tictactoe) de 3x3 vacío
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- Los subíndices en el ejemplo anterior no son realmente necesarios
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

Insertar una sola fila en la tabla distributors, devolviendo el número de secuencia generado por la cláusula DEFAULT:

INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;

Incrementar el conteo de ventas del vendedor que gestiona la cuenta de Acme Corporation, y registrar toda la fila actualizada junto con la hora actual en una tabla de registro:

WITH upd AS (
  UPDATE employees SET sales_count = sales_count + 1 WHERE id =
    (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
    RETURNING *
)
INSERT INTO employees_log SELECT *, current_timestamp FROM upd;

Insertar o actualizar nuevos distribuidores según corresponda. Asume que se ha definido un índice único que restringe los valores que aparecen en la columna did. Ten en cuenta que se utiliza la tabla especial excluded para hacer referencia a los valores originalmente propuestos para la inserción:

INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;

Insertar o actualizar nuevos distribuidores como en el caso anterior, devolviendo información sobre los valores existentes que se actualizaron, junto con los nuevos datos insertados. Ten en cuenta que los valores devuelvos para old_did y old_dname serán NULL para las filas que no estén en conflicto:

INSERT INTO distributors (did, dname)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname
    RETURNING old.did AS old_did, old.dname AS old_dname,
              new.did AS new_did, new.dname AS new_dname;

Insertar un distribuidor, o no hacer nada para las filas propuestas para la inserción cuando existe una fila excluida existente (una fila con una columna o columnas restringidas que coinciden después de que se ejecuten los disparadores before row insert). El ejemplo asume que se ha definido un índice único que restringe los valores que aparecen en la columna did:

INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH')
    ON CONFLICT (did) DO NOTHING;

Insertar o actualizar nuevos distribuidores según corresponda. El ejemplo asume que se ha definido un índice único que restringe los valores que aparecen en la columna did. La cláusula WHERE se utiliza para limitar las filas realmente actualizadas (sin embargo, cualquier fila existente no actualizada se seguirá bloqueando):

-- No actualizar los distribuidores existentes basados en un determinado código postal
INSERT INTO distributors AS d (did, dname) VALUES (8, 'Anvil Distribution')
    ON CONFLICT (did) DO UPDATE
    SET dname = EXCLUDED.dname || ' (formerly ' || d.dname || ')'
    WHERE d.zipcode <> '21201';

-- Nombra una restricción directamente en la sentencia (utiliza el índice asociado
-- para arbitrar la acción DO NOTHING)
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

Insertar un nuevo distribuidor si es posible; de lo contrario, DO NOTHING. El ejemplo asume que se ha definido un índice único que restringe los valores que aparecen en la columna did en un subconjunto de filas donde la columna booleana is_active se evalúa como true:

-- Esta sentencia podría inferir un índice único parcial en «did» con un predicado de
-- «WHERE is_active», pero también podría usar una restricción única regular en «did»
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

Compatibilidad

INSERT cumple con el estándar SQL, excepto que la cláusula RETURNING es una extensión de PostgreSQL, al igual que la capacidad de usar WITH con INSERT, y la capacidad de especificar una acción alternativa con ON CONFLICT. Asimismo, el estándar no permite omitir la lista de nombres de columnas si no todas las columnas se llenan a partir de la cláusula VALUES o de la consulta. Si prefieres una sentencia que se ajuste más al estándar SQL que ON CONFLICT, consulta la MERGE.

El estándar SQL especifica que OVERRIDING SYSTEM VALUE solo se puede especificar si existe una columna de identidad que se genera siempre. PostgreSQL permite la cláusula en cualquier caso y la ignora si no es aplicable.

Las posibles limitaciones de la cláusula de consulta están documentadas en la SELECT.