INSERT

Nombre

INSERT -- crea nueva filas en una tabla

Sinopsis

INSERT INTO tabla [ ( columna [,  ...] ) ]
    { DEFAULT VALUES | VALUES ( { expresión | DEFAULT } [,  ...] ) [,  ...] | consulta }
    [ RETURNING * | expresión_salida [ [ AS ] nombre_salida ] [,  ...] ]

Descripción

INSERT insertar nuevas filas dentro de en una tabla. Se puede insertar una o más filas especificadas por expresiones de valores, o cero o más filas resultantes de una consulta.

Los nombres de columnas destino pueden ser listadas en cualquier orden. Si no se da una lista de nombres de columna, de forma predeterminada se toman todas las columnas de la tabla en su orden declarado; o los primeros N nombres de columnas, si hay solo N columnas provistas en la clausula VALUES o en la consulta. Los valores provistos por la clausula VALUES o la query son asociados con las columnas explícitas o implícitas de izquierda a derecha.

Cada columna no presente en la lista explicita o implícita será completada con los valores por defecto, ya sea los valores predeterminados declarados o nulos de lo contrario.

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

La clausula opcional RETURNING causa que el INSERT compute y retorne valores basados en la fila actualmente insertada. Esto es principalmente útil para obtener los valores que fueron provistos por defecto, como los números seriales de secuencia. Sin embargo, se permite cualquier expresión usando las columnas de la tabla. La sintaxis de la lista RETURNING es idéntica a la sintaxis de la lista de salida de SELECT.

Debe tener privilegios INSERT sobre la tabla para poder insertar en ella. Si se epecifíca una lista de columnas, solo se necesita privilegios INSERT en las columnas listadas. Usar la clausula RETURNING requiere privilegios SELECT en todas las columnas mencionadas en el RETURNING. Si se usa una clausula query para insertar filas desde una consulta, obviamente se necesita tener privilegios SELECT en cualquier tabla o columna usada en dicha consulta.

Parámetros

tabla

El nombre de una tabla existente (opcionalmente calificado por el esquema).

columna

El nombre de una columna de la tabla. Si es necesario, el nombre de columna puede ser calificado con un nombre de subcamo o subíndice de arreglo. (Insertando solo en algunos campos de una columna copuesta deja a los otros campos nulos.)

DEFAULT VALUES

Todas las columnas serán completadas con sus valores predeterminados.

expresión

Una expresión o valor a asignar a la correspondiente columna.

DEFAULT

La correspondiente columna será completada con sus valores predeterminados.

consulta

Una consulta (sentencia SELECT) que provee las filas a ser insertadas. Referirse a la sentencia SELECT para una descripción de la sintaxis.

expresión_salida

Una expresión para ser computada y retornada por el comando INSERT luego de que la fila es insertada. Le expresión puede usar cualquier nombre de columna de la tabla. Escribir * para devolver todas las columnas de las filas insertadas.

nombre_salida

Un nombre para usar para la columna devuelta.

Salidas

Al completarse exitosamente, un comando INSERT devuelve una etiqueta de comando de la forma

INSERT oid cantidad

La cantidad es el número de filas insertadas. Si cantidad es exactamente uno, y la tabla destino tiene OIDs, entonces oid es el OID asignado a la fila insertada. De lo contrario, oid es cero.

Si el comando INSERT contiene una clausula RETURNING, el resultado será similar al de una sentencia SELECT conteniendo las columnas y valores definidos en la lista RETURNING, computados sobre las filas insertadas por el comando.

Ejemplos

Insertar una fila individual en la tabla peliculas:

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

En este ejemplo, la columna duracion es omitida y por lo tanto tendrá el valor predeterminado:

INSERT INTO peliculas (codigo, titulo, did, fecha_prod, genero)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

Este ejemplo usa la clausula DEFAULT para la columna fecha en vez de especificar su valor:

INSERT INTO peliculas VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comedia', '82 minutes');
INSERT INTO peliculas (codigo, titulo, did, fecha_prod, genero)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

Para insertar una fila enteramente de valores predeterminados:

INSERT INTO peliculas DEFAULT VALUES;

Para insertar filas múltiples usando la sintaxis VALUES multi-fila:

INSERT INTO peliculas (codigo, titulo, did, fecha_prod, genero) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedia'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedia');

Este ejemplo inserta algunas filas en la tabla peliculas de la tabla tmp_peliculas con las misma disposición de columnas que peliculas:

INSERT INTO peliculas SELECT * FROM tmp_peliculas WHERE fecha_prod < '2004-05-07';

Este ejemplo inserta en columnas de arreglo:

-- Crear un tablero vacio de ta-te-ti de 3x3 
INSERT INTO tateti (juego, tablero[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- Los subindices en el ejemplo anterior no es realmente necesitado
INSERT INTO tateti (juego, tablero)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

Insertar una fila individual en la tabla distribuidores, retornando el número de secuencia generado por la clausula DEFAULT:

INSERT INTO distribuidores (did, nombre) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;

Compatibilidad

INSERT se ajusta al estándar SQL, exceptuando que la clausula RETURNING es una extensión PostgreSQL. También, el caso en que la lista de nombres de columnas es omitida, pero no todas las columnas son completadas con la clausula VALUES o consulta, no es permitido en el estándar.

Limitaciones posibles en la clausula consulta están documentadas en la sentencia SELECT.