Catégories :

DDL de pipeline de données

CREATE TASK

Crée une nouvelle tâche dans le schéma actuel/spécifié ou remplace une tâche existante.

Cette commande prend également en charge la variante suivante :

  • CREATE TASK … CLONE (crée un clone d’une tâche existante)

Voir aussi :

ALTER TASK , DROP TASK , SHOW TASKS

Dans ce chapitre :

Syntaxe

CREATE [ OR REPLACE ] TASK [ IF NOT EXISTS ] <name>
  WAREHOUSE = <string>
  [ SCHEDULE = '{ <num> MINUTE | USING CRON <expr> <time_zone> }' ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ AFTER <string> ]
[ WHEN <boolean_expr> ]
AS
  <sql>

Syntaxe des variantes

CREATE TASK … CLONE

Crée une nouvelle tâche avec les mêmes valeurs de paramètre :

CREATE [ OR REPLACE ] TASK <name> CLONE <source_task>
  [ COPY GRANTS ]
  [ ... ]

Pour plus de détails, voir CREATE <objet> … CLONE.

Paramètres requis

nom

Chaîne qui indique l’identificateur (c’est-à-dire le nom) de la tâche ; doit être unique pour le schéma dans lequel la tâche est créée.

De plus, l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (p. ex. "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus de détails, voir Exigences relatives à l’identificateur.

WAREHOUSE = chaîne

Spécifie l’entrepôt virtuel utilisé pour exécuter la tâche.

sql

Une seule instruction SQL , ou un appel à une procédure stockée, exécutée lors de l’exécution de la tâche.

Note

L’instruction SQL ou la procédure stockée doit être exécutable seule. Nous vous recommandons vivement de vérifier que le sql s’exécute comme prévu avant de créer la tâche. Les tâches sont destinées à automatiser les instructions SQL et les procédures stockées qui ont déjà été testées de manière approfondie.

Paramètres facultatifs

SCHEDULE ... Spécifie la planification pour l’exécution périodique de la tâche :

Note

Une planification ne peut pas être spécifiée pour les tâches enfants dans une simple arborescence de tâches (c’est-à-dire les tâches qui ont un ensemble de tâches prédécesseur utilisant le paramètre AFTER).

  • USING CRON expr fuseau_horaire

    Spécifie une expression cron et un fuseau horaire pour l’exécution périodique de la tâche. Prend en charge un sous-ensemble de la syntaxe standard de l’utilitaire cron.

    Pour obtenir une liste des fuseaux horaires, voir la liste des fuseaux horaires de la base de données tz (dans Wikipedia).

    L’expression cron comprend les champs suivants :

    # __________ minute (0-59)
    # | ________ hour (0-23)
    # | | ______ day of month (1-31, or L)
    # | | | ____ month (1-12, JAN-DEC)
    # | | | | _ day of week (0-6, SUN-SAT, or L)
    # | | | | |
    # | | | | |
      * * * * *
    

    Les caractères spéciaux suivants sont acceptés :

    *

    Caractère générique. Spécifie toute occurrence du champ.

    L

    Signifie « dernier ». Lorsqu’il est utilisé dans le champ du jour de la semaine, il vous permet de spécifier des constructions telles que « le dernier vendredi » (« 5L ») d’un mois donné. Dans le champ du mois, il spécifie le dernier jour du mois.

    /n

    Indique l’instance n d’une unité de temps donnée. Par exemple, si 4/3 est spécifié dans le champ du mois, la tâche est planifiée pour avril, juillet et octobre (c’est-à-dire tous les 3 mois, à partir du 4e mois de l’année).

    Note

    • L’expression cron est actuellement évaluée par rapport au fuseau horaire spécifié. La modification de la valeur du paramètre TIMEZONE pour le compte (ou la définition de la valeur au niveau de l’utilisateur ou de la session) ne modifie pas le fuseau horaire de la tâche.

    • L’expression cron définit toutes les heures d’exécution valides de la tâche. Snowflake tente d’exécuter une tâche en fonction de ce calendrier. Toutefois, toute heure d’exécution valide est ignorée si une exécution précédente n’a pas été terminée avant le début de la prochaine heure d’exécution valide.

    • Lorsqu’un jour de mois et un jour de semaine spécifiques sont inclus dans l’expression cron, la tâche est planifiée les jours satisfaisant le jour du mois ou le jour de la semaine. Par exemple, SCHEDULE = 'USING CRON 0 0 10-20 * TUE,THU UTC' planifie une tâche à 0AM entre le 10e et le 20e jour du mois ainsi que le mardi ou le jeudi en dehors de ces dates.

  • nb MINUTE

    Spécifie un intervalle (en minutes) de temps d’attente inséré entre les exécutions de la tâche. Accepte uniquement les entiers positifs.

    Prend également en charge la syntaxe nb M.

    Pour éviter toute ambiguïté, un intervalle de base est défini lorsque :

    L’intervalle de base démarre le compteur d’intervalle à partir de l’heure actuelle. Par exemple, si une valeur INTERVAL de 10 est définie et que la tâche est activée à 9:03 AM, elle s’exécute à 9:13 AM, 9:23 AM, etc. Notez que nous faisons de notre mieux pour assurer une précision absolue, mais nous garantissons uniquement que les tâches ne s’exécutent pas avant que leur intervalle défini ne soit exécuté (par exemple, dans cet exemple, la tâche pourrait d’abord être exécutée à 9:14 AM, mais ne fonctionnera certainement pas à 9:12 AM).

paramètre_session = valeur [ , paramètre_session = valeur ... ]

Spécifie une liste de paramètres de session séparés par des virgules à définir pour la session lorsque la tâche est exécutée. Une tâche prend en charge tous les paramètres de session. Pour obtenir la liste complète, voir Paramètres de session.

USER_TASK_TIMEOUT_MS = nb

Spécifie la limite de temps sur une seule exécution de la tâche avant son expiration (en millisecondes).

Note

Avant d’augmenter considérablement le délai d’une tâche, déterminez si l’instruction SQL initiée par la tâche peut être optimisée (soit en réécrivant l’instruction ou en utilisant une procédure stockée) ou si la taille de l’entrepôt doit être augmentée.

Valeurs : 0 - 86400000 (1 jour).

Par défaut : 3600000 (1 heure)

COPY GRANTS

Spécifie de conserver les droits d’accès de la tâche d’origine lorsqu’une nouvelle tâche est créée à l’aide de l’une des variantes CREATE TASK suivantes :

  • CREATE OR REPLACE TASK

  • CREATE TASK … CLONE

Ce paramètre copie toutes les autorisations, excepté OWNERSHIP, de la tâche existante vers la nouvelle tâche. Par défaut, le rôle qui exécute la commande CREATE TASK possède la nouvelle tâche.

Remarque :

  • Si l’instruction CREATE TASK fait référence à plusieurs tâches (p. ex. create or replace task t1 clone t2;), la clause COPY GRANTS donne priorité à la tâche à remplacer.

  • La sortie SHOW GRANTS pour la tâche de remplacement liste le concessionnaire des privilèges copiés comme le rôle qui a exécuté l’instruction CREATE TASK, avec l’horodatage courant lorsque l’instruction a été exécutée.

  • L’opération de copie des accords s’effectue atomiquement dans la commande CREATE TASK (c’est-à-dire dans la même transaction).

Note

Ce paramètre n’est pas pris en charge actuellement.

COMMENT = 'litéral_chaine'

Spécifie un commentaire pour la tâche.

Par défaut : aucune valeur

AFTER chaîne

Spécifie le prédécesseur pour la tâche actuelle. Lorsqu’une exécution du prédécesseur se termine avec succès, il déclenche cette tâche (après un bref décalage).

Ce paramètre permet de définir une simple arborescence de tâches, c’est-à-dire un ensemble de tâches organisées par leurs dépendances. Dans ce contexte, une arborescence est une série de tâches qui commencent par une tâche racine planifiée et sont liées entre elles par leurs dépendances.

Note

  • La tâche racine dans l’arborescence devrait avoir une planification définie ; chacune des autres tâches de l’arborescence a un prédécesseur défini (c’est-à-dire une tâche spécifiée à l’aide du paramètre AFTER) pour les relier ensemble.

  • Une tâche est limitée à un seul prédécesseur ; cependant, une tâche peut avoir un maximum de 100 tâches enfants (c’est-à-dire d’autres tâches qui identifient la tâche en tant que prédécesseur) ; en outre, une simple arborescence de tâches est limitée à un maximum de 1 000 tâches au total (y compris la tâche racine) soit dans l’état de reprise (c’est-à-dire dans un état “Démarré”) soit dans l’état de suspension.

    Par exemple, la tâche T2 est limitée à un seul prédécesseur, par exemple T1 ; cependant, T1 peut servir de prédécesseur pour les tâches T2, T3, T4, etc.

  • Toutes les tâches d’une arborescence simple doivent avoir le même propriétaire (c’est-à-dire qu’un seul rôle doit disposer du privilège OWNERSHIP sur toutes les tâches de l’arborescence).

  • Toutes les tâches d’une arborescence simple doivent exister dans le même schéma.

  • La tâche racine dans une arborescence de tâches doit être suspendue avant que toute tâche dans l’arborescence soit recréée (à l’aide de la syntaxe CREATE OR REPLACE TASK) ou qu’une tâche enfant soit ajoutée (à l’aide de CREATE TASK … AFTER ).

  • Si une tâche dans une arborescence est clonée, le rôle qui la clone devient le propriétaire du clone par défaut.

    • Si le propriétaire de la tâche d’origine crée le clone, la tâche clone conserve le lien entre la tâche et le prédécesseur. Cela signifie que le même prédécesseur déclenche à la fois la tâche d’origine et la tâche clone.

    • Si un autre rôle crée le clone, le clone de tâche peut avoir une planification mais pas un prédécesseur.

  • Les comptes sont actuellement limités à un maximum de 10 000 tâches reprises.

  • Limites actuelles :

    • Snowflake garantit qu’au plus une instance d’une tâche avec un calendrier défini est exécutée à un moment donné ; cependant, nous ne pouvons pas fournir la même garantie pour les tâches avec un prédécesseur défini.

WHEN expr_booléenne

Spécifie une expression SQL booléenne ; plusieurs conditions associées à AND/OR sont prises en charge. Lorsqu’une tâche est déclenchée (en fonction de son paramètre SCHEDULE ou AFTER), elle valide les conditions de l’expression pour déterminer si elle doit être exécutée. Si les conditions de l’expression ne sont pas remplies, la tâche ignore l’exécution en cours. Aucune tâche identifiant cette tâche en tant que prédécesseur ne s’exécute pas non plus.

Actuellement, seule la fonction suivante est prise en charge pour l’évaluation dans l’expression SQL :

SYSTEM$STREAM_HAS_DATA

Indique si un flux spécifié contient des données de suivi des modifications. Utilisé pour ignorer l’exécution de la tâche en cours si le flux ne contient aucune donnée de modification.

Si le résultat est FALSE, la tâche ne s’exécute pas.

La validation des conditions de l’expression WHEN ne nécessite pas d’entrepôt virtuel mais utilise une petite quantité de traitement dans la couche de services Cloud. Une charge nominale s’accumule chaque fois qu’une tâche évalue sa condition WHEN et ne s’exécute pas. Les charges s’accumulent chaque fois que la tâche est déclenchée jusqu’à son exécution ; à ce moment, la charge est convertie en crédits Snowflake et ajoutée à l’utilisation des ressources de calcul pour l’exécution de la tâche.

Notes sur l’utilisation

  • L’exécution de cette commande nécessite les privilèges suivants :

    • CREATE TASK sur le schéma.

    • USAGE sur l’entrepôt dans la définition de la tâche.

    Le propriétaire de la tâche (c’est-à-dire le rôle avec le privilège OWNERSHIP sur la tâche) doit aussi avoir le privilège global EXECUTE TASK pour que les tâches s’exécutent. La révocation du privilège EXECUTE TASK sur un rôle empêche toutes les tâches suivantes de démarrer sous ce rôle.

    Nous vous recommandons d’exécuter une instruction SQL ou d’appeler une procédure stockée avant de l’inclure dans une définition de tâche. Effectuez cette étape en tant que rôle de propriétaire de tâche pour vous assurer que le rôle possède tous les privilèges requis sur tous les objets référencés par SQL.

  • Après avoir créé une tâche, vous devez exécuter ALTER TASK … RESUME avant que la tâche ne soit exécutée en fonction des paramètres spécifiés dans la définition de la tâche. Notez que les comptes sont actuellement limités à un maximum de 10 000 tâches reprises.

    De plus, lorsqu’une tâche est clonée, son exécution est suspendue par défaut et doit être activée explicitement à l’aide de la même commande.

  • Les tâches s’exécutent à l’aide du rôle disposant du privilège OWNERSHIP sur la tâche. Les instructions SQL exécutées par la tâche ne peuvent fonctionner que sur des objets Snowflake sur lesquels le rôle dispose des privilèges requis.

  • Par défaut, une instruction DML exécutée sans démarrer explicitement une transaction est automatiquement validée en cas de succès ou annulée en cas d’échec à la fin de l’instruction. Ce comportement s’appelle validation automatique, et il est contrôlé avec le paramètre AUTOCOMMIT. Ce paramètre doit être défini sur TRUE. Si le paramètre AUTOCOMMIT est défini sur FALSE au niveau du compte, définissez-le sur TRUE pour la tâche individuelle (avec ALTER TASK … SET AUTOCOMMIT = TRUE) ; sinon, toute instruction DML exécutée par la tâche échoue.

  • Plusieurs tâches qui consomment des données de modification à partir d’un flux de table unique récupèrent différents deltas. Lorsqu’une tâche consomme les données de modification dans un flux à l’aide d’une instruction DML, le flux avance le décalage. Les données de modification ne sont plus disponibles pour la prochaine tâche à consommer. Actuellement, nous recommandons qu’une seule tâche consomme les données de modification d’un flux. Plusieurs flux peuvent être créés pour la même table et consommés par différentes tâches.

  • Lorsque la syntaxe CREATE OR REPLACE est utilisée, la tâche existante est détruite et recréée à l’aide de la définition spécifiée. Toute exécution en cours de la tâche (c’est-à-dire une exécution avec un état EXECUTING dans la sortie TASK_HISTORY) est terminée. Pour interrompre l’exécution de la tâche spécifiée, exécutez la fonction SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS.

Exemples

Créer une tâche qui insère l’horodatage actuel dans une table toutes les heures, en commençant par 9 AM et en se terminant par 5 PM le dimanche (fuseau horaire Amérique/Los Angeles). La tâche définit le paramètre TIMESTAMP_INPUT_FORMAT pour la session dans laquelle la tâche est exécutée :

CREATE TASK mytask_hour
  WAREHOUSE = mywh
  SCHEDULE = 'USING CRON 0 9-17 * * SUN America/Los_Angeles'
  TIMESTAMP_INPUT_FORMAT = 'YYYY-MM-DD HH24'
AS
INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

Exemples de chronométrage supplémentaires :

Valeur SCHEDULE

Description

* * * * * UTC

Chaque minute. Fuseau horaire UTC.

0 2 * * * UTC

Tous les soirs à 2 AM. Fuseau horaire UTC.

0 5,17 * * * UTC

Deux fois par jour, à 5 AM et à 5 PM (pile). Fuseau horaire UTC.

30 2 L 6 * UTC

En juin, le dernier jour du mois, à 2:30 AM. Fuseau horaire UTC.

Créer une tâche qui insère l’horodatage actuel dans une table toutes les 5 minutes :

CREATE TASK mytask_minute
  WAREHOUSE = mywh
  SCHEDULE = '5 MINUTE'
AS
INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

Créer une tâche qui insère les données de suivi des modifications pour les opérations INSERT d’un flux dans une table toutes les 5 minutes. La tâche interroge le flux à l’aide de la fonction SYSTEM$STREAM_HAS_DATA pour déterminer s’il existe des données de modification et, si le résultat est FALSE, ignore l’exécution en cours :

CREATE TASK mytask1
  WAREHOUSE = mywh
  SCHEDULE = '5 minute'
WHEN
  SYSTEM$STREAM_HAS_DATA('MYSTREAM')
AS
  INSERT INTO mytable1(id,name) SELECT id, name FROM mystream WHERE METADATA$ACTION = 'INSERT';

Créer une arborescence de tâches simple en spécifiant la tâche mytask1 existante comme prédécesseur qui déclenche la nouvelle tâche mytask2 lorsqu’elle est exécutée avec succès. La nouvelle tâche interroge la table mytable et insère les résultats de la requête dans une autre table :

CREATE TASK mytask2
  WAREHOUSE = mywh
  AFTER mytask1
AS
INSERT INTO mytable2(id,name) SELECT id, name FROM mytable1;

Créez une tâche nommée my_copy_task qui appelle une procédure stockée pour décharger les données de la table mytable vers la zone de préparation mystage indiquée (à l’aide de COPY INTO <emplacement>) toutes les heures :

-- Create a stored procedure that unloads data from a table
-- The COPY statement in the stored procedure unloads data to files in a path identified by epoch time (using the Date.now() method)
create or replace procedure my_unload_sp()
  returns string not null
  language javascript
  as
  $$
    var my_sql_command = ""
    var my_sql_command = my_sql_command.concat("copy into @mystage","/",Date.now(),"/"," from mytable overwrite=true;");
    var statement1 = snowflake.createStatement( {sqlText: my_sql_command} );
    var result_set1 = statement1.execute();
  return my_sql_command; // Statement returned for info/debug purposes
  $$;

-- Create a task that calls the stored procedure every hour
create task my_copy_task
  warehouse = mywh
  schedule = '60 minute'
as
  call my_unload_sp();