EXCEPTION (Script Snowflake)¶

Especifica como lidar com exceções geradas no bloco do Script Snowflake.

Para obter mais informações sobre exceções, consulte Tratamento de exceções.

Consulte também: RAISE

Sintaxe¶

EXCEPTION
    WHEN <exception_name> [ OR <exception_name> ... ] THEN
        <statement>;
        [ <statement>; ... ]
    [ WHEN ... ]
    [ WHEN OTHER THEN ]
        <statement>;
        [ <statement>; ... ]

Copy

Onde:

exception_name
Um nome de exceção definido na parte DECLARE do bloco atual ou em um bloco delimitador.

statement
Uma instrução pode ser qualquer uma das seguintes opções:

Uma única instrução SQL (incluindo CALL).

Uma instrução de fluxo de controle (ex.: instrução de looping ou ramificação).

Um bloco aninhado.

Notas de uso¶

Cada bloco pode ter seu próprio manipulador de exceção.
O Snowflake não oferece suporte a mais do que um manipulador de exceção por bloco. Entretanto, esse manipulador pode pegar mais de um tipo de exceção por ter mais de uma cláusula WHEN.
O manipulador de exceção deve estar no final do bloco. Se o bloco contiver instruções após o manipulador de exceção, essas instruções não serão executadas.
A cláusula WHEN OTHER THEN captura qualquer exceção ainda não especificada.
Se mais de uma cláusula WHEN pudesse corresponder a uma exceção específica, então a primeira cláusula WHEN que corresponder é a que é executada. As outras cláusulas não são executadas.
Um manipulador de exceção só pode lidar com uma exceção especificada se essa exceção especificada estiver no escopo.
Se um procedimento armazenado for destinado a retornar um valor, então ele deve retornar um valor de cada caminho possível, incluindo cada WHEN cláusula do manipulador de exceção.

Exemplos¶

Este exemplo declara, gera e trata de uma exceção. Note que:

O manipulador de exceção é projetado para lidar com mais de um tipo de exceção.

Uma das cláusulas WHEN do manipulador de exceção contém uma única instrução, enquanto a outra contém um bloco.

DECLARE
  RESULT VARCHAR;
  EXCEPTION_1 EXCEPTION (-20001, 'I caught the expected exception.');
  EXCEPTION_2 EXCEPTION (-20002, 'Not the expected exception!');
BEGIN
  RESULT := 'If you see this, I did not catch any exception.';
  IF (TRUE) THEN
    RAISE EXCEPTION_1;
  END IF;
  RETURN RESULT;
EXCEPTION
  WHEN EXCEPTION_2 THEN
    RETURN SQLERRM;
  WHEN EXCEPTION_1 THEN
    RETURN SQLERRM;
END;

Copy

Nota: se você estiver usando SnowSQL ou Classic Console, use este exemplo (consulte Como usar o Script Snowflake no SnowSQL e na Classic Console):

EXECUTE IMMEDIATE $$
    DECLARE
        RESULT VARCHAR;
        EXCEPTION_1 EXCEPTION (-20001, 'I caught the expected exception.');
        EXCEPTION_2 EXCEPTION (-20002, 'Not the expected exception!');
    BEGIN
        RESULT := 'If you see this, I did not catch any exception.';
        IF (TRUE) THEN
            RAISE EXCEPTION_1;
        END IF;
        RETURN RESULT;
    EXCEPTION
        WHEN EXCEPTION_2 THEN
            RETURN SQLERRM;
        WHEN EXCEPTION_1 THEN
            RETURN SQLERRM;
    END;
$$
;

Copy

Aqui está o resultado da execução do exemplo que gera a exceção. Isto mostra que o manipulador de exceção pegou a exceção.

+----------------------------------+
| anonymous block                  |
|----------------------------------|
| I caught the expected exception. |
+----------------------------------+

Copy

Este próximo exemplo é semelhante ao exemplo anterior, mas demonstra blocos aninhados, e mostra que um bloco interno pode gerar uma exceção declarada tanto no bloco interno quanto no externo.

DECLARE
  e1 EXCEPTION (-20001, 'Exception e1');

BEGIN
  -- Inner block.
  DECLARE
    e2 EXCEPTION (-20002, 'Exception e2');
    selector BOOLEAN DEFAULT TRUE;
  BEGIN
    IF (selector) THEN
      RAISE e1;
    ELSE
      RAISE e2;
    END IF;
  END;

EXCEPTION
  WHEN e1 THEN
    RETURN SQLERRM || ' caught in outer block.';
END;

Copy

Nota: se você estiver usando SnowSQL ou Classic Console, use este exemplo (consulte Como usar o Script Snowflake no SnowSQL e na Classic Console):

EXECUTE IMMEDIATE $$
    DECLARE
        e1 EXCEPTION (-20001, 'Exception e1');

    BEGIN
        -- Inner block.
        DECLARE
            e2 EXCEPTION (-20002, 'Exception e2');
            selector BOOLEAN DEFAULT TRUE;
        BEGIN
            IF (selector) THEN
                RAISE e1;
            ELSE
                RAISE e2;
            END IF;
        END;

    EXCEPTION
        WHEN e1 THEN
            BEGIN
                RETURN SQLERRM || ' caught in outer block.';
            END;

    END;
$$
;

Copy

Aqui está o resultado da execução do exemplo que gera a exceção. Isto mostra que o manipulador de exceção pegou a exceção.

+-------------------------------------+
| anonymous block                     |
|-------------------------------------|
| Exception e1 caught in outer block. |
+-------------------------------------+

Copy

Este próximo exemplo é semelhante ao exemplo anterior, mas demonstra blocos aninhados, cada um dos quais com seu próprio manipulador de exceção.

DECLARE
  RESULT VARCHAR;
  e1 EXCEPTION (-20001, 'Outer exception e1');

BEGIN
  RESULT := 'No error so far (but there will be).';

  DECLARE
    e1 EXCEPTION (-20101, 'Inner exception e1');
  BEGIN
    RAISE e1;
  EXCEPTION
    WHEN e1 THEN
      RESULT := 'Inner exception raised.';
      RETURN RESULT;
  END;

  RETURN RESULT;

EXCEPTION
  WHEN e1 THEN
    RESULT := 'Outer exception raised.';
    RETURN RESULT;

END;

Copy

Nota: se você estiver usando SnowSQL ou Classic Console, use este exemplo (consulte Como usar o Script Snowflake no SnowSQL e na Classic Console):

EXECUTE IMMEDIATE $$
    DECLARE
        RESULT VARCHAR;
        e1 EXCEPTION (-20001, 'Outer exception e1');

    BEGIN
        RESULT := 'No error so far (but there will be).';

        DECLARE
            e1 EXCEPTION (-20101, 'Inner exception e1');
        BEGIN
            RAISE e1;
        EXCEPTION
            WHEN e1 THEN
                RESULT := 'Inner exception raised.';
                RETURN RESULT;
        END;

        RETURN RESULT;

    EXCEPTION
        WHEN e1 THEN
            RESULT := 'Outer exception raised.';
            RETURN RESULT;

    END;
$$
;

Copy

Nota

Este exemplo usa o mesmo nome de exceção (e1) nos blocos externo e interno.

Isso não é recomendado.

O exemplo faz isso para ilustrar o escopo dos nomes de exceção. As duas exceções com o nome e1 são exceções diferentes.

O manipulador e1 no bloco externo não lida com a exceção e1 que é declarada e gerada no bloco interno.

Aqui está o resultado da execução do exemplo que gera a exceção. Isso mostra que o manipulador de exceção interno funcionou.

+-------------------------+
| anonymous block         |
|-------------------------|
| Inner exception raised. |
+-------------------------+

Copy

Este fragmento de exemplo mostra:

Como pegar mais de uma exceção na mesma cláusula usando OR.

Como pegar exceções não especificadas usando WHEN OTHER THEN.

EXCEPTION
  WHEN MY_FIRST_EXCEPTION OR MY_SECOND_EXCEPTION OR MY_THIRD_EXCEPTION THEN
    RETURN 123;
  WHEN MY_FOURTH_EXCEPTION THEN
    RETURN 4;
  WHEN OTHER THEN
    RETURN 99;

Copy

O exemplo seguinte mostra como retornar SQLCODE, SQLERRM (mensagem de erro SQL), e SQLSTATE ao capturar uma exceção:

DECLARE
  MY_EXCEPTION EXCEPTION (-20001, 'Sample message');
BEGIN
  RAISE MY_EXCEPTION;
EXCEPTION
  WHEN STATEMENT_ERROR THEN
    RETURN OBJECT_CONSTRUCT('Error type', 'STATEMENT_ERROR',
                            'SQLCODE', SQLCODE,
                            'SQLERRM', SQLERRM,
                            'SQLSTATE', SQLSTATE);
  WHEN EXPRESSION_ERROR THEN
    RETURN OBJECT_CONSTRUCT('Error type', 'EXPRESSION_ERROR',
                            'SQLCODE', SQLCODE,
                            'SQLERRM', SQLERRM,
                            'SQLSTATE', SQLSTATE);
  WHEN OTHER THEN
    RETURN OBJECT_CONSTRUCT('Error type', 'Other error',
                            'SQLCODE', SQLCODE,
                            'SQLERRM', SQLERRM,
                            'SQLSTATE', SQLSTATE);
END;

Copy

Nota: se você estiver usando SnowSQL ou Classic Console, use este exemplo (consulte Como usar o Script Snowflake no SnowSQL e na Classic Console):

EXECUTE IMMEDIATE $$
    DECLARE
        MY_EXCEPTION EXCEPTION (-20001, 'Sample message');
    BEGIN
        RAISE MY_EXCEPTION;
    EXCEPTION
        WHEN STATEMENT_ERROR THEN
            RETURN OBJECT_CONSTRUCT('Error type', 'STATEMENT_ERROR',
                                    'SQLCODE', SQLCODE,
                                    'SQLERRM', SQLERRM,
                                    'SQLSTATE', SQLSTATE);
        WHEN EXPRESSION_ERROR THEN
            RETURN OBJECT_CONSTRUCT('Error type', 'EXPRESSION_ERROR',
                                    'SQLCODE', SQLCODE,
                                    'SQLERRM', SQLERRM,
                                    'SQLSTATE', SQLSTATE);
        WHEN OTHER THEN
            RETURN OBJECT_CONSTRUCT('Error type', 'Other error',
                                    'SQLCODE', SQLCODE,
                                    'SQLERRM', SQLERRM,
                                    'SQLSTATE', SQLSTATE);
    END;
$$
;

Copy

A execução deste exemplo produz os seguintes resultados:

+--------------------------------+
| anonymous block                |
|--------------------------------|
| {                              |
|   "Error type": "Other error", |
|   "SQLCODE": -20001,           |
|   "SQLERRM": "Sample message", |
|   "SQLSTATE": "P0001"          |
| }                              |
+--------------------------------+

Copy

Este exemplo demonstra o retorno de um valor de cada caminho possível:

declare
    e1 exception;
    e2 exception;
begin
    statement_1;
    ...
    RETURN x;
exception
    when e1 then begin
        ...
        RETURN y;
        end;
    when e2 then begin
        ...
        RETURN z;
        end;
end;

Copy