共用方式為

Azure Databricks 中的錯誤處理

  • 發行項

適用於： 核取記號為「是」 Databricks SQL 核取記號為「是」 Databricks Runtime 12.2 和更新版本

錯誤元件

當 Azure Databricks 引發錯誤時，它包含下列元件：

  • Error 類別

    錯誤條件中唯一的描述性人類可讀取字串。

    某些錯誤類別包含子元件。

    例如： TABLE_OR_VIEW_NOT_FOUND和 INCOMPLETE_TYPE_DEFINITION。ARRAY。

    如需所有錯誤類別的清單，請參閱 錯誤類別。

  • SQLSTATE

    五個字元長字串，將錯誤類別分組成許多產品和 API 所支援的標準格式。

    例如：'42P01'

    如需 Azure Databricks 使用之所有 SQLSTATEs 的完整清單，請參閱 SQLSTATEs。

  • 參數化訊息

    參數佔位元的錯誤訊息。

    例如： TABLE_OR_VIEW_NOT_FOUND 包含下列訊息：

    The table or view <relationName> cannot be found.

    您可以使用參數化訊息，將訊息參數值對應至參數卷標 <parameter>來轉譯錯誤訊息。

  • 訊息參數

    參數和值的對應，提供錯誤的其他資訊。 例如： 'relationName' -> 'main.default.tab1' 。

  • 訊息

    完全轉譯的錯誤訊息，包括錯誤類別和 SQLSTATE，並填入參數。 例如：

    [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

警告

訊息 和 參數化訊息 在版本之間不穩定。 訊息正文可能會變更或當地語系化，而不需通知。 若要以程式設計方式處理錯誤條件，請改用 Error 類別SQLSTATE和訊息參數。

處理錯誤狀況

適用於： 核取記號為「是」 Databricks SQL 核取記號為「是」 Databricks Runtime 14.2 和更新版本

重要

這項功能處於公開預覽狀態。

Azure Databricks 提供語言特定的 API 來處理錯誤狀況。

Python

針對 Python，請使用 pySparkException

  • PySparkException.getErrorClass()：傳回例外狀況的錯誤類別做為字串。
  • PySparkException.getMessageParameters()：傳回例外狀況的訊息參數做為字典。
  • PySparkException.getSqlState()：以 SQLSTATE 字串形式傳回表達式的 。

Scala

針對 Scala，請使用 SparkThrowable

  • getErrorClass()：傳回錯誤類別做為字串。
  • getMessageParameters()：傳回訊息參數做為對應。
  • getSqlState()：以字串傳回 SQLSTATE。

範例

  • 攔截任何例外狀況並顯示錯誤類別、訊息參數和 SQLSTATE。 同時顯示預設錯誤訊息

    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)

    結果

      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

  • 只攔截 SQLSTATE 42P01 並顯示自訂訊息：

    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

    結果

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

  • 只攔截錯誤類別 TABLE_OR_VIEW_NOT_FOUND 並顯示自訂訊息：

    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

    結果

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

用戶引發例外狀況

Azure Databricks 提供下列函式來引發使用者定義的錯誤：

  • raise_error

    引發具有自定義錯誤訊息的例外狀況。

  • assert_true

    如果不符合條件，則引發具有選擇性錯誤訊息的錯誤。

這兩個函式都會傳回錯誤類別 『USER_RAISED_EXCEPTION』，以及SQLSTATE'P0001'使用者定義的訊息。

範例

> 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