GRANT
INSERT INTO table [ ( colonne [, ...] ) ]
{ DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | requête }
[ RETURNING * | expression_sortie [ [ AS ] nom_sortie ] [, ...] ]
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.
Le nom de la table (éventuellement qualifié du nom du schéma).
Le nom d'une colonne de 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.)
Toutes les colonnes se voient attribuer leur valeur par défaut.
Une expression ou une valeur à affecter à la colonne correspondante.
La colonne correspondante se voit attribuer sa valeur par défaut.
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.
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 table. Indiquez * pour que toutes les colonnes soient renvoyées.
Un nom à utiliser pour une colonne renvoyée.
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.
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;
INSERT est conforme au standard SQL, sauf la clause RETURNING qui est une extension PostgreSQL™. 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.