INSERT |
Insère |
|---|---|
| PostgreSQL | |
Syntaxe
|
[ WITH [ RECURSIVE ] with_query [, ...] ] INSERT INTO table_name [ AS alias ] [ ( column_name [, ...] ) ] [ OVERRIDING { SYSTEM | USER } VALUE ] { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query } [ ON CONFLICT [ conflict_target ] conflict_action ] [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ] où conflict_target peut être l'un des éléments suivants : ( { index_column_name | ( index_expression ) } [ COLLATE collation ] [ opclass ] [, ...] ) [ WHERE index_predicate ] ON CONSTRAINT constraint_name et conflict_action est l'un des : DO NOTHING DO UPDATE SET { column_name = { expression | DEFAULT } | ( column_name [, ...] ) = [ ROW ] ( { expression | DEFAULT } [, ...] ) | ( column_name [, ...] ) = ( sub-SELECT ) } [, ...] [ WHERE condition ] |
Paramètres
| Nom | Description |
|---|---|
| with_query | Ce paramètre permet d'indiquer la clause WITH vous permet de spécifier une ou plusieurs sous-requêtes pouvant être référencées par nom dans la requête INSERT. Il est possible que la requête (instruction SELECT) contienne également une clause WITH. Dans un tel cas, les deux ensembles de with_query peuvent être référencés dans la requête, mais le second est prioritaire car il est plus étroitement imbriqué. |
| table_name | Ce paramètre permet d'indiquer le nom (éventuellement qualifié par le schéma) d'une table existante. |
| alias | Ce paramètre permet d'indiquer un nom de remplacement pour table_name. Lorsqu'un alias est fourni, il masque complètement le nom réel de la table. Ceci est particulièrement utile lorsque ON CONFLICT DO UPDATE cible une table nommée exclue, car cela sera sinon considéré comme le nom de la table spéciale représentant les lignes proposées pour l'insertion. |
| column_name | Ce paramètre permet d'indiquer le nom d'une colonne de la table nommée par table_name. Le nom de la colonne peut être qualifié avec un nom de sous-zone ou un indice de tableau, si nécessaire. (L'insertion dans seulement certains champs d'une colonne composite laisse les autres champs nuls.) Lors du référencement d'une colonne avec ON CONFLICT DO UPDATE, n'incluez pas le nom de la table dans la spécification d'une colonne cible. Par exemple, INSERT INTO table_name ... ON CONFLICT DO UPDATE SET table_name.col = 1 n'est pas valide (cela suit le comportement général de UPDATE). |
| OVERRIDING SYSTEM VALUE | Ce paramètre permet d'annuler cette restriction. Sans cette clause, c'est une erreur de spécifier une valeur explicite (autre que DEFAULT) pour une colonne d'identité définie comme GENERATED ALWAYS. |
| OVERRIDING USER VALUE | Ce paramètre permet d'indiquer si cette clause est spécifiée, toutes les valeurs fournies pour les colonnes d'identité définies comme générées par défaut sont ignorées et les valeurs générées par la séquence par défaut sont appliquées. Cette clause est utile par exemple lors de la copie de valeurs entre des tables. Écrire INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM tbl1 copiera à partir de tbl1 toutes les colonnes n'étant pas des colonnes d'identité dans tbl2 tandis que les valeurs des colonnes d'identité dans tbl2 seront générées par les séquences associées à tbl2. |
| DEFAULT VALUES | Ce paramètre permet d'indiquer que toutes les colonnes seront remplies avec leurs valeurs par défaut. (Une clause OVERRIDING n'est pas autorisée sous cette forme.) |
| expression | Ce paramètre permet d'indiquer une expression ou une valeur à affecter à la colonne correspondante. |
| DEFAULT | Ce paramètre permet d'indiquer la colonne correspondante sera remplie avec sa valeur par défaut. |
| query | Ce paramètre permet d'indiquer une requête (instruction SELECT) fournissant les lignes à insérer. |
| output_expression | Ce paramètre permet d'indiquer une expression à calculer et à renvoyer par la commande INSERT après l'insertion ou la mise à jour de chaque ligne. L'expression peut utiliser n'importe quel nom de colonne de la table nommée par table_name. Écrivez * pour renvoyer toutes les colonnes des lignes insérées ou mises à jour. |
| output_name | Ce paramètre permet d'indiquer un nom à utiliser pour une colonne renvoyée. |
Description
Cette instruction permet de créer de nouvelles lignes dans une table.
Remarques
- L'instruction INSERT insère de nouvelles lignes dans une table. On peut insérer une ou plusieurs lignes spécifiées par des expressions de valeur, ou zéro ou plusieurs lignes résultant d'une requête.
- Les noms de colonne cible peuvent être répertoriés dans n'importe quel ordre. Si aucune liste de noms de colonnes n'est donnée, la valeur par défaut est toutes les colonnes de la table dans leur ordre déclaré ; ou les N premiers noms de colonnes, s'il n'y a que N colonnes fournies par la clause ou la requête VALUES. Les valeurs fournies par la clause ou la requête VALUES sont associées à la liste de colonnes explicite ou implicite de gauche à droite.
- Chaque colonne non présente dans la liste des colonnes explicites ou implicites sera remplie avec une valeur par défaut, soit sa valeur par défaut déclarée, soit null s'il n'y en a pas.
- Si l'expression d'une colonne n'est pas du type de données correct, une conversion de type automatique sera tentée.
- Le ON CONFLICT peut être utilisé pour spécifier une action alternative à la levée d'une erreur de violation de contrainte d'unicité ou d'exclusion.
- La clause optionnelle RETURNING oblige INSERT à calculer et à renvoyer une ou plusieurs valeurs en fonction de chaque ligne réellement insérée (ou mise à jour, si une clause ON CONFLICT DO UPDATE a été utilisée). Ceci est principalement utile pour obtenir des valeurs fournies par défaut, telles qu'un numéro de séquence de série. Cependant, toute expression utilisant les colonnes de la table est autorisée. La syntaxe de la liste RETURNING est identique à celle de la liste de sortie de SELECT. Seules les lignes insérées ou mises à jour avec succès seront renvoyées. Par exemple, si une ligne a été verrouillée mais n'a pas été mise à jour parce qu'une condition de clause ON CONFLICT DO UPDATE ... WHERE n'a pas été satisfaite, la ligne ne sera pas renvoyée.
- Vous devez avoir le privilège INSERT sur une table pour pouvoir y insérer. Si ON CONFLICT DO UPDATE est présent, le privilège UPDATE sur la table est également requis.
- Si une liste de colonnes est spécifiée, vous n'avez besoin que du privilège INSERT sur les colonnes répertoriées. De même, lorsque ON CONFLICT DO UPDATE est spécifié, vous n'avez besoin du privilège UPDATE que sur la ou les colonnes répertoriées à mettre à jour. Cependant, ON CONFLICT DO UPDATE requiert également le privilège SELECT sur toute colonne dont les valeurs sont lues dans les expressions ou la condition ON CONFLICT DO UPDATE.
- L'utilisation de la clause RETURNING requiert le privilège SELECT sur toutes les colonnes mentionnées dans RETURNING. Si vous utilisez la clause query pour insérer des lignes à partir d'une requête, vous devez bien entendu disposer du privilège SELECT sur n'importe quelle table ou colonne utilisée dans la requête.
Dernière mise à jour : Jeudi, le 14 Octobre 2021