Dépannage des erreurs SQL et schéma de Spark

Utilisez ce guide pour diagnostiquer et résoudre les erreurs SQL de requêtes, de schémas et de métadonnées dans les jobs Microsoft Fabric Spark, y compris les exceptions d’analyse, les changements de comportement entre versions, les tables ou vues non résolues, et les erreurs d’inférence de schéma Parquet. Pour d’autres erreurs de tâches Spark, voir l’aperçu des erreurs Spark dans Microsoft Fabric.

Comportement incohérent entre les versions Spark

L’erreur INCONSISTENT_BEHAVIOR_CROSS_VERSION indique que votre application Spark produit des résultats différents, échoue ou se comporte différemment après un changement de version à l’exécution. Le même code et les données qui ont travaillé sur la version précédente produisent désormais une sortie inattendue, des erreurs ou une dégradation des performances.

Matrice de compatibilité du runtime Fabric

Composant Durée 1.2 Durée 1.3 Durée 2.0
Apache Spark 3.4 3,5 4.1
Java 11 11 21
Scala 2.12 2.12 2.13
Python 3.10 3.11 3.13
R 4,2 4.4 4,5
Lac Delta 2.4 3.2 4,2

Catégories courantes

Catégorie Examples
Incompatibilité date/heure / horodatage Différentes analyse, Grégorien proleptique et calendrier julian
Différences entre les résultats de la requête Nombres de lignes, valeurs ou classements de colonnes différents
Nouvelles erreurs sur le code existant ClassNotFoundException, suppression de l’API obsolète
Régression des performances Le même travail prend beaucoup plus de temps
Compatibilité Delta Lake InvalidProtocolVersionException
Incompatibilité entre la bibliothèque et la dépendance modifications de version de package Python, mise à niveau scala/Java

Catégorie A : incompatibilité datetime et horodatage

Pourquoi cela se produit : Spark 3.0+ passe du calendrier grégorien julian/grégorien hybride au calendrier grégorien proleptique. Les formats Parquet INT96 et datetime écrits avec l’ancien comportement peuvent maintenant être mal interprétés. Les réglages de date et heure hérités peuvent ne pas se propager correctement en mode haute concurrence.

Étape 1 : Identifiez si cela vous affecte. Vos données/flux de travail impliquent-ils :

  • Dates historiques (antérieures à 1900 ou antérieures à 1582) ?

  • Fichiers/tables Parquet créés avant une mise à niveau récente ?

  • Échecs uniquement dans les environnements mis à niveau ou à haute concurrence ?

  • Journaux d’erreurs contenant INCONSISTENT_BEHAVIOR_CROSS_VERSION ou READ_ANCIENT_DATETIME ?

Étape 2 : Définissez la configuration Spark pour les modes de base datetime :

spark.conf.set("spark.sql.parquet.int96RebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.int96RebaseModeInWrite", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInWrite", "CORRECTED")

Important

Validez avant utilisation en production. Avant d’appliquer le CORRECTED mode à un pipeline de production, testez d’abord sur un exemple de jeu de données. Définir CORRECTED pour des données écrites à l’origine avec le comportement LEGACY peut entraîner des décalages silencieux de valeurs de date pour les dates historiques (antérieures à 1582). Exécutez SELECT MIN(date_col), MAX(date_col) FROM my_table sur un échantillon et comparez les résultats d’un paramètre à l’autre avant de lancer l’exécution complète d’un pipeline. Si les résultats diffèrent selon les dates historiques, utilisez LEGACY les données existantes et planifiez une migration vers CORRECTED de nouvelles données.

  • Utilisez « CORRIGÉ » pour un comportement nouveau et cohérent entre les environnements (recommandé).

  • Utilisez « LEGACY » uniquement si vous avez des données écrites avec des environnements d’exécution antérieurs à la mise à niveau et que vous ne parvenez plus à relire.

Ou via %%configure:

%%configure  
{  
"conf": {  
"spark.sql.parquet.int96RebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.int96RebaseModeInWrite": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInWrite": "CORRECTED"  
}  
}

Important

En mode haute concurrence, les réglages doivent être appliqués au niveau du carnet/session ; Les paramètres d’environnement ou de cluster peuvent ne pas se propager.

Étape 3 : Valider:

  • Réexécutez les travaux/notebooks ayant échoué.

  • Vérifiez que le paramètre a pris effet :

print(spark.conf.get("spark.sql.parquet.datetimeRebaseModeInRead"))

Catégorie B : modifications de version scala, Java ou Python

Environnement d’exécution Fabric Spark Java Scala Python
Durée 1.2 3.4 11 2.12 3.10
Durée 1.3 3,5 11 2.12 3.11
Durée 2.0 4.1 21 2.13 3.13

Que faire :

  • Regénérez les JAR personnalisés avec la nouvelle version de Scala/Spark. Utilisez la portée fournie pour Spark dans Maven/SBT.

  • Pour ClassNotFoundException avec des FICHIERS JARs tiers, vérifiez que le fichier JAR a le suffixe Scala correct (par exemple, _2.12).

  • Pour Python ModuleNotFoundError, installez explicitement les packages manquants :

%pip install pandas==2.0.3

Catégorie C — Incompatibilité du protocole Delta Lake

Pourquoi cela se produit : Delta Lake utilise des versions de protocole pour suivre les fonctionnalités de table. Les mises à niveau de protocole sont irréversibles.

Scénario Result
Vecteurs de suppression activés dans l’environnement d’exécution 1.2 et lus dans l’environnement d’exécution 1.1 Échec : Runtime 1.1 ne prend pas en charge le protocole
Table créée avec TimestampNTZ sur Runtime 1.2 Nécessite la version 3 du lecteur : le runtime 1.1 ne peut pas lire
Tableau écrit en externe avec Writer version 6 Peut ne pas être pris en charge par le runtime Fabric Delta

Que faire :

  • Avancer, pas vers l’arrière : utilisez un runtime qui prend en charge le protocole.

  • Évitez de mélanger différents runtimes sur les mêmes tables Delta.

  • Vérifiez le protocole avant d’activer les nouvelles fonctionnalités :

DESCRIBE DETAIL my_table

Catégorie D — Modifications comportementales Spark SQL

Pourquoi cela se produit : Les versions de Spark modifient les comportements par défaut (mode ANSI, règles de cast, gestion null).

Que faire :

  • Si le mode ANSI provoque un comportement plus strict :
spark.conf.set("spark.sql.ansi.enabled", "false")
  • Pour les modifications d’analyse de date/heure :
spark.conf.set("spark.sql.legacy.timeParserPolicy", "LEGACY")
  • Pour une vérification de type INSERT plus stricte :
spark.conf.set("spark.sql.storeAssignmentPolicy", "LEGACY")

Les réglages hérités sont une solution à court terme. Prévoyez de mettre à jour votre code pour le nouveau comportement.

AnalysisException dans Spark

Une exception AnalysisException est levée pendant la phase d’analyse de requête de Spark, avant que des données ne soient traitées. Spark valide votre requête SQL ou DataFrame et vérifie que toutes les tables, colonnes, fonctions et types référencés existent et sont compatibles. Si quelque chose n’est pas vérifié, Spark rejette immédiatement la requête. Il s’agit presque toujours d’un problème côté utilisateur : une faute de frappe, une table manquante, une incompatibilité de schéma ou une opération non prise en charge. Étant donné qu’elle échoue tôt, aucune ressource de calcul n’est gaspille.

Modèles d’erreur classiques :

org.apache.spark.sql.AnalysisException: Table or view not found: my_table

org.apache.spark.sql.AnalysisException: [UNRESOLVED_COLUMN.WITH_SUGGESTION]  
A column or function parameter with name 'NotARealColumn' cannot be resolved.  
Did you mean one of the following? [Revenue, GrossRevenue, Rating, Branch, City]

org.apache.spark.sql.AnalysisException: Data type mismatch: ...

Étape 1 : Lire attentivement le message d’erreur

Le AnalysisException message contient presque toujours :

  • Ce qui a échoué : table, colonne, fonction ou opération

  • Pourquoi elle a échoué : introuvable, incompatibilité de type, référence ambiguë

  • Ce qui était disponible : liste de colonnes, de tables ou de types valides

Exemple de faute de frappe de nom de colonne :

AnalysisException: cannot resolve '`salery`' given input columns:  
[employee.name, employee.salary, employee.dept]

L’erreur indique que vous avez tapé « salery » lorsque la colonne est réellement appelée « salaire ».

Étape 2 : Faire correspondre votre erreur à un scénario

Comparez votre texte d’erreur avec les scénarios suivants, puis appliquez la correction correspondante.

Scénario A : table ou vue introuvable

Table or view not found: my_table
  • Faute de frappe dans le nom de la table : vérifiez l’orthographe et la casse.

  • Mauvaise base de données/schéma : utilisez un nom pleinement qualifié :

spark.sql("SELECT * FROM my_catalog.my_schema.my_table")
  • Affichage temporaire expiré : si la session a redémarré, la vue est supprimée. Recréez-le :
df.createOrReplaceTempView("my_table")
  • Tableau non encore écrit : vérifiez que le bloc-notes/cellule en amont est terminé.

  • Lakehouse non attaché — dans Fabric, vérifiez que le lakehouse est attaché à votre notebook.

Scénario B : colonne introuvable

[UNRESOLVED_COLUMN.WITH_SUGGESTION] A column or function parameter  
with name 'X' cannot be resolved.
  • Erreur typographique dans le nom de la colonne : comparer avec les suggestions dans l’erreur.

  • La colonne a été renommée ou supprimée en amont : vérifiez le schéma :

df.printSchema()
  • La colonne existe dans un autre DataFrame : après une jointure, référencez la source correcte :
df1.join(df2, df1.id == df2.id).select(df1.id, df2.name)

Scénario C : référence de colonne ambiguë

[AMBIGUOUS_REFERENCE] Reference 'Quantity' is ambiguous,  
could be: [a.Quantity, b.Quantity]

Que faire : Qualifiez la colonne avec l’alias de table :

# SQL  
spark.sql("""
  SELECT a.id, b.name  
  FROM table_a a JOIN table_b b ON a.id = b.id  
""")

# DataFrame API  
df1.alias("a").join(df2.alias("b"), col("a.id") == col("b.id")) \
  .select("a.id", "b.name")

Pour obtenir la liste complète des fonctions SQL disponibles, consultez Fonctions intégrées Spark SQL.

Scénario D : incompatibilité de type de données

Data type mismatch: differing types in '(col_a = col_b)': int vs string

Que faire : Effectuez une conversion explicite en type commun :

from pyspark.sql.functions import col  
df = df1.join(df2, df1["id"].cast("string") == df2["id_str"])

Scénario E — Fonction introuvable

Undefined function: 'my_function'

Que faire :

  • Erreur typographique : vérifiez la référence de fonction SQL de Spark.

  • UDF non inscrite :

spark.udf.register("my_function", my_function)
  • Fonction supprimée dans une mise à niveau de version : consultez le guide de migration.

Scénario F : incompatibilité de schéma lors de l’écriture / INSERT

[_LEGACY_ERROR_TEMP_DELTA_0007] A schema mismatch detected  
when writing to the Delta table...

Que faire :

  • Vérifiez ce que la cible attend :
spark.sql("DESCRIBE my_table").show()
  • Vérifiez ce que vous écrivez :
df.printSchema()
  • Aligner les colonnes et les types :
df = df.select("col_a", "col_b", "col_c")  
df = df.withColumn("col_a", col("col_a").cast("int"))
  • Pour l’évolution du schéma Delta :
df.write.format("delta") \
  .option("mergeSchema", "true") \
  .mode("append") \
  .save("/path/to/table")

Scénario G — Delta Lake AnalysisException

Error Cause Réparer
Impossible d’écrire sur une table qui nécessite la version N de lecture/écriture Incompatibilité du protocole Delta Utiliser un runtime qui prend en charge le protocole requis
Incompatibilité de schéma détectée lors de l’écriture dans la table Delta Les nouvelles données ont des colonnes supplémentaires/manquantes Activer la fusion de schémas ou corriger le schéma
Format incompatible détecté Écriture vers un chemin Delta dans un format non Delta Vérifier que le chemin cible est une table Delta
Opération non autorisée : impossible de modifier les colonnes de partition Tentative de modification du partitionnement Créer une table avec le partitionnement souhaité

Pour plus d’informations sur l’évolution du schéma Delta Lake, les fonctionnalités de table et les versions de protocole, consultez la documentation Delta Lake.

Scénario H — Chemin d’accès /fichier introuvable

Path does not exist: abfss://container@account.dfs.core.windows.net/my/path

Que faire :

  • Erreur typographique dans le chemin : vérifiez le nom du conteneur, le compte de stockage et le chemin du fichier.

  • Le fichier a été supprimé ou déplacé : vérifiez que le fichier existe dans votre explorateur lakehouse/storage.

  • Compte de stockage ou espace de travail incorrect.

  • Problème d’autorisations : l’erreur indique parfois « chemin introuvable » lorsqu’elle est réellement « accès refusé ».

Important

Dans Fabric notebooks, la lecture à partir du dossier nbresource avec Spark n'est pas prise en charge. Utilisez les entrées/sorties de fichiers Python (open()) au lieu de spark.read pour les fichiers de ressources du notebook. Utilisez .save() au lieu de .saveAsTable() lors de l’écriture dans un chemin explicite.

Scénario I : opération non prise en charge

Unsupported operation: ALTER TABLE ADD COLUMNS ... for non-Delta tables

Que faire : Vérifiez si la fonctionnalité nécessite un format Delta. Convertissez si nécessaire :

from delta.tables import DeltaTable  
DeltaTable.convertToDelta(spark, "parquet.`/path/to/table`")

Techniques de débogage

  • Imprimez le schéma :
df.printSchema()  
spark.sql("DESCRIBE EXTENDED my_table").show(truncate=False)
  • Répertorier les tables disponibles :
spark.sql("SHOW TABLES").show()
  • Répertorier les colonnes disponibles :
spark.sql("DESCRIBE my_table").show()
  • Testez les requêtes progressivement — procédez étape par étape :
spark.sql("SELECT * FROM my_table LIMIT 5").show()  
spark.sql("SELECT col_a, col_b FROM my_table LIMIT 5").show()
  • Vérifier la configuration Spark :
for k, v in sorted(spark.sparkContext.getConf().getAll()):  
    print(f"{k} = {v}")

Tableau de résolution des problèmes de référence rapide

Le message d’erreur contient Cause la plus probable Première action
Table ou vue introuvable Table manquante ou base de données incorrecte Vérifier l’orthographe ; Utiliser un nom pleinement qualifié
impossible de résoudre + nom de colonne Colonne manquante ou mal orthographiée Exécuter df.printSchema() ou décrire une table
Référence... est ambiguë Nom de colonne en double après jointure Qualifier avec l’alias de table : a.id
Incompatibilité de type de données Types incompatibles en comparaison Convertir des colonnes vers un type commun
Fonction non définie UDF manquante ou non inscrite Vérifier l’orthographe ; enregistrer l’UDF si elle est personnalisée
Impossible d’écrire des données incompatibles Incompatibilité de schéma lors de l’écriture Comparer les schémas source/cible ; cast/select
Le chemin d’accès n’existe pas Chemin d’accès de fichier incorrect ou fichier supprimé Vérifier le chemin d’accès dans l’Explorateur de stockage
Impossible de caster en toute sécurité Vérification stricte des types lors de l’instruction INSERT Caster une colonne explicitement avant d’écrire
DeltaAnalysisException Problème de schéma/protocole propre à Delta Voir la section Delta Lake ci-dessus
Opération non prise en charge Fonctionnalité non disponible pour le format de tableau Vérifier si le format Delta est requis

Table ou vue introuvable

Code d’erreur :Spark_User_MetaStore_TableOrViewNotFound

Que signifie cette erreur ?

Spark ne pouvait pas résoudre un nom de table ou de vue contre le Metastore lors de l’analyse des requêtes – avant que Spark ne traite des données. La table n’existe soit pas sous le nom que vous avez utilisé, soit se trouve dans un autre contexte de base de données ou d’espace de travail, soit a été supprimée ou renommée.

Messages d’erreur à rechercher

Table or view not found: my_table
[TABLE_OR_VIEW_NOT_FOUND]
AnalysisException: Table or view not found

Causes et correctifs courants

Examinez ces causes courantes pour trouver celle qui correspond à votre situation, puis appliquez sa solution.

Faute de frappe ou nom de tableau non qualifié

Cette cause est la plus courante. Vérifiez l’orthographe, puis utilisez des noms entièrement qualifiés pour que la résolution des noms ne dépende pas du contexte actuel de la base de données.

-- Prefer fully qualified names
SELECT * FROM my_lakehouse.dbo.sales_orders;

-- List what actually exists
SHOW TABLES IN my_lakehouse;

Mauvaise base de données ou mauvais contexte de la maison du lac

La table existe, mais elle se trouve dans une base de données, un schéma ou une maison de lac différente de celle actuellement attachée au carnet. Dans Fabric, un nom de table non qualifié se résout contre la maison de lac par défaut du carnet.

  • Vérifiez quelle maison du lac est attachée par défaut dans l’explorateur de carnets.
  • Exécutez spark.catalog.currentDatabase() pour confirmer le contexte actif de la base de données.

Table supprimée, renommée ou pas encore créée

Un pipeline en amont, un autre notebook ou un autre utilisateur a supprimé ou renommé la table. Dans les pipelines à plusieurs étapes, une activité en aval peut s’exécuter avant que l’étape de création de table en amont ne soit terminée.

  • Vérifiez les dépendances du pipeline et l’ordre des activités.
  • Ajoutez un test d’existence avant de lire : spark.catalog.tableExists("my_lakehouse.dbo.sales_orders").

Redémarrage de session libéré des vues temporaires

Vues temporaires créées uniquement createOrReplaceTempView() en direct pour la session Spark actuelle. Si la session redémarre (timeout, redémarrage du noyau ou %%configure redémarrage), les vues temporaires précédentes disparaissent et vous devez les recréer.

Référence multi-espaces de travail sans accès

Vous avez référencé une table dans la cabane lacustre d’un autre espace de travail sans les autorisations requises, ou le raccourci qui soutient la table pointe vers un lieu qui n’existe plus.

Remarque

Les erreurs avec ce code provenant d’une cellule SQL de notebook apparaissent comme AnalysisException. Pour plus d’informations, voir AnalysisException dans Spark. Des erreurs issues des définitions de tâches Spark et des activités de pipeline apparaissent directement sous ce code. Les étapes de résolution sont les mêmes.

Tableau de résolution des problèmes de référence rapide

Symptôme Cause la plus probable Première action
Échec uniquement avec un nom non qualifié Mauvais laca-lac ou base de données par défaut Utilisez catalog.schema.table.
Ça a marché hier, ça échoue aujourd’hui Tableau retiré ou renommé en amont Vérifier la lignée des pipelines
Échec après un redémarrage du noyau Vue temporaire perdue avec la session Recréer la vue temporaire
Échecs seulement pour certains utilisateurs Autorisations inter-espaces de travail Vérifier l’accès à l’espace de travail

Impossible d’inférer le schéma de Parquet

Code d’erreur :Spark_User_Parquet_NeedsManualSchema

Que signifie cette erreur ?

Spark ne peut pas déduire automatiquement un schéma lors de la lecture de fichiers Parquet. Comme les fichiers Parquet incluent leurs propres métadonnées de schéma, cette erreur signifie généralement que Spark n’a trouvé aucun fichier Parquet utilisable sur le chemin. Le répertoire peut être vide, ne contenir que des fichiers non-Parquet, ou contenir des fichiers dont les schémas sont incohérents entre eux.

Messages d’erreur à rechercher

Spark_User_Parquet_NeedsManualSchema
Unable to infer schema for Parquet
Schema must be specified manually

Pourquoi cette erreur se produit

  • Vous essayez de lire à partir d’un répertoire vide – il n’existe aucun fichier Parquet à partir duquel déduire un schéma.
  • Le répertoire contient des fichiers Parquet avec des schémas incohérents (par exemple, écrits par différentes versions de pipeline).
  • Le chemin existe mais ne contient pas de métadonnées Parquet (mauvais chemin, ou alors les fichiers sont en réalité CSV ou JSON).

Étapes de résolution

  1. Vérifiez si le répertoire est vide avant de lire :

    files = notebookutils.fs.ls("abfss://path")
    if len(files) == 0:
        print("Directory is empty - no schema to infer")
    
  2. Si un répertoire vide est un état légitime (par exemple, pas encore de données pour une partition), fournissez explicitement le schéma :

    from pyspark.sql.types import StructType, StructField, StringType, IntegerType
    
    schema = StructType([
        StructField("name", StringType(), True),
        StructField("age", IntegerType(), True),
    ])
    
    df = spark.read.schema(schema).parquet("abfss://path")
    
  3. Si les schémas sont incohérents entre les fichiers, activez la fusion de schémas pour concilier les différences compatibles :

    df = spark.read.option("mergeSchema", "true").parquet("abfss://path")
    
  4. Vérifiez que les fichiers sont bien du Parquet – vérifiez les extensions de fichiers et confirmez que le processus d’écriture a réussi.

Remarque

mergeSchema Concilie les différences de schéma compatibles (colonnes ajoutées) mais ne peut pas corriger les types conflictuels pour la même colonne. Pour les conflits de types, lisez les groupes de fichiers séparément, faites un casting vers un schéma commun, et faites l’union.

Tableau de résolution des problèmes de référence rapide

Symptôme Cause la plus probable Première action
Erreur sur un répertoire vide Aucun fichier Parquet pour déduire un schéma Fournir le schéma explicitement
Échec après avoir mixé les versions des fichiers Schémas incohérents entre les fichiers Activez mergeSchema
Path ne possède aucune métadonnée Parquet Mauvais chemin, ou les fichiers sont CSV ou JSON Vérifier les extensions de fichiers et le chemin