Parcourir les aide-mémoire · Microsoft Fabric

Technologie: Microsoft FabricCatégorie: Ingénierie des donnéesNiveau: IntermédiaireMis à jour

Modèles de lecture et d’écriture Delta Lake

Lire et écrire des tables Delta dans Microsoft Fabric en toute sécurité avec l’ajout (append), l’écrasement (overwrite), MERGE, le partitionnement, le contrôle du schéma, des modèles adaptés à la concurrence et la maintenance des tables.

Sur cette page
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Lire une table Delta managée par son nom
  5. 2. Lire une table Delta par son chemin
  6. 3. Ne lire que les colonnes nécessaires
  7. 4. Filtrer tôt
  8. 5. Ajouter de nouvelles lignes immuables
  9. 6. Ajouter un identifiant de lot d’ingestion
  10. 7. N’écraser une table entière que lorsque le remplacement complet est voulu
  11. 8. N’écraser le schéma que lorsque le changement de schéma est délibéré
  12. 9. Utiliser mergeSchema avec prudence pour l’évolution additive du schéma
  13. 10. Faire un upsert avec MERGE de Delta
  14. 11. Préférer des correspondances de mise à jour explicites pour des contrats de production stables
  15. 12. Dédupliquer la source avant MERGE
  16. 13. Valider l’unicité de la source avant un merge
  17. 14. Utiliser une clé métier composée lorsqu’une seule colonne ne suffit pas
  18. 15. Ne mettre à jour que si la ligne entrante est plus récente
  19. 16. N’insérer que les nouvelles clés
  20. 17. Ne supprimer via MERGE qu’avec un contrat source délibéré
  21. 18. Utiliser MERGE en SQL lorsque SQL est plus clair
  22. 19. Utiliser staging + merge pour l’ingestion concurrente
  23. 20. Concevoir une logique de nouvelle tentative pour les conflits Delta concurrents
  24. 21. Comprendre le Low Shuffle Merge de Fabric
  25. 22. Ne partitionner que sur des dimensions utiles de cardinalité faible ou modérée
  26. 23. Ne pas surpartitionner les petites tables
  27. 24. Examiner la distribution des partitions avant de modifier l’organisation
  28. 25. Éviter repartition(1) avant les écritures Delta
  29. 26. Réduire un nombre excessif de partitions d’écriture lorsque la sortie est petite
  30. 27. Compacter les petits fichiers avec OPTIMIZE
  31. 28. N’utiliser le Z-Order que pour un vrai modèle d’accès
  32. 29. Comprendre V-Order dans Fabric
  33. 30. Examiner les paramètres d’optimisation de Fabric avant de les modifier
  34. 31. Utiliser VACUUM pour nettoyer le stockage, pas pour optimiser les requêtes
  35. 32. N’utiliser VACUUM LITE que sur les runtimes Fabric compatibles
  36. 33. Ne pas réduire la rétention de VACUUM à la légère
  37. 34. Lire une version antérieure d’une table Delta pour investiguer
  38. 35. Examiner l’historique Delta
  39. 36. Comparer les comptages avant et après les écritures
  40. 37. Rapprocher les clés métier après un upsert
  41. 38. Stocker les métadonnées d’exécution pour les chargements incrémentaux
  42. 39. Éviter de lire et de réécrire toute la cible pour une petite modification incrémentale
  43. 40. Garder l’ingestion brute en ajout seul lorsque c’est possible
  44. Interpréter le résultat
  45. Points à vérifier
  46. Le nombre de lignes de la cible augmente à chaque relance
  47. MERGE touche beaucoup plus de données que prévu
  48. Des traitements concurrents échouent pendant les écritures
  49. La table contient de nombreux petits fichiers
  50. Les lectures ralentissent après de nombreuses mises à jour ou merges
  51. Les anciennes versions de la table ne fonctionnent plus
  52. Notes de production
  53. Delta fournit des transactions ACID sur la table, pas des contraintes métier arbitraires
  54. Le Low Shuffle Merge de Fabric est déjà activé par défaut
  55. Les écritures concurrentes exigent une conception tenant compte de l’organisation des données
  56. OPTIMIZE et VACUUM résolvent des problèmes différents
  57. VACUUM affecte la capacité de reprise
  58. Les valeurs par défaut de V-Order ont évolué
  59. Tenir la maintenance des tables à l’écart des pics d’écriture lorsque c’est possible
  60. Le partitionnement n’est pas obligatoire
  61. Erreurs fréquentes
  62. 1. Utiliser l’ajout pour un flux modifiable et rejouable
  63. 2. Utiliser l’écrasement à chaque relance
  64. 3. Utiliser whenMatchedUpdateAll() sans réfléchir au schéma
  65. 4. Faire un merge avec des clés source en double
  66. 5. Partitionner par un identifiant à forte cardinalité
  67. 6. Appeler repartition(1) avant chaque écriture
  68. 7. Exécuter VACUUM pour accélérer les requêtes
  69. 8. Réduire la rétention de VACUUM sans comprendre le time travel
  70. 9. Considérer une transaction Delta réussie comme la preuve que les métriques sont correctes
  71. 10. Relancer toutes les exceptions d’écriture
  72. Étape suivante
  73. Pour aller plus loin

Problème

Les tables Lakehouse de Microsoft Fabric reposent sur Delta Lake, qui apporte aux charges de travail Spark une sémantique de table transactionnelle au-dessus de fichiers Parquet stockés dans OneLake.

La syntaxe pour lire et écrire des tables Delta est simple.

Les questions de production sont plus difficiles :

  • Ce chargement doit-il faire un ajout, un écrasement ou un merge ?
  • L’opération est-elle idempotente ?
  • Des écritures concurrentes vont-elles toucher les mêmes fichiers ?
  • Les changements de schéma seront-ils acceptés ou rejetés ?
  • Le partitionnement aide-t-il, ou crée-t-il des petits fichiers ?
  • Les mises à jour répétées fragmentent-elles les fichiers ?
  • Quand faut-il exécuter OPTIMIZE ou VACUUM ?
  • Comment éviter de réécrire beaucoup plus de données que nécessaire ?

L’objectif est de choisir le modèle d’écriture à partir du contrat de données, et non selon la commande la plus facile à relancer.

Réponse rapide

Utilisez ce flux de décision :

Uniquement de nouvelles lignes immuables
→ APPEND

Reconstruire volontairement toute la table
→ OVERWRITE

Insérer + mettre à jour des clés métier existantes
→ MERGE

Remplacer uniquement une tranche/partition connue
→ overwrite sélectif / modèle tenant compte des partitions

Nombreux producteurs concurrents
→ ajout en staging, puis réconciliation par un MERGE contrôlé

Lire une table Delta d’un Lakehouse :

df = spark.read.table("sales")

ou :

df = (
    spark.read
    .format("delta")
    .load("Tables/sales")
)

Ajout (append) :

(
    df.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Upsert :

from delta.tables import DeltaTable

target = DeltaTable.forName(
    spark,
    "sales",
)

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

N’utilisez pas l’écrasement complet de la table comme stratégie de relance par défaut.

Code / commandes

1. Lire une table Delta managée par son nom

sales = spark.read.table(
    "sales"
)

Équivalent en Spark SQL :

sales = spark.sql(
    "SELECT * FROM sales"
)

Utilisez les noms de table lorsque la table est enregistrée dans le metastore du Lakehouse et que le notebook est attaché au Lakehouse prévu.


2. Lire une table Delta par son chemin

sales = (
    spark.read
    .format("delta")
    .load("Tables/sales")
)

Utilisez les lectures par chemin lorsque :

  • le chemin fait lui-même partie de la conception
  • vous travaillez avec un emplacement OneLake explicite
  • vous ne voulez pas dépendre de l’espace de noms des tables du Lakehouse par défaut actuel

Dans le code de production, évitez de mélanger à la légère les sémantiques par nom de table et par chemin.

Choisissez un modèle cohérent pour la charge de travail.


3. Ne lire que les colonnes nécessaires

sales = (
    spark.read.table("sales")
    .select(
        "sale_id",
        "merchant_id",
        "sale_date",
        "amount",
    )
)

L’élagage des colonnes (column pruning) réduit la quantité de données transportées dans les transformations en aval.

C’est important sur les tables Delta larges.


4. Filtrer tôt

from pyspark.sql import functions as F

sales = (
    spark.read.table("sales")
    .filter(
        F.col("sale_date") >= "2026-10-01"
    )
    .select(
        "sale_id",
        "merchant_id",
        "sale_date",
        "amount",
    )
)

Filtrer avant les jointures et les agrégations peut réduire :

  • le volume scanné
  • le volume de shuffle
  • la pression mémoire
  • la taille de la sortie

La possibilité de pousser chaque prédicat vers la source (pushdown) dépend de l’organisation de la table et de l’expression.


5. Ajouter de nouvelles lignes immuables

(
    new_sales.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Utilisez l’ajout lorsque les lignes sont réellement nouvelles et que les lignes existantes ne doivent pas être modifiées.

Exemples typiques :

  • ingestion d’événements immuables
  • données brutes d’atterrissage
  • historique d’audit en ajout seul

L’ajout n’est pas automatiquement idempotent.

Si le même lot peut être rejoué, la prévention des doublons doit être conçue séparément.


6. Ajouter un identifiant de lot d’ingestion

Pour détecter les rejeux :

from pyspark.sql import functions as F

new_sales = (
    new_sales
    .withColumn(
        "ingestion_batch_id",
        F.lit("2026-10-04T1700Z"),
    )
)

Cela peut aider à identifier :

  • les chargements de lots en double
  • les relances
  • les traitements partiels
  • la traçabilité (lineage)

Un identifiant de lot n’empêche pas les doublons à lui seul.

Il vous fournit des éléments pour garantir ou auditer l’idempotence.


7. N’écraser une table entière que lorsque le remplacement complet est voulu

(
    rebuilt_table.write
    .format("delta")
    .mode("overwrite")
    .saveAsTable("sales_summary")
)

Utilisez ce modèle pour :

  • les petites tables dérivées
  • les reconstructions complètes et déterministes
  • les tables dont le contrat est explicitement de tout remplacer

N’utilisez pas l’écrasement simplement parce que c’est plus facile que d’implémenter une logique incrémentale.

Un écrasement complet peut :

  • réécrire de grandes quantités de données
  • allonger la durée d’exécution
  • créer davantage de fichiers obsolètes
  • augmenter le risque de conflit
  • affecter les lecteurs et écrivains concurrents selon l’opération

8. N’écraser le schéma que lorsque le changement de schéma est délibéré

(
    rebuilt_table.write
    .format("delta")
    .mode("overwrite")
    .option(
        "overwriteSchema",
        "true",
    )
    .saveAsTable("sales_summary")
)

N’utilisez overwriteSchema que lorsque le remplacement du schéma de la table fait partie de la migration ou de la reconstruction.

Ne l’activez pas globalement.

Les changements de schéma doivent être intentionnels et validés auprès des consommateurs en aval.


9. Utiliser mergeSchema avec prudence pour l’évolution additive du schéma

(
    new_data.write
    .format("delta")
    .mode("append")
    .option(
        "mergeSchema",
        "true",
    )
    .saveAsTable("sales")
)

Cela peut permettre d’ajouter de nouvelles colonnes compatibles.

N’utilisez pas l’évolution de schéma pour masquer une dérive de schéma en amont.

Avant de l’activer en production, décidez :

Quelles colonnes ont le droit d’apparaître ?
Qui est responsable des changements de schéma ?
Comment les consommateurs en aval seront-ils prévenus ?

10. Faire un upsert avec MERGE de Delta

from delta.tables import DeltaTable

target = DeltaTable.forName(
    spark,
    "sales",
)

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

Utilisez MERGE lorsque la clé métier peut déjà exister et que les données entrantes peuvent :

  • mettre à jour des lignes existantes
  • insérer de nouvelles lignes

La condition de merge doit représenter la véritable clé métier.


11. Préférer des correspondances de mise à jour explicites pour des contrats de production stables

Au lieu de :

.whenMatchedUpdateAll()

utilisez des correspondances explicites lorsque le contrôle du schéma est important :

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdate(
        set={
            "merchant_id": "s.merchant_id",
            "sale_date": "s.sale_date",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .whenNotMatchedInsert(
        values={
            "sale_id": "s.sale_id",
            "merchant_id": "s.merchant_id",
            "sale_date": "s.sale_date",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .execute()
)

Les correspondances explicites réduisent le couplage accidentel entre le schéma source et le schéma cible.


12. Dédupliquer la source avant MERGE

Si la source contient plusieurs lignes pour la même clé cible, décidez laquelle doit l’emporter.

Exemple :

from pyspark.sql import Window
from pyspark.sql import functions as F

w = (
    Window
    .partitionBy("sale_id")
    .orderBy(
        F.col("updated_at").desc(),
        F.col("source_sequence").desc(),
    )
)

source_deduped = (
    source
    .withColumn(
        "_rn",
        F.row_number().over(w),
    )
    .filter(
        F.col("_rn") == 1
    )
    .drop("_rn")
)

Faites ensuite le merge de source_deduped.

Ne vous fiez pas à un ordre arbitraire des lignes de la source.


13. Valider l’unicité de la source avant un merge

duplicate_keys = (
    source
    .groupBy("sale_id")
    .count()
    .filter(
        F.col("count") > 1
    )
)

duplicate_keys.show(
    50,
    truncate=False,
)

Si la source doit être unique et que cette requête renvoie des lignes, arrêtez-vous et investiguez.

Des clés source en double peuvent rendre le comportement du merge ambigu, ou le faire échouer selon le modèle de correspondance.


14. Utiliser une clé métier composée lorsqu’une seule colonne ne suffit pas

merge_condition = """
    t.member_id = s.member_id
    AND t.merchant_id = s.merchant_id
    AND t.site_id = s.site_id
"""

Puis :

(
    target.alias("t")
    .merge(
        source.alias("s"),
        merge_condition,
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

Ne simplifiez pas une véritable clé composite uniquement pour raccourcir le code du merge.


15. Ne mettre à jour que si la ligne entrante est plus récente

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll(
        condition="""
            s.updated_at > t.updated_at
        """
    )
    .whenNotMatchedInsertAll()
    .execute()
)

Cela empêche un rejeu plus ancien d’écraser un état plus récent.

N’utilisez ce modèle que si updated_at offre une sémantique d’ordre fiable.


16. N’insérer que les nouvelles clés

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenNotMatchedInsertAll()
    .execute()
)

Ce modèle peut rendre une ingestion de type ajout idempotente par clé métier.

Il est plus coûteux qu’un ajout aveugle, car la cible doit participer à la correspondance.

Utilisez-le lorsque la prévention des doublons vaut ce coût.


17. Ne supprimer via MERGE qu’avec un contrat source délibéré

Exemple :

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedDelete(
        condition="s.is_deleted = true"
    )
    .whenMatchedUpdateAll(
        condition="s.is_deleted = false"
    )
    .whenNotMatchedInsertAll(
        condition="s.is_deleted = false"
    )
    .execute()
)

N’utilisez la suppression pilotée par la source que lorsque l’indicateur de suppression a une sémantique métier fiable.

Ne déduisez pas une suppression simplement parce qu’une ligne est absente d’un lot source incrémental.


18. Utiliser MERGE en SQL lorsque SQL est plus clair

MERGE INTO sales AS t
USING sales_stage AS s
ON t.sale_id = s.sale_id

WHEN MATCHED
    AND s.updated_at > t.updated_at
THEN UPDATE SET
    t.merchant_id = s.merchant_id,
    t.sale_date = s.sale_date,
    t.amount = s.amount,
    t.updated_at = s.updated_at

WHEN NOT MATCHED
THEN INSERT
(
    sale_id,
    merchant_id,
    sale_date,
    amount,
    updated_at
)
VALUES
(
    s.sale_id,
    s.merchant_id,
    s.sale_date,
    s.amount,
    s.updated_at
);

Spark SQL et l’API Delta fonctionnent tous deux très bien.

Choisissez la forme qui rend la transformation la plus facile à relire.


19. Utiliser staging + merge pour l’ingestion concurrente

Une architecture plus sûre en forte concurrence est :

    • Producteur A
    • Producteur B
    • Producteur C
  1. ajout seul
    Staging Delta
  2. MERGE contrôlé
  3. Delta cible
Staging et merge pour l’ingestion concurrente

Une zone de staging en ajout seul réduit les conflits entre producteurs indépendants.

Un merge contrôlé effectue ensuite la réconciliation de la cible, sujette aux conflits.

C’est particulièrement utile lorsque plusieurs activités de notebook ou de pipeline peuvent arriver en même temps.


20. Concevoir une logique de nouvelle tentative pour les conflits Delta concurrents

Delta fournit des commits transactionnels : une transaction échouée ne laisse donc pas la table dans un état partiellement validé.

Pour les charges de travail où des conflits d’écriture logiques sont attendus, ne relancez que les cas d’échec de concurrence connus.

Modèle conceptuel :

import time

max_retries = 3

for attempt in range(max_retries):
    try:
        run_merge()
        break
    except Exception as exc:
        if not is_expected_delta_conflict(exc):
            raise

        if attempt == max_retries - 1:
            raise

        time.sleep(2 ** attempt)

N’interceptez pas toutes les exceptions pour les relancer aveuglément.

Relancez :

  • les conditions transitoires ou de conflit que vous comprenez

Ne relancez pas automatiquement :

  • un schéma incorrect
  • des données source mal formées
  • une logique de merge invalide
  • des échecs d’autorisation

21. Comprendre le Low Shuffle Merge de Fabric

Fabric Spark inclut l’optimisation Low Shuffle Merge pour MERGE de Delta.

Elle est activée par défaut dans les runtimes Fabric Spark.

Vérifiez le paramètre de la session actuelle :

print(
    spark.conf.get(
        "spark.microsoft.delta.merge.lowShuffle.enabled"
    )
)

Définissez-le explicitement si nécessaire pour des tests contrôlés :

spark.conf.set(
    "spark.microsoft.delta.merge.lowShuffle.enabled",
    True,
)

Ne considérez pas cette optimisation comme un substitut à :

  • des conditions de merge sélectives
  • des clés métier correctes
  • une bonne organisation des fichiers
  • la réduction du volume source

22. Ne partitionner que sur des dimensions utiles de cardinalité faible ou modérée

Exemple :

(
    sales.write
    .format("delta")
    .mode("append")
    .partitionBy(
        "sale_year",
        "sale_month",
    )
    .saveAsTable("sales")
)

Les bons candidats au partitionnement correspondent souvent à :

  • des filtres d’élagage courants
  • des limites d’ingestion
  • des limites d’isolation des écrivains

Les mauvais candidats incluent souvent :

  • les identifiants de transaction
  • les horodatages exacts
  • les identifiants client comptant des millions de valeurs

Un partitionnement à forte cardinalité crée un nombre excessif de répertoires et de fichiers.


23. Ne pas surpartitionner les petites tables

Une table n’a pas besoin d’un partitionnement physique simplement parce qu’elle possède une colonne de date.

Pour les tables petites ou moyennes, une table Delta non partitionnée peut être plus simple et offrir de bonnes performances.

Le partitionnement doit résoudre un problème concret, par exemple :

  • l’élagage des données
  • l’isolation des écritures
  • la gestion du cycle de vie

24. Examiner la distribution des partitions avant de modifier l’organisation

(
    sales
    .groupBy(
        "sale_year",
        "sale_month",
    )
    .count()
    .orderBy(
        F.desc("count")
    )
    .show(
        100,
        truncate=False,
    )
)

Appuyez-vous sur la distribution réelle des données pour évaluer si les partitions proposées seraient équilibrées et utiles.


25. Éviter repartition(1) avant les écritures Delta

Risqué :

(
    df.repartition(1)
    .write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Cela crée un goulot d’étranglement d’écriture sur une seule partition.

Les tables Delta sont conçues pour contenir plusieurs fichiers Parquet.

Si un processus en aval exige un fichier d’export unique, traitez-le comme un besoin d’export distinct.


26. Réduire un nombre excessif de partitions d’écriture lorsque la sortie est petite

Si le résultat final est petit mais comporte encore de nombreuses partitions Spark :

smaller = df.coalesce(20)

Écrivez ensuite :

(
    smaller.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales_summary")
)

Ne le faites qu’après avoir mesuré.

Un nombre trop faible de partitions peut aussi créer des tâches volumineuses ou lentes.


27. Compacter les petits fichiers avec OPTIMIZE

Spark SQL :

OPTIMIZE sales;

Recourez à la maintenance des tables lorsque des écritures ou merges répétés ont créé de nombreux petits fichiers et que les performances de lecture en pâtissent.

OPTIMIZE réécrit les fichiers de données.

Planifiez-le délibérément plutôt qu’après chaque écriture.


28. N’utiliser le Z-Order que pour un vrai modèle d’accès

Exemple :

OPTIMIZE sales
ZORDER BY
(
    merchant_id,
    sale_date
);

Utilisez le Z-Order lorsque les requêtes filtrent de façon répétée sur certaines colonnes et que la table est assez volumineuse pour que le saut de fichiers (file skipping) et l’amélioration de l’organisation comptent.

N’appliquez pas le Z-Order à toutes les colonnes.

La maintenance a un coût en calcul et en écriture.


29. Comprendre V-Order dans Fabric

V-Order est une optimisation de Fabric appliquée à l’écriture, qui porte sur l’organisation des fichiers Parquet.

Elle peut améliorer les lectures dans l’ensemble des moteurs Fabric, en particulier pour les charges analytiques à forte intensité de lecture, au prix d’un travail d’écriture supplémentaire.

Le comportement actuel de Fabric dépend de la configuration de l’espace de travail et du runtime ; V-Order n’est pas activé par défaut dans tous les espaces de travail récents.

Vérifiez votre charge de travail et votre runtime réels plutôt que de supposer qu’il est activé.

Utilisez V-Order lorsque les performances de lecture des consommateurs Fabric justifient le compromis à l’écriture.


30. Examiner les paramètres d’optimisation de Fabric avant de les modifier

Exemples :

keys = [
    "spark.sql.parquet.vorder.enabled",
    "spark.sql.parquet.vorder.default",
    "spark.databricks.delta.optimizeWrite.enabled",
]

for key in keys:
    try:
        print(
            key,
            spark.conf.get(key),
        )
    except Exception:
        print(
            key,
            "<not available>",
        )

Le nom et la disponibilité des paramètres de configuration peuvent dépendre du runtime Fabric.

Ne copiez pas d’anciennes recettes d’optimisation sans vérifier le runtime actif.


31. Utiliser VACUUM pour nettoyer le stockage, pas pour optimiser les requêtes

Standard :

VACUUM sales;

Rétention explicite :

VACUUM sales RETAIN 168 HOURS;

VACUUM supprime définitivement les anciens fichiers de données non référencés plus anciens que le seuil de rétention.

C’est avant tout une opération de nettoyage du stockage.

Ce n’est pas la même chose que OPTIMIZE.


32. N’utiliser VACUUM LITE que sur les runtimes Fabric compatibles

Fabric Spark Runtime 2.0 / Delta 4.1 et versions ultérieures prennent en charge VACUUM LITE.

Exemple :

VACUUM sales LITE RETAIN 168 HOURS;

ou :

from delta.tables import DeltaTable

table = DeltaTable.forName(
    spark,
    "sales",
)

table.vacuum(
    168,
    mode="LITE",
)

VACUUM LITE utilise les informations du journal Delta au lieu d’un listage complet des répertoires.

Si l’historique du journal Delta disponible est insuffisant, il peut échouer et exiger un vacuum standard (complet).

Vérifiez la prise en charge par le runtime avant de l’utiliser.


33. Ne pas réduire la rétention de VACUUM à la légère

Une rétention courte peut supprimer des fichiers nécessaires pour :

  • le voyage dans le temps (time travel)
  • les lecteurs de longue durée
  • la reprise opérationnelle
  • l’investigation d’un retour arrière

Ne désactivez pas les contrôles de sécurité de la rétention dans le code de production courant.

Si une rétention plus courte est réellement nécessaire, traitez-la comme une décision opérationnelle aux conséquences connues.


34. Lire une version antérieure d’une table Delta pour investiguer

Time travel par version :

previous = (
    spark.read
    .format("delta")
    .option(
        "versionAsOf",
        42,
    )
    .table("sales")
)

Par horodatage :

previous = (
    spark.read
    .format("delta")
    .option(
        "timestampAsOf",
        "2026-10-03T12:00:00Z",
    )
    .table("sales")
)

Utilisez le time travel pour :

  • le débogage
  • la comparaison
  • l’analyse de reprise

La disponibilité dépend de l’historique de transactions et des fichiers de données conservés.

VACUUM peut supprimer définitivement des fichiers nécessaires aux versions antérieures.


35. Examiner l’historique Delta

DESCRIBE HISTORY sales;

Utilisez l’historique pour investiguer :

  • les écritures
  • les merges
  • les écrasements
  • les opérations de maintenance
  • les horodatages
  • les métadonnées des opérations

C’est souvent le premier endroit à consulter lorsqu’une table a changé de manière inattendue.


36. Comparer les comptages avant et après les écritures

Avant :

source_count = source.count()

Après :

target_count = (
    spark.table("sales")
    .count()
)

Un simple comptage de lignes prouve rarement la justesse à lui seul, mais c’est un signal de rapprochement utile.

Pour les chargements de production, validez également :

  • les clés métier distinctes
  • le nombre de valeurs nulles
  • les identifiants de lot
  • les montants agrégés
  • la plage de dates concernée

37. Rapprocher les clés métier après un upsert

duplicate_target_keys = (
    spark.table("sales")
    .groupBy("sale_id")
    .count()
    .filter(
        F.col("count") > 1
    )
)

duplicate_target_keys.show(
    50,
    truncate=False,
)

Si le contrat de la cible stipule que sale_id est unique, des lignes en double constituent un problème de justesse, que la transaction Delta elle-même ait réussi ou non.

Delta fournit la transactionnalité au niveau des fichiers et de la table, pas des contraintes automatiques d’unicité des clés métier pour des écritures Spark arbitraires.


38. Stocker les métadonnées d’exécution pour les chargements incrémentaux

Exemples de colonnes :

output = (
    source
    .withColumn(
        "pipeline_run_id",
        F.lit(run_id),
    )
    .withColumn(
        "ingested_at_utc",
        F.current_timestamp(),
    )
)

Cela améliore :

  • la traçabilité
  • l’investigation des doublons
  • l’analyse des rejeux
  • les décisions de retour arrière

Évitez de placer des secrets ou des données opérationnelles sensibles dans les colonnes de métadonnées.


39. Éviter de lire et de réécrire toute la cible pour une petite modification incrémentale

Mauvais modèle :

target = spark.table("sales")
combined = target.unionByName(source)
# dedupe everything
# overwrite whole table

Mieux :

petite source incrémentale
→ dédoublonner la source
→ MERGE dans la cible

Privilégiez les opérations incrémentales ciblées lorsque c’est possible.

Les réécritures complètes de table créent inutilement :

  • des E/S
  • du shuffle
  • des fichiers obsolètes
  • du travail de maintenance
  • une exposition à la concurrence

40. Garder l’ingestion brute en ajout seul lorsque c’est possible

Une architecture robuste est :

Bronze
  événements/fichiers source en ajout seul

Silver
  MERGE / dédoublonnage / logique de correction

Gold
  tables organisées prêtes à être consommées

Cela conserve l’historique source tout en permettant des transformations avec état contrôlées en aval.

Ne modifiez pas de façon répétée des tables brutes alignées sur la source, sauf si le contrat source l’exige réellement.

Interpréter le résultat

Modèle Cas d’usage le plus adapté
append Nouvelles lignes immuables
overwrite Reconstruction complète voulue
MERGE Upsert / réconciliation incrémentale
staging + MERGE Ingestion concurrente dans une cible partagée
partitionnement Élagage, cycle de vie ou isolation des écrivains
OPTIMIZE Compacter/réorganiser les fichiers pour des lectures plus efficaces
Z-Order Améliorer le saut de fichiers pour des filtres sélectifs répétés
V-Order Optimisation de l’organisation Parquet de Fabric pour les consommateurs à forte intensité de lecture
VACUUM Supprimer définitivement les anciens fichiers non référencés
time travel Investiguer/lire des versions historiques de la table
DESCRIBE HISTORY Auditer les opérations Delta

La distinction importante est la suivante :

écriture réussie sur le plan transactionnel
!=
écriture correcte sur le plan métier

Vous devez toujours valider :

  • les clés métier
  • le nombre de lignes
  • les doublons
  • les agrégats
  • la fenêtre de chargement

Points à vérifier

Le nombre de lignes de la cible augmente à chaque relance

Votre chargement n’est probablement pas idempotent.

Vérifiez :

  • le rejeu d’ajouts
  • l’absence de correspondance sur la clé métier
  • des identifiants de lot instables

MERGE touche beaucoup plus de données que prévu

Vérifiez :

  • la sélectivité de la condition de merge
  • l’élagage des partitions
  • l’organisation des données
  • la taille de la source
  • l’organisation des fichiers de la cible

Un merge correct mais trop large peut tout de même coûter cher.

Des traitements concurrents échouent pendant les écritures

Vérifiez si les écrivains :

  • modifient des fichiers ou partitions de la cible qui se chevauchent
  • exécutent des merges en conflit
  • lancent de la maintenance pendant l’ingestion

Envisagez :

  • un ajout en staging
  • l’isolation des écrivains
  • une réconciliation sérialisée
  • des nouvelles tentatives ciblées

La table contient de nombreux petits fichiers

Causes probables :

  • des ajouts fréquents de petite taille
  • un trop grand nombre de partitions d’écriture
  • des effets secondaires du low shuffle merge
  • des modèles de micro-lots

Mesurez l’impact, puis envisagez la maintenance de la table.

Les lectures ralentissent après de nombreuses mises à jour ou merges

Examinez :

  • le nombre de fichiers
  • la taille des fichiers
  • l’organisation
  • les vecteurs de suppression (deletion vectors) et le comportement du runtime
  • le besoin d’un OPTIMIZE
  • les colonnes fréquemment filtrées

Les anciennes versions de la table ne fonctionnent plus

Vérifiez si VACUUM a supprimé des fichiers historiques nécessaires.

Les métadonnées du journal Delta ne peuvent pas, à elles seules, restaurer des fichiers supprimés définitivement.

Notes de production

Delta fournit des transactions ACID sur la table, pas des contraintes métier arbitraires

Delta protège les commits de la table contre les écritures partielles.

Il n’impose pas automatiquement :

  • l’unicité
  • l’intégrité référentielle
  • une sémantique d’une ligne par clé métier

Validez-les vous-même.

Le Low Shuffle Merge de Fabric est déjà activé par défaut

Ne perdez pas de temps à « optimiser » en l’activant, sauf si vous diagnostiquez une différence de configuration ou testez un comportement.

Concentrez-vous d’abord sur la taille de la source, les clés de merge, les fichiers touchés et le déséquilibre (skew).

Les écritures concurrentes exigent une conception tenant compte de l’organisation des données

Delta utilise un contrôle de concurrence optimiste.

Des ajouts indépendants sont moins sujets aux conflits que des mises à jour ou merges qui se chevauchent.

En forte concurrence :

staging en ajout seul
→ réconciliation centralisée

est souvent plus simple à exploiter.

OPTIMIZE et VACUUM résolvent des problèmes différents

OPTIMIZE
→ réécrit/compacte/réorganise les fichiers actuels

VACUUM
→ supprime les anciens fichiers non référencés

N’utilisez pas l’un comme substitut de l’autre.

VACUUM affecte la capacité de reprise

Une fois les fichiers obsolètes supprimés, les versions historiques qui en dépendent ne sont plus lisibles.

La rétention est un choix de reprise opérationnelle, pas seulement un paramètre de coût de stockage.

Les valeurs par défaut de V-Order ont évolué

Les valeurs par défaut des espaces de travail et des runtimes Fabric ont changé.

Ne supposez pas que des recommandations écrites pour d’anciens espaces de travail Fabric correspondent à un runtime actuel.

Examinez la configuration réelle.

Tenir la maintenance des tables à l’écart des pics d’écriture lorsque c’est possible

OPTIMIZE, VACUUM et les merges lourds consomment des ressources et peuvent interférer avec les charges d’écriture concurrentes.

Planifiez la maintenance aux moments où elle minimise la contention opérationnelle.

Le partitionnement n’est pas obligatoire

Ne copiez pas automatiquement les modèles de partitionnement de type Hive.

Delta peut offrir de bonnes performances sans partitionnement physique pour de nombreuses charges de travail.

Ne partitionnez que lorsque la taille des données et les modèles d’accès et d’écriture le justifient.

Erreurs fréquentes

1. Utiliser l’ajout pour un flux modifiable et rejouable

Une relance peut créer des doublons.

Adoptez une stratégie d’idempotence durable.

2. Utiliser l’écrasement à chaque relance

Cela transforme de petites modifications incrémentales en réécritures complètes et coûteuses de la table.

3. Utiliser whenMatchedUpdateAll() sans réfléchir au schéma

Des colonnes source ajoutées par commodité peuvent involontairement entrer dans le contrat de la cible.

Utilisez des correspondances explicites lorsque la stabilité compte.

4. Faire un merge avec des clés source en double

La source entrante doit avoir une sémantique de clé métier déterministe.

Dédupliquez délibérément avant le merge.

5. Partitionner par un identifiant à forte cardinalité

Cela crée beaucoup trop de minuscules répertoires et fichiers, et un mauvais comportement opérationnel.

6. Appeler repartition(1) avant chaque écriture

Une seule partition de sortie est un goulot d’étranglement, pas une optimisation.

7. Exécuter VACUUM pour accélérer les requêtes

VACUUM sert principalement à nettoyer le stockage.

Utilisez OPTIMIZE et l’optimisation de l’organisation des données pour les performances de lecture.

8. Réduire la rétention de VACUUM sans comprendre le time travel

Les fichiers supprimés ne peuvent plus être utilisés ensuite pour les versions historiques.

9. Considérer une transaction Delta réussie comme la preuve que les métriques sont correctes

Une transaction peut être parfaitement valide alors que la clé métier ou la logique source est erronée.

Rapprochez les données.

10. Relancer toutes les exceptions d’écriture

Ne relancez que les erreurs réellement transitoires ou liées à des conflits.

Un schéma incorrect ou une logique de merge erronée doivent échouer de façon visible.

Étape suivante

Utilisez le modèle d’écriture pour choisir l’action suivante.

  • Uniquement de nouveaux événements immuables → faites un ajout et ajoutez des contrôles de rejeu et de lot.
  • Les relances créent des doublons → mettez en place une idempotence par clé ou MERGE.
  • Des lignes existantes peuvent changer → utilisez MERGE avec une véritable clé métier.
  • La source contient des clés en double → dédupliquez avec un ordre déterministe avant d’écrire.
  • Des écrivains concurrents entrent en conflit → faites un ajout en staging et réconciliez avec un merge contrôlé.
  • Le merge scanne trop de données de la cible → améliorez la sélectivité du merge, la stratégie de partitionnement et d’organisation, ainsi que le filtrage de la source.
  • La table contient de nombreux petits fichiers → examinez le partitionnement à l’écriture, puis envisagez OPTIMIZE.
  • Le stockage continue de croître après des mises à jour ou des merges → revoyez la rétention de VACUUM en toute sécurité.
  • Les anciennes versions sont nécessaires à la reprise → protégez la rétention avant d’exécuter un vacuum.
  • Les lectures restent lentes malgré des modèles d’écriture corrects → passez à Performance des notebooks Fabric et à l’analyse de l’organisation des tables.

← Tous les aide-mémoire