Tratamento de erros no Azure Databricks

2025-05-05

Aplica-se a: marca de verificação sim Databricks SQL Databricks Runtime 12.2 e superior

Componentes de erro

Quando o Azure Databricks gera um erro, ele inclui os seguintes componentes:

Condição de erro

Uma cadeia de caracteres descritiva, legível por humanos, exclusiva para a condição de erro.

Algumas condições de erro incluem subcondições.

Por exemplo: TABLE_OR_VIEW_NOT_FOUND e INCOMPLETE_TYPE_DEFINITION.ARRAY

Para obter uma lista de todas as condições de erro, consulte Condições de erro.
SQLSTATE

Uma cadeia de caracteres de cinco caracteres, agrupando condições de erro em um formato padrão suportado por muitos produtos e APIs.

Por exemplo: '42P01'

Para obter uma lista completa de todos os SQLSTATEs usados pelo Azure Databricks, consulte SQLSTATEs.
Mensagem parametrizada

A mensagem de erro com marcadores de posição para os parâmetros.

Por exemplo: TABLE_OR_VIEW_NOT_FOUND inclui a seguinte mensagem:
```
The table or view <relationName> cannot be found.
```
Você pode usar a mensagem parametrizada para renderizar uma mensagem de erro, mapeando os valores de parâmetro da mensagem para as tags de parâmetro <parameter>.
Parâmetros de mensagem

Um mapa de parâmetros e valores que fornecem informações adicionais sobre o erro. Por exemplo: 'relationName' -> 'main.default.tab1'.

Mensagem

A mensagem de erro completamente renderizada, incluindo a condição de erro e o SQLSTATE, com os parâmetros preenchidos. Por exemplo:

[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

Aviso

A mensagem e a mensagem parametrizada não são estáveis entre as versões. O texto da mensagem pode ser alterado ou adaptado sem aviso prévio. Para manipular programaticamente uma condição de erro, use a Condição de erroSQLSTATE e Parâmetros de mensagem.

Gestão de condições de erro

Aplica-se a: Confirmado Sim Databricks SQL Databricks Runtime 14.2 e superior

Importante

Esta funcionalidade está em Pré-visualização Pública.

O Azure Databricks fornece APIs específicas do idioma para lidar com condições de erro.

SQL

Aplica-se a: marcação marcada como sim Databricks SQL Databricks Runtime 16.3 e superior

Para SQL, use a sintaxe da instrução composta para definir manipuladores de condição.

DECLARE EXIT HANDLER: Define um manipulador para um conjunto de condições de erro especificadas, os SQLSTATEs, ou qualquer SQLEXCEPTION.
GET DIAGNÓSTICO: Recupera a condição de erro, SQLSTATEe os parâmetros de mensagem da condição de erro intercetada pelo manipulador.

Píton

Para Python use pySparkException

PySparkException.getErrorClass(): Retorna a condição de erro da exceção como uma cadeia de caracteres.
PySparkException.getMessageParameters(): Retorna os parâmetros de mensagem da exceção como um dicionário.
PySparkException.getSqlState(): Devolve o SQLSTATE da expressão como uma cadeia de caracteres.

linguagem de programação Scala

Para Scala, utilize SparkThrowable

getErrorClass(): Retorna uma condição de erro como uma cadeia de caracteres.
getMessageParameters(): Retorna parâmetros de uma mensagem como um mapa.
getSqlState(): Retorna um SQLSTATE como uma cadeia de caracteres.

Exemplos

Detecte qualquer erro e exiba a condição de erro, os parâmetros da mensagem e SQLSTATE. Exibir também a mensagem de erro padrão

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;

linguagem de programação 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)
}

Píton

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)

Resultado

  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

Capture somente o SQLSTATE 42P01 e exiba uma mensagem personalizada:

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;

linguagem de programação 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"))
}

Píton

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

Resultado

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

Detete apenas a condição TABLE_OR_VIEW_NOT_FOUND de erro e exiba uma mensagem personalizada:

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;

linguagem de programação 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"))
}

Píton

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

Resultado

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

Exceções levantadas pelo usuário

O Azure Databricks fornece as seguintes funções para gerar erros definidos pelo usuário:

raise_error

Gera uma exceção com uma mensagem de erro personalizada.
assert_true

Gera um erro com uma mensagem de erro opcional, se uma condição não for atendida.

Ambas as funções retornam a condição de erro 'USER_RAISED_EXCEPTION' juntamente com SQLSTATE'P0001' e uma mensagem definida pelo usuário.

Exemplos

> 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

Partilhar via

Tratamento de erros no Azure Databricks

Componentes de erro

Gestão de condições de erro

SQL

Píton

linguagem de programação Scala

Exemplos

SQL

linguagem de programação Scala

Píton

SQL

linguagem de programação Scala

Píton

SQL

linguagem de programação Scala

Píton

Exceções levantadas pelo usuário

Exemplos

Relacionado

Comentários

Recursos adicionais