Azure Databricks 中的错误处理

2025-05-09

适用于：勾选“是” Databricks SQL Databricks Runtime 12.2 及更高版本

错误组件

当 Azure Databricks 引发错误时，错误包括以下组件：

错误条件

错误条件特有的用户可读的描述性字符串。

一些错误条件包括子条件。

例如：TABLE_OR_VIEW_NOT_FOUND 和 INCOMPLETE_TYPE_DEFINITION.ARRAY。

有关所有错误条件的列表，请参阅错误条件。
SQLSTATE

一个五个字符长的字符串，将错误条件分组为许多产品和 API 支持的标准格式。

例如：'42P01'

有关 Azure Databricks 使用的所有 SQLSTATE 的完整列表，请参阅 SQLSTATE。
参数化的消息

参数占位符的错误消息。

例如：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

警告

“消息”和“参数化的消息”跨版本不稳定。消息文本可能会更改或本地化，恕不另行通知。若要以编程方式处理错误条件，请改用错误条件SQLSTATE和消息参数。

处理错误条件

适用于：勾选“是” Databricks SQL、Databricks Runtime 14.2 及更高版本

重要

此功能目前以公共预览版提供。

Azure Databricks 提供特定于语言的 API 来处理错误条件。

SQL

适用于： Databricks SQL Databricks Runtime 16.3 及更高版本

对于 SQL，请使用复合语句语法来定义条件处理程序。

DECLARE EXIT HANDLER：为一组指定的错误条件、SQLSTATE或任何SQLEXCEPTION定义处理程序。
GET 诊断：检索由处理程序截获的错误条件、SQLSTATE和消息参数。

Python语言

对于 Python，请使用 pySparkException

PySparkException.getErrorClass()：以字符串形式返回异常的错误条件。
PySparkException.getMessageParameters()：以字典的形式返回异常的消息参数。
PySparkException.getSqlState()：以字符串的形式返回表达式的 SQLSTATE。

Scala(编程语言)

对于 Scala，请使用 SparkThrowable

getErrorClass()：以字符串的形式返回错误条件。
getMessageParameters()：以映射的形式返回消息参数。
getSqlState()：将 SQLSTATE 作为字符串返回。

示例

捕获任何异常并显示错误条件、消息参数和 SQLSTATE。还显示默认错误消息

SQL

BEGIN
  DECLARE EXIT HANDLER FOR SQLEXCEPTION
    BEGIN
      DECLARE error_condition STRING;
      DECLARE sqlstate STRING;
      DECLARE msg_args MAP<STRING, STRING>;
      DECLARE msg STRING;

      GET DIAGNOSTICS CONDITION 1
        error_condition = CONDITION_IDENTIFIER,
        sqlstate        = RETURNED_SQLSTATE,
        msg_args        = MESSAGE_ARGUMENTS,
        msg             = MESSAGE_TEXT;

      VALUES('Error Condition   : ' || error_condition         ),
            ('Message arguments : ' || cast(msg_args AS STRING)),
            ('SQLSTATE          : ' || sqlstate                ),
            (msg                                               );
    END;
  SELECT * FROM does_not_exist;
END;

Scala(编程语言)

import org.apache.spark.SparkThrowable

try {
  spark.sql("SELECT * FROM does_not_exist").show()
}
catch {
  case ex: SparkThrowable =>
    println("Error Condition   : " + ex.getErrorClass)
    println("Message arguments : " + 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 Condition   : " + ex.getErrorClass())
  print("Message arguments : " + str(ex.getMessageParameters()))
  print("SQLSTATE          : " + ex.getSqlState())
  print(ex)

结果

  Error Condition   : TABLE_OR_VIEW_NOT_FOUND
  Message arguments : {'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 并显示自定义消息：

SQL

BEGIN
  DECLARE EXIT HANDLER FOR SQLSTATE '42P01'
    BEGIN
      DECLARE msg_args MAP<STRING, STRING>;
      GET DIAGNOSTICS CONDITION 1 msg_args = MESSAGE_ARGUMENTS;
      VALUES('I\'m so sorry, but I cannot find: ' || msg_args['relationName']);
    END;
  SELECT * FROM does_not_exist;
END;

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 并显示自定义消息：

SQL

BEGIN
  DECLARE EXIT HANDLER FOR TABLE_OR_VIEW_NOT_FOUND
    BEGIN
      DECLARE msg_args MAP<STRING, STRING>;
      GET DIAGNOSTICS CONDITION 1 msg_args = MESSAGE_ARGUMENTS;
      VALUES('I\'m so sorry, but I cannot find: ' || msg_args['relationName']);
    END;
  SELECT * FROM does_not_exist;
END;

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”，还返回一个用户定义的消息。

示例

> 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

通过

Azure Databricks 中的错误处理

错误组件

处理错误条件

SQL

Python语言

Scala(编程语言)

示例

SQL

Scala(编程语言)

Python语言

SQL

Scala(编程语言)

Python语言

SQL

Scala(编程语言)

Python语言

用户引发的异常

示例

相关内容

反馈

其他资源