Fehlerbehandlung in Azure Databricks

Gilt für: Databricks SQL Databricks Runtime 12.2 und höher

Fehlerkomponenten

Wenn Azure Databricks einen Fehler auslöst, enthält er die folgenden Komponenten:

• Fehlerklasse

  Eine beschreibende, lesbare Zeichenfolge, die für die Fehlerbedingung eindeutig ist

  Einige Fehlerklassen enthalten Unterklassen.

  Beispiel: TABLE_OR_VIEW_NOT_FOUND und INCOMPLETE_TYPE_DEFINITION.ARRAY

  Eine Liste aller Fehlerklassen finden Sie unter Fehlerklassen.

• SQLSTATE

  Eine fünfstellige Zeichenfolge, die Fehlerklassen in einem Standardformat gruppiert, das von vielen Produkten und APIs unterstützt wird

  Beispiel: '42P01'

  Eine vollständige Liste aller von Azure Databricks verwendeten SQLSTATE-Werte finden Sie unter SQLSTATE-Codes.

• Parametrisierte Meldung

  Die Fehlermeldung mit Platzhaltern für die Parameter

  Beispiel: TABLE_OR_VIEW_NOT_FOUND enthält die folgende Meldung:

  The table or view <relationName> cannot be found.
  

  Sie können die parametrisierte Nachricht verwenden, um eine Fehlermeldung zu rendern, indem Sie Meldungsparameter den Parametertags <parameter> zuordnen.

• Meldungsparameter

  Eine Zuordnung von Parametern und Werten, die zusätzliche Informationen zum Fehler bereitstellen. Beispiel: 'relationName' -> 'main.default.tab1'

• Meldung

  Die vollständig gerenderte Fehlermeldung, einschließlich der Fehlerklasse und des SQLSTATE-Werts, mit ausgefüllten Parametern. Beispiel:

  [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
  

Warnung

Meldung und Parametrisierte Meldung sind nicht über Versionen hinweg stabil. Der Meldungstext kann ohne Ankündigung geändert oder lokalisiert werden. Um eine Fehlerbedingung programmgesteuert zu behandeln, verwenden Sie stattdessen die Fehlerklasse, SQLSTATE und die Meldungsparameter.

Behandeln von Fehlerbedingungen

Gilt für: Databricks SQL Databricks Runtime 14.2 und höher

Wichtig

Dieses Feature befindet sich in der Public Preview.

Azure Databricks stellt sprachspezifische APIs zur Behandlung von Fehlerbedingungen bereit.

Python

Verwenden Sie für Python pySparkException.

• PySparkException.getErrorClass(): Gibt die Fehlerklasse der Ausnahme als Zeichenfolge zurück.
• PySparkException.getMessageParameters(): Gibt die Meldungsparameter der Ausnahme als Wörterbuch zurück.
• PySparkException.getSqlState(): Gibt den SQLSTATE-Wert der Ausnahme als Zeichenfolge zurück.

Scala

Verwenden Sie für Scala SparkThrowable.

• getErrorClass(): Gibt eine Fehlerklasse als Zeichenfolge zurück.
• getMessageParameters(): Gibt einen Meldungsparameter als Zuordnung zurück.
• getSqlState(): Gibt einen SQLSTATE-Wert als Zeichenfolge zurück.

Beispiele

• Erfassen Sie alle Ausnahmen und Anzeigefehlerklassen, Meldungsparameter und SQLSTATE-Werte. Zeigen Sie außerdem die Standardfehlermeldung an.

  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)
  

  Ergebnis

    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
  

• Erfassen Sie nur den SQLSTATE-Wert 42P01, und zeigen Sie eine benutzerdefinierte Meldung an:

  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
  

  Ergebnis

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

• Erfassen Sie nur die Fehlerklasse TABLE_OR_VIEW_NOT_FOUND, und zeigen Sie eine benutzerdefinierte Meldung an:

  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
  

  Ergebnis

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

Von Benutzer*innen ausgelöste Ausnahmen

Azure Databricks bietet die folgenden Funktionen zum Auslösen von benutzerdefinierten Fehlern:

• raise_error

  Löst eine Ausnahme mit einer benutzerdefinierten Fehlermeldung aus.

• assert_true

  Löst einen Fehler mit einer optionalen Fehlermeldung aus, wenn eine Bedingung nicht erfüllt wird.

Beide Funktionen geben die Fehlerklasse USER_RAISED_EXCEPTION und den SQLSTATE-Wert 'P0001' zusammen mit einer benutzerdefinierten Nachricht zurück.

Beispiele

> 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

Verwandte Themen

• assert_true-Funktion
• raise_error-Funktion