Descrição

O comando INSERT insere novas linhas em uma tabela. Pode-se inserir 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 será todas as colunas da tabela em sua ordem declarada; ou os primeiros N nomes de coluna, se houver apenas N colunas fornecidas pela cláusula VALUES ou pela 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.

Cada coluna não presente na lista de colunas explícitas ou implícitas será preenchida com o valor padrão, seja seu valor padrão declarado, ou nulo se não houver nenhum.

Se a expressão de alguma coluna não for do tipo de dados correto, será feita uma tentativa de conversão automática de tipo de dados.

Os comandos INSERT em tabelas que não possuem índices de unicidade, não serão bloqueados por atividades concorrentes. As tabelas com índices de unicidade podem ser bloqueadas, se as sessões simultâneas executarem ações que bloqueiam ou modificam as linhas correspondentes aos valores de índice de unicidade que estão sendo inseridos; os detalhes são cobertos na Seção 63.5. A cláusula ON CONFLICT pode ser usada para indicar uma ação alternativa, quando acontece um erro de restrição de unicidade ou de violação de restrição de exclusão. (Veja Cláusula ON CONFLICT abaixo.)

A cláusula opcional RETURNING faz com que o comando INSERT calcule e retorne valor(es) com base em cada linha realmente inserida (ou atualizada, se uma cláusula ON CONFLICT DO UPDATE for usada). Serve principalmente para obter valores que foram fornecidos por padrão, como o número de uma sequência serial. No entanto, é permitida qualquer expressão que utilize as colunas da tabela. A sintaxe da lista da cláusula RETURNING é idêntica à da lista de saída do comando SELECT. Somente as linhas que foram inseridas ou atualizadas com sucesso serão retornadas. Por exemplo, se uma linha foi bloqueada, mas não foi atualizada porque uma cláusula ON CONFLICT DO UPDATE ... WHERE condição não foi satisfeita, a linha não será retornada.

É necessário possuir o privilégio INSERT na tabela para inserir linhas nela. Se a cláusula ON CONFLICT DO UPDATE estiver presente, também é necessário possuir o privilégio UPDATE na tabela.

Se for especificada uma lista de colunas, só é necessário possuir o privilégio INSERT nas colunas listadas. Da mesma forma, quando é especificada a cláusula ON CONFLICT DO UPDATE, só é necessário possuir o privilégio UPDATE na(s) coluna(s) listadas para serem atualizadas. Entretanto, a cláusula ON CONFLICT DO UPDATE também requer o privilégio SELECT em todas as colunas cujos valores são lidos na expressão ou condição da cláusula.

O uso da cláusula RETURNING requer o privilégio SELECT em todas as colunas mencionadas na cláusula. Se for usado o parâmetro consulta para inserir linhas de uma consulta, é claro que será necessário ter o privilégio SELECT em qualquer tabela ou coluna presente na consulta.

Parâmetros

Saídas

Após a conclusão bem-sucedida, o comando INSERT retorna uma etiqueta de comando na forma

INSERT oid contador

O contador é o número de linhas inseridas ou atualizadas. O oid é sempre zero (costumava ser o OID atribuído à linha inserida se contador fosse exatamente igual a um, e a tabela de destino fosse declarada WITH OIDS, e zero caso contrário, mas criar uma tabela WITH OIDS não tem mais suporte).

Se o comando INSERT contiver uma cláusula RETURNING, o resultado será semelhante ao de um comando SELECT contendo as colunas e valores definidos na lista RETURNING, calculado sobre a(s) linha(s) inserida(s) ou atualizada(s) pelo comando.

Notas

Se a tabela especificada for uma tabela particionada, cada linha será roteada para a partição apropriada e inserida nela. Se a tabela especificada for uma partição, ocorrerá um erro se uma das linhas de entrada violar a restrição de partição.

Também pode ser considerado o uso do comando MERGE, já que este comando permite misturar INSERT, UPDATE e DELETE em uma única declaração. Veja MERGE.

Exemplos

Inserir uma única linha na tabela films:

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

Neste exemplo, a coluna len é omitida, portanto, receberá o valor padrão:

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

Este exemplo usa a cláusula DEFAULT para as colunas de data em vez de especificar o 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 inserir uma linha que consiste inteiramente em valores padrão:

INSERT INTO films DEFAULT VALUES;

Para inserir várias linhas usando a sintaxe de VALUES de várias linhas:

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 exemplo insere algumas linhas na tabela films a partir da tabela tmp_films, que tem a mesma disposição de colunas que a tabela films:

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

Este exemplo insere nas colunas da matriz:

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

Insira uma única linha na tabela distributors, retornando o número de sequência gerado pela cláusula DEFAULT:

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

Incrementar a contagem de vendas do vendedor que gerencia a conta da “Acme Corporation”, registrando todas as linhas atualizadas junto com a hora corrente em uma tabela de registro de transações:

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;

Inserir ou atualizar novos distribuidores conforme apropriado. É assumido que foi definido um índice de unicidade que restringe os valores que aparecem na coluna did. Note que a tabela especial excluded é usada para referenciar os valores originalmente propostos para inserção:

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

Insira ou atualize novos distribuidores conforme descrito acima, retornando informações sobre quaisquer valores existentes que foram atualizados, juntamente com os novos dados inseridos. Note que os valores retornados para old_did e old_dname serão NULL para linhas sem conflito:

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;

Inserir um distribuidor, ou não fazer nada para as linhas propostas para inserção quando houver uma linha existente excluída (uma linha com uma restrição correspondentes em uma ou mais colunas após o disparo dos gatilhos para antes ou depois). Este exemplo assume que foi definido um índice de unicidade que restringe os valores que aparecem na coluna did:

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

Inserir ou atualizar novos distribuidores conforme apropriado. Este exemplo assume que foi definido um índice de unicidade que restringe os valores que aparecem na coluna did. A cláusula WHERE é usada para limitar as linhas realmente atualizadas (qualquer linha existente não atualizada ainda será bloqueada, mesmo assim):

-- Não atualizar os distribuidores existentes com base em um determinado CEP
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';

-- Especificar a restrição diretamente na instrução
-- (usa o índice para arbitrar a ação de DO NOTHING)
INSERT INTO distributors (did, dname) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING;

Inserir um novo distribuidor se possível; senão DO NOTHING. Este exemplo assume que foi definido um índice de unicidade que restringe os valores que aparecem na coluna did em um subconjunto de linhas em que a coluna booleana is_active é avaliada como true :

-- Esta instrução pode inferir um índice de unicidade parcial em "did"
-- com o predicado de "WHERE is_active", mas também poderia usar apenas
-- uma restrição de unicidade regular em "did"
INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE is_active DO NOTHING;

Conformidade

O comando INSERT está em conformidade com o padrão SQL, exceto que a cláusula RETURNING é uma extensão PostgreSQL, assim como a capacidade de usar WITH com INSERT, e a capacidade de especificar uma ação alternativa com ON CONFLICT. 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 consulta, não é permitido pelo padrão. Caso se prefira uma instrução que esteja mais em conformidade com o padrão SQL do que ON CONFLICT, veja MERGE.

O padrão SQL especifica que a cláusula OVERRIDING SYSTEM VALUE só pode ser especificado, se a coluna de identidade gerada sempre existe. O PostgreSQL permite a cláusula em qualquer caso, ignorando-a se não se aplicar.

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