Description

MERGE exécute des actions qui modifient des lignes dans la table cible identifiée par nom_table_cible, à partir d'une source_des_données. MERGE est un ordre SQL qui, à lui seul et selon la condition, peut opérer un INSERT, un UPDATE ou un DELETE sur des lignes, une tâche qui nécessiterait sinon de multiples appels en langage procédural.

Tout d'abord, la commande MERGE fait une jointure entre source_des_données et la table cible, ce qui donne zéro ou plus ligne(s) candidates au changement. Pour chacune, on définit le statut MATCHED ou NOT MATCHED une fois pour toutes ; puis les clauses WHEN sont évaluées dans l'ordre spécifié. Pour chaque ligne candidate à un changement, la première clause évaluée à true est exécutée. Au plus une clause WHEN est exécutée pour chaque ligne candidate au changement.

Les opérations de MERGE ont le même effet que les commandes UPDATE, INSERT, ou DELETE de même nom. La syntaxe de ces commandes diffère, notamment sur l'absence de clause WHERE et de nom de table. Toutes les actions opèrent sur la table cible, bien que des modifications sur d'autres tables puissent être faites en passant par des triggers.

Si DO NOTHING est précisé, la ligne source est passée. Comme les actions sont évaluées dans l'ordre spécifié, il peut être pratique de sauter les lignes source sans intérêt avant une gestion plus fine.

Il n'y a pas de droit MERGE dédié. Si vous spécifiez une mise à jour, vous devez posséder le droit UPDATE sur les colonnes de la table cible mentionnées dans la clause SET. Pour une insertion, vous devez posséder le droit INSERT sur la table cible. Et pour une suppression, vous devez posséder le droit DELETE sur la table cible. Si vous ajoutez une action DO NOTHING, vous devrez avoir le droit SELECT sur au moins une colonne de la table cible. Vous aurez aussi besoin du droit SELECT sur toute colonne de source_des_données et sur toute colonne de la table cible référencée dans toute condition (incluant condition_jointure) ou expression. Les droits sont testés et vérifiés une fois au démarrage de l'ordre, que les clauses WHEN concernées soient exécutées ou pas.

MERGE n'est pas supporté si la table cible est une vue matérialisée, une table étrangère, ou si des règles y ont été posées.

Paramètres

Résultats

Si elle termine avec succès, la commande MERGE renvoie un résultat de la forme :

MERGE nombre_total

nombre_total est le nombre total des lignes changées (qu'elles aient été insérées, mises à jour ou effacées). Si nombre_total vaut 0, aucune ligne n'a été changée de quelque manière que ce soit.

Notes

Les étapes suivantes se déroulent pendant l'exécution de MERGE.

En résumé, les triggers de niveau instruction (par exemple INSERT) seront déclenchés à chaque spécification d'une action de leur genre. Par contre, les triggers de niveau ligne se déclencheront uniquement pour les types d'événements exécutés. Ainsi un ordre MERGE peut déclencher à la fois des triggers sur instruction UPDATE et sur INSERT, même si seuls des triggers de ligne sur UPDATE sont déclenchés.

Vous devez vous assurer que la jointure produit au plus une ligne candidate pour chaque ligne de la source. En d'autres termes, une ligne cible ne devrait pas être jointe à plus d'une ligne de données source. Si cela devait arriver, une seule ligne parmi les candidates sera utilisée pour modifier la ligne cible ; une erreur sera levée lors des tentatives suivantes de modification de la ligne. Cela peut arriver si des triggers sur ligne modifient la table cible et que les lignes modifiées sont par la suite aussi modifiées par MERGE. Si l'action répétée est un INSERT, cela provoquera une violation d'unicité, alors que des ordres UPDATE ou DELETE répétés causeront une violation de cardinalité ; ce dernier comportement est exigé par le standard SQL. Cela diffère du comportement historique de PostgreSQL dans les jointures au sein d'ordres UPDATE et DELETE, où le deuxième essai de modification d'une même ligne est simplement ignoré, tout comme les suivants.

Si une clause WHEN omet une sous-clause AND, elle devient la clause finale atteinte pour ce type (MATCHED ou NOT MATCHED). Si une autre clause WHEN est spécifiée pour le même type, elle serait probablement inatteignable et une erreur est levée. Si aucune clause finale n'est spécifiée pour un type, il est possible qu'aucune action ne soit exécutée pour la ligne candidate.

L'ordre dans lequel les lignes seront générées depuis la source des données est par défaut indéterminé. Au besoin, une requête_source peut être utilisée pour définir un ordre cohérent, qui pourrait être nécessaire pour éviter des verrous mutuels entre transactions simultanées.

Il n'y a pas de clause RETURNING à une commande MERGE. Les action INSERT, UPDATE et DELETE ne peuvent contenir de clauses RETURNING ou WITH.

Quand MERGE est lancé en parallèle à d'autres commandes qui modifient la table cible, les règles usuelles d'isolation des transactions s'appliquent ; voir Section 13.2 pour une explication du comportement de chaque niveau d'isolation. Comme alternative permettant de lancer un ordre UPDATE en même temps que se déroule un INSERT, vous pouvez considérer INSERT ... ON CONFLICT. Il y a beaucoup de différences entre les deux ordres, et leurs limites diffèrent, si bien qu'ils ne sont pas interchangeables.

Exemples

Effectue une maintenance sur customer_accounts à partir de nouvelles recent_transactions.

MERGE INTO customer_account ca
USING recent_transactions t
ON t.customer_id = ca.customer_id
WHEN MATCHED THEN
  UPDATE SET balance = balance + transaction_value
WHEN NOT MATCHED THEN
  INSERT (customer_id, balance)
  VALUES (t.customer_id, t.transaction_value);

Notez que c'est exactement la même chose que l'ordre suivant, car le résultat du MATCHED ne change pas pendant l'exécution.

MERGE INTO customer_account ca
USING (SELECT customer_id, transaction_value FROM recent_transactions) AS t
ON t.customer_id = ca.customer_id
WHEN MATCHED THEN
  UPDATE SET balance = balance + transaction_value
WHEN NOT MATCHED THEN
  INSERT (customer_id, balance)
  VALUES (t.customer_id, t.transaction_value);

Tente d'insérer un nouvel article dans un stock avec sa quantité. Si l'article existe déjà, met plutôt à jour son stock existant. Interdit les entrées avec un stock à zéro.

MERGE INTO wines w
USING wine_stock_changes s
ON s.winename = w.winename
WHEN NOT MATCHED AND s.stock_delta > 0 THEN
  INSERT VALUES(s.winename, s.stock_delta)
WHEN MATCHED AND w.stock + s.stock_delta > 0 THEN
  UPDATE SET stock = w.stock + s.stock_delta
WHEN MATCHED THEN
  DELETE;

La table wine_stock_changes peut être, par exemple, une table temporaire récemment chargée dans la base.

Compatibilité

Cette commande se conforme au standard SQL.

La clause WITH et l'action DO NOTHING sont des extensions au standard SQL.