Partage via

Instruction composée BEGIN END

S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 16.3 et versions ultérieures

Implémente un bloc de script SQL qui peut contenir une séquence d’instructions SQL, d’instructions de contrôle de flux, de déclarations de variables locales et de gestionnaires d’exceptions. Lorsqu’elles sont marquées comme ATOMIC, le bloc s’exécute en tant qu’unité transactionnelle où toutes les instructions réussissent ensemble ou échouent ensemble.

Remarque

Lors de l’appel d’une instruction composée à partir d’un notebook, il doit s’agir de la seule instruction dans la cellule.

Syntaxe

[ label : ]
      BEGIN [ ATOMIC ]
      [ { declare_variable | declare_condition } ; [...] ]
      [ declare_cursor ; [...] ]
      [ declare_handler ; [...] ]
      [ SQL_statement ; [...] ]
      END [ label ]

declare_variable
  DECLARE variable_name [, ...] datatype [ DEFAULT default_expr ]

declare_condition
  DECLARE condition_name CONDITION [ FOR SQLSTATE [ VALUE ] sqlstate ]

declare_cursor
  DECLARE cursor_name [ ASENSITIVE | INSENSITIVE ] CURSOR FOR query [ FOR READ ONLY ]

declare_handler
  DECLARE handler_type HANDLER FOR condition_values handler_action

handler_type
  EXIT | CONTINUE

condition_values
 { { SQLSTATE [ VALUE ] sqlstate | condition_name } [, ...] |
   { SQLEXCEPTION | NOT FOUND } [, ...] }

Avant Databricks Runtime 17.2, vous ne pouvez déclarer qu’une seule variable à la fois.

Paramètres

  • étiquette

    Un identificateur facultatif est utilisé pour qualifier les variables définies dans le composé et pour quitter le composé. Les deux occurrences d’étiquette doivent correspondre et l’étiquette END ne peut être spécifiée que si label: elle est spécifiée.

    l’étiquette ne doit pas être spécifiée pour une instruction composée de niveau supérieur ou pour une ATOMIC instruction composée.

  • ATOMIC

    S’applique à :coche oui Databricks SQL coche oui Databricks Runtime 17.0 et versions ultérieures

    Important

    Les instructions composées ATOMIC sont en préversion publique.

    Marque l’instruction composée comme bloc de transaction atomique. Toutes les instructions du bloc s’exécutent sous la forme d’une seule unité transactionnelle : toutes les instructions réussissent ensemble ou toutes les modifications sont restaurées si une instruction échoue. Azure Databricks valide automatiquement les modifications lorsque le bloc se termine correctement, ou restaure toutes les modifications en cas d’échec d’une instruction.

    Les blocs atomiques fournissent la même isolation, visibilité, gestion des erreurs et limite la sémantique que les transactions interactives explicites. Toutefois, les blocs atomiques offrent une syntaxe plus simple avec le comportement de validation et de restauration automatique.

    La saisie d’un BEGIN ATOMIC ... END bloc commence implicitement une transaction. La saisie semi-automatique valide implicitement la transaction. Les erreurs entraînent l’abandon et la restauration automatique de la transaction.

    Remarque

    Les transactions multi-tables nécessitent des validations Databricks Runtime 18.0 et ultérieures et gérées par le catalogue activées sur toutes les tables. Les transactions atomiques à table unique fonctionnent dans Databricks Runtime 17.0 et versions ultérieures sans exigences supplémentaires.

    Les restrictions suivantes s’appliquent aux instructions composées atomiques :

    • BEGIN ATOMIC ... END les blocs peuvent être appelés dans d’autres blocs atomiques. Le bloc interne est aplatit dans la transaction externe : toutes les instructions s’exécutent dans le cadre d’une transaction plus grande. Il ne s’agit pas d’une transaction imbriquée. Un bloc atomique ne peut pas contenir de bloc non atomique BEGIN ... END .
    • Les blocs atomiques ne peuvent pas être imbriqués dans des blocs non atomiques BEGIN ... END .
    • Les gestionnaires d’exceptions (DECLARE ... HANDLER) ne sont pas autorisés dans les blocs atomiques.
    • Les blocs atomiques ne peuvent pas être définis dans les gestionnaires d’exceptions.
    • Seules les opérations DML (INSERT, , UPDATE, DELETEMERGE), SELECT les instructions, les déclarations et les affectations de variables, les instructions de flux de contrôle (IFet SIGNALsimilaires) et les appels aux procédures stockées atomiques sont autorisés dans des blocs atomiques. Les instructions DDL et d’autres opérations ne sont pas prises en charge.
    • Le paramètre des variables locales ou de session n’est pas transactionnel. Autrement dit, les affectations de variables ne sont pas soumises à une restauration en cas d’échec de transaction.

    Consultez les transactions non interactives.

  • NOT ATOMIC

    Spécifie que, si une instruction SQL dans le composé échoue, les instructions SQL précédentes ne seront pas restaurées. Il s’agit du comportement par défaut lorsqu’il ATOMIC n’est pas spécifié.

  • declare_variable

    Déclaration de variable locale pour une ou plusieurs variables

    • variable_name

      Un nom de la variable. Le nom ne doit pas être qualifié et doit être unique dans la déclaration composée.

    • data_type

      Tout type de données pris en charge. Si data_type est omis, vous devez spécifier DEFAULT et le type est dérivé du default_expression.

    • { DEFAULT | = } default_expression

      Définit la valeur initiale de la variable après la déclaration. default_expression doit pouvoir être converti en data_type. Si aucune valeur par défaut n’est spécifiée, la variable est initialisée avec NULL.

  • Declare_condition

    Déclaration de condition locale

    • condition_name

      Le nom non qualifié de la condition est limité à l’instruction composée.

    • sqlstate

      Littéral STRING de 5 caractères alphanumériques (insensibles à la casse) composés de lettres de A à Z et de chiffres de 0 à 9. SQLSTATE ne doit pas commencer par « 00 », « 01 » ou « XX ». Tout SQLSTATE commençant par « 02 » est également intercepté par l’exception NOT FOUND prédéfinie. S’il n’est pas spécifié, SQLSTATE est « 45000 ».

  • declare_cursor

    S’applique à :check marqué oui Databricks Runtime 18.1 et versions ultérieures

    Déclaration de curseur local pour effectuer une itération dans les résultats de la requête.

    Remarque

    Pour DECLARE CURSOR, seules les erreurs de syntaxe sont détectées et déclenchées. La requête n’est pas exécutée tant que le curseur n’est pas ouvert avec OPEN.

    • cursor_name : nom non qualifié du curseur, unique parmi les curseurs de cette instruction composée. Lorsque vous référencez le curseur dans OPEN, FETCH ou CLOSE, vous pouvez qualifier le nom du curseur avec l’étiquette d’instruction composée (par exemple label.my_cursor) pour lever l’ambiguïté dans les étendues imbriquées.
    • ASENSITIVE | INSENSITIVE: facultatif. Une fois le curseur ouvert, le jeu de résultats n’est pas affecté par les modifications DML. Il s’agit du comportement par défaut et uniquement pris en charge.
    • requête : requête qui définit le curseur ; elle est exécutée lorsque le curseur est ouvert avec OPEN.

  • declare_handler

    Déclaration d’un gestionnaire d’erreurs.

    • handler_type

      • EXIT

        Classifie le gestionnaire pour quitter l’instruction composée une fois la condition gérée. Tous les curseurs ouverts dans l’instruction composée et les instructions composées imbriquées sont implicitement fermés.

      • CONTINUE

        S’applique à :check marqué oui Databricks Runtime 18.1 et versions ultérieures

        Classifie le gestionnaire pour poursuivre l’exécution une fois le gestionnaire terminé. L’exécution reprend avec l’instruction qui suit celle qui a déclenché la condition.

    • condition_values

      Spécifie à quels sqlstates ou conditions le gestionnaire s’applique. Les valeurs de condition doivent être uniques dans tous les gestionnaires de l’instruction composée. Les valeurs de condition spécifiques sont prioritaires sur SQLEXCEPTION.

    • sqlstate

      Littéral STRING de 5 caractères 'A'-'Z' et '0'-'9' (insensible à la casse).

    • condition_name

      Condition définie dans ce composé, une instruction composée externe ou une classe d’erreur définie par le système.

    • SQLEXCEPTION

      S’applique à n’importe quelle condition d’erreur orientée utilisateur.

    • NOT FOUND

      S’applique à toute condition d’erreur avec une classe SQLSTATE '02', y compris la condition CURSOR_NO_MORE_ROWS (SQLSTATE '02000') levée lors de l’extraction au-delà de la fin d’un jeu de résultats de curseur.

    • handler_action

      Instruction SQL à exécuter quand l’une des valeurs de condition se produit. Pour ajouter plusieurs instructions, utilisez une instruction composée imbriquée.

  • SQL_statement

    Instruction SQL telle qu’une instruction DDL, DML, de contrôle ou instruction composée. Tout SELECT ou VALUES instruction produit un jeu de résultats que l’appelant peut consommer.

Exemples

Instruction composée non atomique avec gestionnaire d’exceptions

-- A compound statement with local variables, exit handler, and nested compound
> BEGIN
    DECLARE a INT DEFAULT 1;
    DECLARE b INT DEFAULT 5;
    DECLARE EXIT HANDLER FOR DIVIDE_BY_ZERO
      div0: BEGIN
        VALUES (15);
      END div0;
    SET a = 10;
    SET a = b / 0;
    VALUES (a);
END;
15

Instruction composée atomique

-- An atomic compound statement that ensures all changes commit together
> BEGIN ATOMIC
    INSERT INTO accounts VALUES (1, 'Alice', 1000);
    INSERT INTO accounts VALUES (2, 'Bob', 2000);
    UPDATE accounts SET balance = balance + 100 WHERE id = 1;
END;

Instruction composée atomique avec restauration automatique

-- If any statement fails, all changes are rolled back automatically
> BEGIN ATOMIC
    INSERT INTO orders VALUES (101, 'Product A', 50.00);
    UPDATE inventory SET quantity = quantity - 1 WHERE product = 'Product A';
    -- If this statement fails, both the INSERT and UPDATE are rolled back
    INSERT INTO audit_log VALUES (101, current_timestamp(), 1/0);
END;
-- Error: Division by zero
-- All changes rolled back automatically

Instruction composée atomique avec des variables

-- Variables can be used within atomic blocks
> BEGIN ATOMIC
    DECLARE total_amount DECIMAL(10, 2);

    INSERT INTO sales VALUES (301, 150.00, current_date());

    SET total_amount = (SELECT SUM(amount) FROM sales WHERE sale_date = current_date());

    UPDATE daily_summary SET total = total_amount WHERE summary_date = current_date();
END;
  • Last updated on