Databricks でのエラー処理

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

エラーコンポーネント

Databricks でエラーが発生すると、次のコンポーネントが含まれます。

• エラー状態

  エラー条件に固有の、説明的で人間が読める文字列。

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

  たとえば、 TABLE_OR_VIEW_NOT_FOUND、 INCOMPLETE_TYPE_DEFINITIONなどです。配列。

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

• SQLSTATE の

  エラー状態を多くの製品や APIsでサポートされている標準形式にグループ化した 5 文字の文字列。

  例えば： '42P01'

  Databricks で使用されるすべての SQLSTATEの完全な一覧については、「 SQLSTATE」を参照してください。

• パラメータ化されたメッセージ

  パラメーターのプレースホルダーを含むエラー メッセージ。

  たとえば、 TABLE_OR_VIEW_NOT_FOUND には次のメッセージが含まれます。

  The table or view <relationName> cannot be found.

  パラメーター化されたメッセージを使用して、メッセージ・パラメーター値をパラメーター・タグ <parameter>にマッピングすることにより、エラー・メッセージをレンダリングできます。

• Message パラメーター

  エラーに関する追加情報を提供するパラメーターと値のマップ。たとえば、 '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 以降

備考

プレビュー

この機能は パブリック プレビュー段階です。

Databricks では、エラー状態を処理するための言語固有の APIs を提供します。

SQL

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

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

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

Python

Python の場合は pySparkException を使用します

• PySparkException.getErrorClass() : 例外のエラー状態を文字列として返します。
• PySparkException.getMessageParameters() : 例外の message パラメーターをディクショナリとして返します。
• PySparkException.getSqlState() : 式のSQLSTATEを文字列として返します。

Scala

Scala の場合は、SparkThrowable を使用します

• getErrorClass() : エラー条件を文字列として返します。
• getMessageParameters() : メッセージ パラメーターをマップとして返します。
• getSqlState() : SQLSTATEを文字列として返します。

例

• 例外をキャッチし、エラー条件、メッセージパラメーター、および SQLSTATEを表示します。 また、デフォルトのエラーメッセージを表示します

  タブ :::タブ-item[SQL]

  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;

  :::

  タブ-item[Scala]

  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)
  }

  :::

  タブ-item[Python]

  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 のみをキャッチし、カスタム・メッセージを表示します。

  タブ :::タブ-item[SQL]

  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;

  :::

  タブ-item[Scala]

  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"))
  }

  :::

  タブ-item[Python]

  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 のみをキャッチし、カスタムメッセージを表示します。

  タブ :::タブ-item[SQL]

  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;

  :::

  タブ-item[Scala]

  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"))
  }

  :::

  タブ-item[Python]

  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`

ユーザーから発生した例外

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

関連

• assert_true 関数
• raise_error 関数
• BEGIN END 複合文
• GET DIAGNOSTICS 文