PostgreSQLLa base de données la plus sophistiquée au monde.

Version anglaise

INSERT

INSERT — Insérer de nouvelles lignes dans une table

Synopsis

[ 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

with_query

La clause WITH vous permet de spécifier une ou plusieurs sous-requêtes qui peuvent être référencées par nom dans la requête INSERT. Voir Section 7.8, « Requêtes WITH (Common Table Expressions) » et SELECT(7) pour des détails.

Il est possible que la requête (instruction SELECT) contienne aussi une clause WITH. Dans ce cas, les deux ensembles de requête_with peuvent être référencés à l'intérieur de la requête mais la deuxième prend précédence car elle est plus fortement imbriquée.

nom_table

Le nom de la table (éventuellement qualifié du nom du schéma).

nom_colonne

Le nom d'une colonne de nom_table. Le nom de la colonne peut être qualifié avec un nom de sous-champ ou un indice de tableau, si nécessaire. (N'insérer que certains champs d'une colonne composite laisse les autres champs à NULL.)

DEFAULT VALUES

Toutes les colonnes se voient attribuer leur valeur par défaut.

expression

Une expression ou une valeur à affecter à la colonne correspondante.

DEFAULT

La colonne correspondante se voit attribuer sa valeur par défaut.

requête

Une requête (instruction SELECT) dont le résultat fournit les lignes à insérer. La syntaxe complète de la commande est décrite dans la documentation de l'instruction SELECT(7).

expression_sortie

Une expression à calculer et renvoyée par la commande INSERT après chaque insertion de ligne. L'expression peut utiliser tout nom de colonne de la nom_table. Indiquez * pour que toutes les colonnes soient renvoyées.

nom_sortie

Un nom à utiliser pour une colonne renvoyée.

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).