Descrição

O comando VALUES computa um valor de linha, ou um conjunto de valores de linha, especificados por expressões de valor. É mais comumente usado para gerar uma “tabela constante” em um comando maior, mas pode ser usado sozinho.

Quando é especificada mais de uma linha, todas as linhas devem ter o mesmo número de elementos. Os tipos de dados das colunas da tabela resultante são determinados pela combinação dos tipos explícitos ou inferidos das expressões que aparecem na coluna, usando as mesmas regras da cláusula UNION (veja UNION, CASE e construções relacionadas).

Dentro de comandos maiores, VALUES é sintaticamente permitido em qualquer lugar onde o SELECT é permitido. Por ser tratado pela gramática como um SELECT, é possível usar as cláusulas ORDER BY, LIMIT (ou de forma equivalente, FETCH FIRST), e OFFSET no comando VALUES.

Parâmetros

Notas

Deve-se evitar listas VALUES com um número muito grande de linhas, porque podem acontecer falhas de memória insuficiente ou baixo desempenho. Quando VALUES aparece no comando INSERT, isto é um caso especial (porque os tipos de dados das colunas são conhecidos pela tabela de destino do INSERT, não precisando ser inferidos pela verificação da lista de VALUES), portanto, é possível lidar com listas maiores do que em outros contextos.

Exemplos

Um comando VALUES simples:

VALUES (1, 'um'), (2, 'dois'), (3, 'três');

Retorna uma tabela de duas colunas e três linhas, equivalente a:

SELECT 1 AS column1, 'um' AS column2
UNION ALL
SELECT 2, 'dois'
UNION ALL
SELECT 3, 'três';

Geralmente, VALUES é usado em um comando SQL maior. O uso mais comum é no comando INSERT:

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

No contexto do comando INSERT, pode ser escrito DEFAULT nas entradas da lista de VALUES, para indicar que deve ser usado o valor padrão da coluna nesta posição, em vez de especificar um valor:

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

VALUES também pode ser usado onde um sub-SELECT pode ser escrito, por exemplo em uma cláusula FROM:

SELECT f.*
  FROM films f,
      (VALUES
          ('MGM', 'Horror'),
          ('UA', 'Sci-Fi')
      ) AS t (studio, kind)
  WHERE f.studio = t.studio AND f.kind = t.kind;

UPDATE employees SET salary = salary * v.increase
  FROM (VALUES
           (1, 200000, 1.2),
           (2, 400000, 1.4)
       ) AS v (depno, target, increase)
  WHERE employees.depno = v.depno
    AND employees.sales >= v.target;

Note que a cláusula AS é necessária quando VALUES é usado em uma cláusula FROM, assim como seria para um SELECT. Não é necessário que a cláusula AS especifique nomes para todas as colunas, mas é uma boa prática fazê-lo. (Os nomes de coluna padrão para VALUES são column1, column2, etc., no PostgreSQL, mas estes nomes podem ser diferentes em outros sistemas de banco de dados.)

Quando VALUES é usado em um comando INSERT, os valores são todos convertidos automaticamente para o tipo de dados da coluna de destino correspondente. Quando usado em outros contextos, pode ser necessário especificar o tipo de dados correto. Se todas as entradas forem constantes cadeia de caracteres entre apóstrofos, converter a primeira é suficiente para determinar o tipo de dados assumido para todas:

SELECT * FROM machines
WHERE ip_address IN
    (VALUES
        ('192.168.0.1'::inet),
        ('192.168.0.10'),
        ('192.168.1.43')
    );

DO $$
DECLARE
    agora TIMESTAMP;
BEGIN
    VALUES (CURRENT_TIMESTAMP) INTO agora;
    RAISE NOTICE 'Data e hora: %', agora;
END $$ LANGUAGE plpgsql;
NOTA:  Data e hora: 2026-03-25 09:50:10.94829
DO

Conformidade

VALUES está em conformidade com o padrão SQL. LIMIT e OFFSET são extensões do PostgreSQL; veja também o comando SELECT.

Veja também