Documentation PostgreSQL 14.22 » Langage SQL » Manipulation de données » Renvoyer des données provenant de lignes modifiées

Précédent | Niveau supérieur | Suivant
6.3. Supprimer des données | Sommaire | Chapitre 7. Requêtes

## 6.4. Renvoyer des données provenant de lignes modifiées

Parfois, il est intéressant d'obtenir des données de lignes modifiées pendant qu'elles sont manipulées. Les commandes `INSERT`, `UPDATE` et `DELETE` ont toutes une clause `RETURNING` optionnelle qui le permet. L'utilisation de la clause `RETURNING` évite l'exécution d'une requête supplémentaire pour coller les données, et est particulièrement intéressante quand il serait difficile d'identifier autrement les lignes modifiées.

Le contenu autorisé d'une clause `RETURNING` est identique à celui de la liste de sortie d'une commande `SELECT` (voir Section 7.3). Elle peut contenir les noms des colonnes de la table cible ou des expressions utilisant ces colonnes. Un raccourci habituel est `RETURNING *`, qui sélectionne toutes les colonnes de la table cible, dans l'ordre de définition.

Avec un `INSERT`, les données disponibles à `RETURNING` sont la ligne qui a été insérée. Ceci n'est pas utile pour les insertions simples, car cela ne fera que répéter les données fournies par le client, mais cela peut devenir très utile si la commande se base sur les valeurs calculées par défaut. Par exemple, lors de l'utilisation d'une colonne `serial` fournissant des identifiants uniques, `RETURNING` peut renvoyer l'identifiant affecté à une nouvelle ligne :

    CREATE TABLE utilisateurs (prenom text, nom text, id serial primary key);

    INSERT INTO utilisateurs (prenom, nom) VALUES ('Joe', 'Cool') RETURNING id;

La clause `RETURNING` est aussi très utile avec un `INSERT ... SELECT`

Dans un `UPDATE`, les données disponibles pour la clause `RETURNING` correspondent au nouveau contenu de la ligne modifiée. Par exemple :

    UPDATE produits SET prix = prix * 1.10
      WHERE prix <= 99.99
      RETURNING nom, prix AS nouveau_prix;

Dans un `DELETE`, les données disponibles pour la clause `RETURNING` correspondent au contenu de la ligne supprimée. Par exemple :

    DELETE FROM produits
      WHERE date_perime = 'today'
      RETURNING *;

Si des triggers (Chapitre 39) sont définis sur la table cible, les données disponibles pour la clause `RETURNING` correspondent à la ligne modifiée par les triggers. De ce fait, une utilisation courante de la clause `RETURNING` est d'inspecter les colonnes calculées par les triggers.