VALUES ( expression [, ...] ) [, ...]
    [ ORDER BY expression_de_tri [ ASC | DESC | USING operateur ] [, ...] ]
    [ LIMIT { nombre | ALL } ]
    [ OFFSET debut ] [ ROW | ROWS ] ]
    [ FETCH { FIRST | NEXT } [ nombre ] { ROW | ROWS } ONLY ]

Description

VALUES calcule une valeur de ligne ou un ensemble de valeurs de lignes spécifiées par des expressions. C'est généralement utilisé pour générer une « table statique » à l'intérieur d'une commande plus large mais elle peut aussi être utilisée séparément.

Quand plus d'une ligne est indiquée, toutes les lignes doivent avoir le même nombre d'éléments. Les types de données des colonnes de la table résultante sont déterminés en combinant les types explicites et les types inférés des expressions apparaissant dans cette colonne, en utilisant les mêmes règles que pour l'UNION (voir Section 10.5, « Constructions UNION, CASE et constructions relatives »).

À l'intérieur de grosses commandes, VALUES est autorisé au niveau de la syntaxe partout où la commande SELECT l'est. Comme la grammaire traite cette commande comme un SELECT, il est possible d'utiliser les clauses ORDER BY, LIMIT (ou de façon équivalente FETCH FIRST) et OFFSET avec une commande VALUES.

Paramètres

Notes

Évitez les listes VALUES comprenant un très grand nombre de lignes car vous pourriez rencontrer des problèmes comme un manque de mémoire et/ou des performances pauvres. Un VALUES apparaissant dans un INSERT est un cas spécial (parce que le type des colonnes est trouvé à partir de la table cible du INSERT et n'a donc pas besoin d'être deviné en parcourant la liste VALUES), du coup il peut gérer des listes plus importantes que dans d'autres contextes.

Exemples

Une simple commande VALUES :

VALUES (1, 'un'), (2, 'deux'), (3, 'trois');

Ceci renverra une table statique comprenant deux colonnes et trois lignes. En fait, c'est équivalent à :

SELECT 1 AS column1, 'un' AS column2
UNION ALL
SELECT 2, 'deux'
UNION ALL
SELECT 3, 'trois';

Plus généralement, VALUES est utilisé dans une commande SQL plus importante. L'utilisation la plus fréquente est dans un INSERT :

INSERT INTO films (code, titee, did, date_prod, genre)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drame');

Dans le contexte de la commande INSERT, les entrées d'une liste VALUES peuvent être DEFAULT pour indiquer que la valeur par défaut de la colonne ciblée doit être utilisée :

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comédie', '82 minutes'),
    ('T_601', 'Yojimbo', 106, DEFAULT, 'Drame', DEFAULT);

VALUES peut aussi être utilisé là où un sous-SELECT peut être écrit, par exemple dans une clause FROM :

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

UPDATE employes SET salaire = salaire * v.augmentation
  FROM (VALUES(1, 200000, 1.2), (2, 400000, 1.4)) AS v (no_dep, cible, augmentation)
  WHERE employees.no_dep = v.no_dep AND employees.ventes >= v.cible;

Notez qu'une clause AS est requise quand VALUES est utilisé dans une clause FROM, par exemple dans un SELECT. Il n'est pas nécessaire de spécifier les noms de toutes les colonnes dans une clause AS c'est une bonne pratique (les noms des colonnes par défaut pour VALUES sont column1, column2, etc dans PostgreSQL™ mais ces noms pourraient être différents dans d'autres SGBD).

Quand VALUES est utilisé dans INSERT, les valeurs sont toutes automatiquement converties dans le type de données de la colonne destination correspondante. Quand elle est utilisée dans d'autres contextes, il pourrait être nécessaire de spécifier le bon type de données. Si les entrées sont toutes des constantes litérales entre guillemets, convertir la première est suffisante pour déterminer le type de toutes :

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

Compatibilité

VALUES est conforme au standard SQL. Les clauses LIMIT et OFFSET sont des extensions PostgreSQL™ ; voir aussi SELECT(7).

Voir aussi

INSERT(7), SELECT(7)