Share via

SIGNAL statement

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 16.3 and above

Important

This feature is in Public Preview.

Raises a condition.

This statement may only be used within a compound statement.

Note: Databricks recommends using RESIGNAL to raise conditions from within a handler. RESIGNAL builds a diagnostic stack in the SQL Standard, while SIGNAL clears the stack. Using RESIGNAL within a handler preserves future exploitation of the diagnostic stack.

Syntax

SIGNAL { condition_name
         [ SET { MESSAGE_ARGUMENTS = argument_map |
                 MESSAGE_TEXT = message_str } ] |
         SQLSTATE [VALUE] sqlstate [ SET MESSAGE_TEXT = message_str ] }

Parameters

  • condition_name

    The name of a locally defined condition or system-defined error condition.

  • argument_map

    Optionally, a MAP<STRING, STRING> literal that assigns values to a system-defined parameterized condition message.

  • message_str

    Optionally, a STRING literal that provides a message string to the raised SQLSTATE or user-defined condition.

  • sqlstate

    A STRING literal of length 5. If specified, raise USER_RAISED_EXCEPTION with the specified SQLSTATE.

Examples

> DECLARE input INT DEFAULT 5;

> BEGIN
    DECLARE arg_map MAP<STRING, STRING>;
    IF input > 4 THEN
      SET arg_map = map('errorMessage',
                        'Input must be <= 4.');
      SIGNAL USER_RAISED_EXCEPTION
        SET MESSAGE_ARGUMENTS = arg_map;
    END IF;
  END;