Pular para o conteúdo principal

Tratamento de erros na Databricks

Aplica-se a: cheque marcado sim Databricks SQL cheque marcado sim 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: cheque marcado sim Databricks SQL cheque marcado sim 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: cheque marcado sim 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
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;

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

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

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