Gestion des erreurs dans Azure Databricks

  • Article

S’applique à : oui coché Databricks SQL case marquée oui Databricks Runtime 12.2 et versions ultérieures

Composants des erreurs

Quand Azure Databricks génère une erreur, il inclut les composants suivants :

  • Classe d’erreur

    Une chaîne descriptive, lisible par l’homme et unique de la condition d’erreur.

    Certaines classes d’erreur incluent des sous-classes.

    Par exemple : ‘TABLE_OR_VIEW_NOT_FOUND’ et ‘INCOMPLETE_TYPE_DEFINITION.ARRAY’.

    Pour obtenir la liste de toutes les classes d’erreur, voir Classes d’erreur.

  • SQLSTATE

    Une chaîne d’une longueur de cinq caractères regroupant des classes d’erreur dans un format standard pris en charge par plusieurs produits et API.

    Par exemple : '42P01'

    Pour obtenir une liste de tous les SQLSTATE utilisés par Azure Databricks, voir SQLSTATEs.

  • Message paramétrables

    Message d’erreur avec des espaces réservés pour les paramètres.

    Par exemple : ‘TABLE_OR_VIEW_NOT_FOUND’ inclut le message suivant :

    The table or view <relationName> cannot be found.

    Vous pouvez utiliser le message paramétrable pour afficher un message d’erreur en mappant les valeurs de paramètre de message aux balises du paramètre <parameter>.

  • Paramètres de message

    Mappage des paramètres et des valeurs qui fournit des informations supplémentaires sur l’erreur. Par exemple : 'relationName' -> 'main.default.tab1'.

  • Message

    Message d’erreur totalement rendu, notamment la classe d’erreur et le SQLSTATE, rempli avec les paramètres. Par exemple :

    [TABLE_OR_VIEW_NOT_FOUND] The table or view `does_not_exist` cannot be found. Verify the spelling and correctness of the schema and catalog.
If you did not qualify the name with a schema, verify the current_schema() output, or qualify the name with the correct schema and catalog.
To tolerate the error on drop use DROP VIEW IF EXISTS or DROP TABLE IF EXISTS. SQLSTATE: 42P01; line 1 pos 14;
'Project [*]
+- 'UnresolvedRelation [does_not_exist], [], false

Avertissement

Message et Message paramétrable ne sont pas stables dans les mises en production. Le texte du message peut être modifié ou localisé sans préavis. Pour gérer une condition d’erreur par programme, utilisez la Classe d’erreur, SQLSTATE et Paramètres de message à la place.

Traitement des conditions d’erreur

S’applique à : coche marquée oui Databricks SQL case marquée oui Databricks Runtime 14.2 et versions ultérieures

Important

Cette fonctionnalité est disponible en préversion publique.

Azure Databricks fournit des API spécifiques au langage pour gérer des conditions d’erreur.

Python

Pour Python, utiliser pySparkException

  • PySparkException.getErrorClass() : renvoie la classe d’erreur de l’exception en tant que chaîne.
  • PySparkException.getMessageParameters() : renvoie les paramètres de message de l’exception en tant que dictionnaire.
  • PySparkException.getSqlState() : renvoie le SQLSTATE de l’expression en tant que chaîne.

Scala

Pour Scala, utiliser SparkThrowable

  • getErrorClass() : renvoie une classe d’erreur en tant que chaîne.
  • getMessageParameters() : renvoie les paramètres d’un message en tant que mappage.
  • getSqlState() : renvoie un SQLSTATE en tant que chaîne.

Exemples

  • Interceptez toute exception et affichez la classe d’erreur, les paramètres du message et SQLSTATE. Afficher également le message d’erreur par défaut

    Scala

    import org.apache.spark.SparkThrowable

try {
  spark.sql("SELECT * FROM does_not_exist").show()
}
catch {
  case ex: SparkThrowable =>
    println("Error Class       : " + ex.getErrorClass)
    println("Message parameters: " + ex.getMessageParameters())
    println("SQLSTATE          : " + ex.getSqlState)
    println(ex)
}

    Python

    from pyspark.errors import PySparkException

try:
  spark.sql("SELECT * FROM does_not_exist").show()
except PySparkException as ex:
  print("Error Class       : " + ex.getErrorClass())
  print("Message parameters: " + str(ex.getMessageParameters()))
  print("SQLSTATE          : " + ex.getSqlState())
  print(ex)

    Résultats

      Error Class       : TABLE_OR_VIEW_NOT_FOUND
  Message parameters: {'relationName': '`does_not_exist`'}
  SQLSTATE          : 42P01
  [TABLE_OR_VIEW_NOT_FOUND] The table or view `does_not_exist` cannot be found. Verify the spelling and correctness of the schema and catalog.
  If you did not qualify the name with a schema, verify the current_schema() output, or qualify the name with the correct schema and catalog.
  To tolerate the error on drop use DROP VIEW IF EXISTS or DROP TABLE IF EXISTS. SQLSTATE: 42P01; line 1 pos 14;
  'Project [*]
  +- 'UnresolvedRelation [does_not_exist], [], false

  • Interceptez le SQLSTATE 42P01 uniquement et affichez un message personnalisé :

    Scala

    import org.apache.spark.SparkThrowable

try {
  spark.sql("SELECT * FROM does_not_exist").show()
}
catch {
  case ex: SparkThrowable if (ex.getSqlState == "42P01") =>
    println("I'm so sorry, but I cannot find: " + ex.getMessageParameters().get("relationName"))
}

    Python

    from pyspark.errors import PySparkException

try:
  spark.sql("SELECT * FROM does_not_exist").show()
except PySparkException as ex:
  if (ex.getSqlState() == "42P01"):
    print("I'm so sorry, but I cannot find: " + ex.getMessageParameters()['relationName'])
  else:
    raise

    Résultats

    I'm so sorry, but I cannot find: `does_not_exist`

  • Interceptez la classe d’erreur TABLE_OR_VIEW_NOT_FOUND uniquement et affichez un message personnalisé :

    Scala

    import org.apache.spark.SparkThrowable

try {
  spark.sql("SELECT * FROM does_not_exist").show()
}
catch {
  case ex: SparkThrowable if (ex.getErrorClass == "TABLE_OR_VIEW_NOT_FOUND") =>
    println("I'm so sorry, but I cannot find: " + ex.getMessageParameters().get("relationName"))
}

    Python

    from pyspark.errors import PySparkException

try:
  spark.sql("SELECT * FROM does_not_exist").show()
except PySparkException as ex:
  if (ex.getErrorClass() == "TABLE_OR_VIEW_NOT_FOUND"):
    print("I'm so sorry, but I cannot find: " + ex.getMessageParameters()['relationName'])
  else:
    raise

    Résultats

    I'm so sorry, but I cannot find: `does_not_exist`

Exceptions levées par l’utilisateur

Azure Databricks fournit les fonctions suivantes pour lever des erreurs définies par l’utilisateur :

  • raise_error

    Permet de lever une exception avec un message d’erreur personnalisé.

  • assert_true

    Permet de lever une erreur avec un message d’erreur facultatif, si une condition n’est pas respectée.

Les deux fonctions renvoient une classe d’erreur ‘USER_RAISED_EXCEPTION’ et le SQLSTATE'P0001' avec un message défini par l’utilisateur.

Exemples

> SELECT raise_error('This is a custom error message');
 [USER_RAISED_EXCEPTION] This is a custom error message. SQLSTATE: P0001

> SELECT assert_true(1 = 2, 'One is not two!');
 [USER_RAISED_EXCEPTION] One is not two! SQLSTATE: P0001

> SELECT assert_true(1 = 2);
 [USER_RAISED_EXCEPTION] '(1 = 2)' is not true! SQLSTATE: P0001