INSERT

Nom

INSERT -- insère de nouvelles lignes dans une table

Synopsis

INSERT INTO table [ ( colonne [, ...] ) ]
    { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) | requête }

Description

INSERT insère de nouvelles lignes dans une table. Il est possible d'insérer une ligne spécifiée par des valeurs ou plusieurs lignes comme résultat d'une requête.

Les noms des colonnes cibles peuvent être donnés dans un ordre quelconque. 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 de déclaration ; ou les N premiers noms de colonnes si seulement 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 dans la liste de colonnes explicite ou implicite est remplie avec sa valeur par défaut déclarée s'il y en a une ou avec NULL s'il n'en a pas.

Si l'expression pour chaque colonne n'est pas du bon type de données, une conversion automatique de type est tentée.

Vous devez avoir le droit INSERT sur une table pour pouvoir y insérer des lignes. Si vous utilisez la clause requête pour insérer des lignes à partir d'une requête, vous avez aussi besoin d'avoir un droit SELECT sur toute table utilisée dans la requête.

Paramètres

table

Le nom d'une table existante (pouvant être qualifié du nom du schéma).

colonne

Le nom d'une colonne dans 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 auront leurs valeurs par défaut.

expression

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

DEFAULT

La colonne correspondante sera remplie avec sa valeur par défaut.

requête

Une requête (instruction SELECT) fournissant les lignes à insérer. Référez-vous à l'instruction SELECT pour une description de la syntaxe.

Sorties

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

INSERT oid 
 nombre

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

Exemples

Insérer une seule ligne dans la table films :

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

Dans cet exemple, la colonne longueur est omise et, du coup, elle prend la valeur par défaut :

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

Cet exemple utilise la clause DEFAULT pour les colonnes date plutôt que de spécifier une valeur :

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

Pour insérer une ligne consistant uniquement en des valeurs par défaut :

INSERT INTO films DEFAULT VALUES;

Cet exemple insère quelques lignes dans la table films à partir de la table tmp_films avec le même emplacement des colonnes :

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

Cet exemple insére dans des colonnes de type tableau :

-- Create an empty 3x3 gameboard for noughts-and-crosses
-- (these commands create the same board)
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1,'{{"","",""},{"","",""},{"","",""}}');
INSERT INTO tictactoe (game, board)
    VALUES (2,'{{,,},{,,},{,,}}');

Compatibilité

INSERT est totalement compatible avec le standard SQL. Le cas où une liste de noms de colonnes est omise, mais où toutes les colonnes ne sont pas remplies à partir des valeurs de la clause VALUES ou à partir de la requête, est interdit par le standard.

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