Tratamento de erros na Databricks

Aplica-se a: Databricks SQL Databricks Runtime 12.2e acima

Componentes de erro

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

• Condição de erro

  Uma cadeia de caracteres descritiva, legível por humanos, exclusiva da 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 longa de cinco caracteres que agrupa as 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 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âmetros <parameter>.

• Parâmetros da 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 totalmente 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

atenção

A mensagem e a mensagem parametrizada não são estáveis em todas as versões. O texto da mensagem pode ser alterado ou localizado 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 .

Tratamento de condições de erro

Aplica-se a: Databricks SQL Databricks Runtime 14.2 e acima

info

Visualização

Esse recurso está em Public Preview.

A Databricks fornece APIs específicas de linguagem para lidar com condições de erro.

SQL

Aplica-se a: Databricks SQL Databricks Runtime 16.3 e acima

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 especificadas, SQLSTATEs ou qualquer SQLEXCEPTION.
• GET DIAGNOSTICS : recupera a condição de erro, SQLSTATE, 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 da mensagem da exceção como um dicionário.
• PySparkException.getSqlState() : Retorna o endereço SQLSTATE da expressão como uma cadeia de caracteres.

Scala

Para Scala, use SparkThrowable

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

Exemplos

• Capture qualquer exceção e exiba a condição de erro, os parâmetros da mensagem e SQLSTATE. Exibir também a mensagem de erro default

  aba :::tab-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;

  :::

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

  :::

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

  ::: ::::

  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

• Pegue somente o SQLSTATE 42P01 e exiba uma mensagem personalizada:

  aba :::tab-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;

  :::

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

  :::

  Tab-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

  ::: ::::

  Resultado

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

• Identifique somente a condição de erro TABLE_OR_VIEW_NOT_FOUND e exiba uma mensagem personalizada:

  aba :::tab-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;

  :::

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

  :::

  Tab-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

  ::: ::::

  Resultado

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

Exceções levantadas pelo usuário

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

• aumentar_erro

  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 o SQLSTATE 'P0001' junto com 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

Relacionado

• assert_true função
• raise_error função
• Declaração composta BEGIN END
• Declaração GET DIAGNOSTICS