[ WITH [ RECURSIVE ] requête_with [, ...] ]
INSERT INTO nom_table [ ( nom_colonne [, ...] ) ]
    { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | requête }
    [ RETURNING * | expression_sortie [ [ AS ] nom_sortie ] [, ...] ]

Description

INSERT insère de nouvelles lignes dans une table. Vous pouvez insérer une ou plusieurs lignes spécifiées par les expressions de valeur, ou zéro ou plusieurs lignes provenant d'une requête.

L'ordre des noms des colonnes n'a pas d'importance. Si aucune liste de noms de colonnes n'est donnée, toutes les colonnes de la table sont utilisée dans l'ordre de leur déclaration (les N premiers noms de colonnes si seules N valeurs de colonnes sont fournies dans la clause VALUES ou dans la requête). Les valeurs fournies par la clause VALUES ou par la requête sont associées à la liste explicite ou implicite des colonnes de gauche à droite.

Chaque colonne absente de la liste, implicite ou explicite, des colonnes se voit attribuer sa valeur par défaut, s'il y en a une, ou NULL dans le cas contraire.

Un transtypage automatique est entrepris lorsque l'expression d'une colonne ne correspond pas au type de donnée déclaré.

La clause RETURNING optionnelle fait que INSERT calcule et renvoie le(s) valeur(s) basée(s) sur chaque ligne en cours d'insertion. C'est principalement utile pour obtenir les valeurs qui ont été fournies par défaut, comme un numéro de séquence. Néanmoins, toute expression utilisant les colonnes de la table est autorisée. La syntaxe de la liste RETURNING est identique à celle de la commande SELECT.

Le droit INSERT sur une table est requis pour pouvoir y insérer des lignes. Si une liste de colonne est indiquée, vous avez seulement besoin d'avoir le droit INSERT sur les colonnes listées. L'utilisation de la clause RETURNING nécessite le droit SELECT sur tous les colonnes mentionnées dans RETURNING. Si la clause requête est utilisée pour insérer des lignes, le droit SELECT sur toute table ou colonne utilisée dans la requête est également requis.

Paramètres

Sorties

En cas de succès, la commande INSERT renvoie un code de la forme

INSERT oid nombre

nombre correspond au nombre de lignes insérées. Si nombre vaut exactement un et que la table cible contient des OID, alors oid est l'OID affecté à la ligne insérée. Sinon, oid vaut zéro.

Si la commande INSERT contient une clause RETURNING, le résultat sera similaire à celui d'une instruction SELECT contenant les colonnes et les valeurs définies dans la liste RETURNING, à partir de la liste des lignes insérées par la commande.

Exemples

Insérer une ligne dans la table films :

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

Dans l'exemple suivant, la colonne longueur est omise et prend donc sa valeur par défaut :

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

L'exemple suivant utilise la clause DEFAULT pour les colonnes date plutôt qu'une valeur précise :

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

Insérer une ligne constituée uniquement de valeurs par défaut :

INSERT INTO films DEFAULT VALUES;

Pour insérer plusieurs lignes en utilisant la syntaxe multi-lignes VALUES :

INSERT INTO films (code, titre, did, date_prod, genre) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');

Insérer dans la table films des lignes extraites de la table tmp_films (la disposition des colonnes est identique dans les deux tables) :

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

Insérer dans des colonnes de type tableau :

-- Créer un jeu de 3 cases sur 3
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- Les indices de l'exemple ci-dessus ne sont pas vraiment nécessaires
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');

Insérer une ligne simple dans la table distributeurs, en renvoyant le numéro de séquence généré par la clause DEFAULT :

INSERT INTO distributeurs (did, dnom) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;

Augmenter le nombre de ventes du vendeur qui gère le compte Acme Corporation, et enregistrer la ligne complètement mise à jour avec l'heure courante dans une table de traçage :

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;

Compatibilité

INSERT est conforme au standard SQL, sauf la clause RETURNING qui est une extension PostgreSQL™, comme la possibilité d'utiliser la clause WITH avec l'instruction INSERT. Le standard n'autorise toutefois pas l'omission de la liste des noms de colonnes alors qu'une valeur n'est pas affectée à chaque colonne, que ce soit à l'aide de la clause VALUES ou à partir de la requête.

Les limitations possibles de la clause requête sont documentées sous SELECT(7).