INSERT

Descrição

O comando INSERT insere novas linhas na tabela. Podem ser inseridas uma ou mais linhas especificadas por expressões de valor, ou zero ou mais linhas resultantes de uma consulta.

Os nomes das colunas de destino podem ser listados em qualquer ordem. Se não for fornecida nenhuma lista de nomes de colunas, o padrão é usar todas as colunas da tabela na ordem em que foram declaradas; ou os primeiros N nomes de colunas, se existirem apenas N colunas fornecidas na cláusula VALUES ou na consulta. Os valores fornecidos pela cláusula VALUES ou pela consulta são associados à lista de colunas explícita ou implícita da esquerda para a direita.

As colunas que não estão presentes na lista de colunas explícita ou implícita são preenchidas com o valor padrão, seja o valor padrão declarado ou nulo se não houver nenhum.

Se a expressão para alguma coluna não for do tipo de dado correto, será tentada uma conversão de tipo automática.

A cláusula opcional RETURNING faz com que o comando INSERT compute e retorne valores baseados em cada linha realmente inserida. Sua utilidade principal é obter valores fornecidos por padrão, como o número seqüencial de uma coluna serial. Entretanto, é permitida qualquer expressão que utilize as colunas da tabela. A sintaxe da lista RETURNING é idêntica à da lista de saída do comando SELECT. [1]

É necessário possuir o privilégio INSERT na tabela para poder inserir linhas, e o privilégio SELECT para utilizar RETURNING. Se for utilizada a cláusula consulta para inserir linhas a partir de uma consulta, também será necessário possuir o privilégio SELECT em todas as tabelas usadas pela consulta.

Parâmetros

Saídas

Ao terminar bem-sucedido, o comando INSERT retorna uma linha de fim de comando na forma

INSERT oid contador

O contador é o número de linhas inseridas. Se contador for igual a um, e a tabela de destino possuir OIDs, então oid será o OID atribuído à linha inserida, senão oid será zero.

Se o comando INSERT contiver a cláusula RETURNING, o resultado será semelhante ao de um comando SELECT contendo as colunas e valores definidos na lista RETURNING, computados sobre as linhas inseridas pelo comando.

Exemplos

Inserir uma única linha na tabela filmes:

INSERT INTO filmes VALUES
    ('UA502', 'Bananas', 105, '1971-07-13', 'Comédia', '82 minutes');

No exemplo abaixo a coluna duracao é omitida e, portanto, receberá o valor padrão:

INSERT INTO filmes (cod, titulo, id_dist, data_prod, tipo)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');

O exemplo abaixo utiliza a cláusula DEFAULT para a coluna data_prod em vez de especificar um valor.

INSERT INTO filmes VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comédia', '82 minutes');
INSERT INTO filmes (cod, titulo, id_dist, data_prod, tipo)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama');

Para inserir uma linha consistindo inteiramente de valores padrão:

INSERT INTO filmes DEFAULT VALUES;

Para inserir várias linhas utilizando a sintaxe de VALUES multilinha:

INSERT INTO filmes (cod, titulo, id_dist, data_prod, tipo) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comédia'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comédia');

O exemplo abaixo insere algumas linhas na tabela filmes a partir da tabela temp_filmes com a mesma disposição de colunas da tabela filmes:

INSERT INTO filmes SELECT * FROM temp_filmes WHERE data_prod < '2004-05-07';

O exemplo mostrado abaixo insere em colunas de matriz:

-- Criar um tabuleiro vazio de 3x3 posições para o Jogo da Velha
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- Os índices do exemplo acima não são realmente necessários
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

Inserir uma única linha na tabela distribuidores retornando o número seqüencial gerado pela cláusula DEFAULT:

INSERT INTO distribuidores (id_dist, nome_dist) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING id_dist;

CREATE TABLE t1
    (c1 serial, c2 text);
CREATE TABLE t1_log
    (c1 int, c2 text, c3 timestamp DEFAULT current_timestamp);

CREATE OR REPLACE FUNCTION insere_t1 (c2 text) RETURNS boolean AS $$
DECLARE
    r1 t1.c1%TYPE;
    r2 t1.c2%TYPE;
BEGIN
    INSERT INTO t1 VALUES (DEFAULT, c2) RETURNING * INTO r1, r2;
    INSERT INTO t1_log VALUES (r1, r2);
    RETURN FOUND;
END;
$$ LANGUAGE plpgsql;

SELECT insere_t1('Maria');
SELECT insere_t1('Manuel');
SELECT insere_t1('Joaquim');
\pset border 2
\pset title 'Tabela t1'
SELECT * FROM t1;
\pset title 'Tabela t1_log'
SELECT * FROM t1_log;

# psql -h Kubuntu -U teste -f insere_t1.sql -o insere_t1.out -q teste
# cat insere_t1.out
   Tabela t1
+----+---------+
| c1 |   c2    |
+----+---------+
|  1 | Maria   |
|  2 | Manuel  |
|  3 | Joaquim |
+----+---------+
(3 linhas)

                Tabela t1_log
+----+---------+----------------------------+
| c1 |   c2    |             c3             |
+----+---------+----------------------------+
|  1 | Maria   | 2007-02-10 18:06:35.756902 |
|  2 | Manuel  | 2007-02-10 18:06:35.760499 |
|  3 | Joaquim | 2007-02-10 18:06:35.761458 |
+----+---------+----------------------------+
(3 linhas)

Compatibilidade

O comando INSERT está em conformidade com o padrão SQL, exceto pela cláusula RETURNING que é uma extensão do PostgreSQL. Além disso, o caso em que a lista de nomes de colunas é omitida, mas nem todas as colunas são preenchidas a partir da cláusula VALUES ou da consulta, não é permitido pelo padrão.

As possíveis limitações da cláusula consulta estão documentadas no comando SELECT.