Azure Databricks でのエラー処理

2025-05-01

適用対象: Databricks SQL Databricks Runtime 12.2 以上

エラーコンポーネント

Azure Databricks でエラーが発生する場合は、次のコンポーネントが含まれています。

エラー条件

わかりやすく、人間が判読でき、エラー条件に一意の文字列。

一部のエラー条件には、サブ条件が含まれます。

例: TABLE_OR_VIEW_NOT_FOUND、 INCOMPLETE_TYPE_DEFINITION。ARRAY。

すべてのエラー条件の一覧については、「エラー条件」を参照してください。
SQLSTATE

5 文字の長い文字列。多くの製品と 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、 およびメッセージパラメーター を使用します。

エラー条件の処理

適用対象: check marked yes Databricks SQL 「はい」のチェックマーク Databricks Runtime 14.2 以上

重要

この機能はパブリックプレビュー段階にあります。

Azure Databricks では、エラー条件を処理するための言語固有の API が提供されます。

SQL

適用対象: Databricks SQL Databricks Runtime 16.3 以降

SQL の場合は、複合ステートメント構文を使用して条件ハンドラーを定義します。

DECLARE EXIT HANDLER: 指定された一連のエラー条件、 SQLSTATE、または任意の SQLEXCEPTIONのハンドラーを定義します。
GET DIAGNOSTICS: ハンドラーによってインターセプトされたエラー条件のエラー条件、 SQLSTATE、およびメッセージパラメーターを取得します。

Python（プログラミング言語）

Python では、pySparkException を使用します

PySparkException.getErrorClass(): 例外のエラー条件を文字列として返します。
PySparkException.getMessageParameters(): 例外のメッセージパラメーターを辞書として返します。
PySparkException.getSqlState(): 式の SQLSTATE を文字列として返します。

スカラ (プログラミング言語)

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;

スカラ (プログラミング言語)

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;

スカラ (プログラミング言語)

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;

スカラ (プログラミング言語)

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

次の方法で共有

Azure Databricks でのエラー処理

エラー コンポーネント

エラー条件の処理

SQL

Python（プログラミング言語）

スカラ (プログラミング言語)

例

SQL

スカラ (プログラミング言語)

Python（プログラミング言語）

SQL

スカラ (プログラミング言語)

Python（プログラミング言語）

SQL

スカラ (プログラミング言語)

Python（プログラミング言語）

ユーザーが発生させた例外

例

関連項目

フィードバック

その他のリソース

エラーコンポーネント