Compartilhar via

Tratamento de erros no Azure Databricks

Aplica-se a:verificação marcada como sim Databricks SQL verificação marcada como sim Databricks Runtime 12.2 e superior.

Componentes do erro

Quando o Azure Databricks gera um erro, este 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 longa de cinco caracteres, agrupando condições de erro em um formato padrão compatível com 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 espaços reservados 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 dos parâmetros 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 traduzido sem aviso prévio. Para lidar programaticamente com uma condição de erro, use a Condição de Erro, SQLSTATE e os Parâmetros de Mensagem.

Como lidar com as condições de erro

Aplica-se a: marca de seleção Sim Databricks SQL verificação marcada como sim Databricks Runtime 14.2 e superior

Importante

Esse recurso está em Visualização Pública.

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

SQL

Aplica-se a: verificação marcada sim Databricks SQL verificação marcada sim Databricks Runtime 16.3 e superiores

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

  • DECLARE EXIT HANDLER: define um manipulador para um conjunto de condições de erro, SQLSTATEs ou qualquer SQLEXCEPTION.
  • GET DIAGNÓSTICO: recupera a condição SQLSTATEde erro e os parâmetros de mensagem da condição de erro interceptada pelo manipulador.

Python

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(): retorna o SQLSTATE da expressão como uma cadeia de caracteres.

Scala (linguagem de programação)

Para Scala, use SparkThrowable

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

Exemplos

  • Capturar qualquer exceção e exibir condição de erro, parâmetros de mensagem e SQLSTATE. Mostra 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;

    Scala (linguagem de programação)

    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)

    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

  • Captura apenas o SQLSTATE 42P01 e mostra 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;

    Scala (linguagem de programação)

    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

    Resultado

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

  • Capture 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;

    Scala (linguagem de programação)

    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

    Resultado

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

Exceções geradas 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' e a SQLSTATE'P0001' 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
  • Last updated on