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 , DESCRIBE TASK

Important

Les tâches nouvellement créées ou clonées sont créées dans un état suspendu. Pour plus d’informations sur la reprise des tâches suspendues, voir ALTER TASK … RESUME.

Syntaxe

CREATE [ OR REPLACE ] TASK [ IF NOT EXISTS ] <name>
  [ { WAREHOUSE = <string> } | { USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> } ]
  [ SCHEDULE = '{ <num> MINUTE | USING CRON <expr> <time_zone> }' ]
  [ CONFIG = <configuration_string> ]
  [ ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
  [ ERROR_INTEGRATION = <integration_name> ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ AFTER <string> [ , <string> , ... ] ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ FINALIZE = <string> ]
[ WHEN <boolean_expr> ]
AS
  <sql>
Copy

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 ]
  [ ... ]
Copy

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

Note

Le clonage de tâches à l’aide de CREATE TASK <nom> CLONE, ou le clonage d’un schéma contenant des tâches, copie toutes les propriétés de tâche sous-jacentes à moins qu’elles ne soient explicitement remplacées.

Paramètres requis

name

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.

sql

Un des éléments suivants :

  • Instruction SQL unique

  • Appel d’une procédure stockée

  • Logique procédurale à l’aide de l’Exécution de scripts Snowflake

    Notez qu’actuellement, Snowsight et l”Classic Console ne prennent pas en charge la création ou la modification de tâches pour utiliser Exécution de scripts Snowflake. Utilisez plutôt SnowSQL ou un autre client en ligne de commande.

Le code SQL est exécuté lorsque la tâche s’exécute.

Note

  • Le code SQL doit être exécutable par lui-même. 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.

  • Les tâches Serverless ne peuvent pas appeler les types d’objets suivants :

    • Des UDFs (fonctions définies par l’utilisateur) qui contiennent du code Java ou Python.

    • Des procédures stockées écrites en Scala (en utilisant Snowpark), ou qui appellent des UDFs qui contiennent du code Java ou Python.

Paramètres facultatifs

WAREHOUSE = string ou . USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = string

WAREHOUSE = string

Spécifie l’entrepôt virtuel qui fournit les ressources de calcul pour les exécutions de tâches.

Omettez ce paramètre pour utiliser les ressources de calcul gérées par Snowflake pour les exécutions de cette tâche. Aussi spécifiées comme tâches sans serveur, ces ressources sont automatiquement redimensionnées et augmentées ou diminuées par Snowflake en fonction des besoins pour chaque charge de travail. Lorsqu’un calendrier est spécifié pour une tâche, Snowflake ajuste la taille des ressources afin d’achever les exécutions futures de la tâche dans le délai spécifié. Pour spécifier la taille initiale de l’entrepôt pour la tâche, définissez le paramètre USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = string.

USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = string

S’applique uniquement aux tâches sans serveur.

Spécifie la taille des ressources de calcul à provisionner pour la première exécution de la tâche, avant qu’un historique de la tâche ne soit disponible pour que Snowflake puisse déterminer une taille idéale. Une fois qu’une tâche a effectué avec succès quelques cycles, Snowflake ignore ce paramètre.

Notez que si l’historique des tâches n’est pas disponible pour une tâche donnée, les ressources de calcul reviennent à cette taille initiale.

Note

Si une valeur de paramètre WAREHOUSE = string est spécifiée, alors la définition de ce paramètre produit une erreur utilisateur.

La taille est équivalente aux ressources de calcul disponibles lors de la création d’un entrepôt (en utilisant CREATE WAREHOUSE) : SMALL, MEDIUM, LARGE, etc. La plus grande taille prise en charge par le paramètre est XXLARGE. Si le paramètre est omis, les premières exécutions de la tâche s’effectuent en utilisant un entrepôt de taille moyenne (MEDIUM).

Vous pouvez modifier la taille initiale (en utilisant ALTER TASK) après la création de la tâche mais avant qu’elle ait été exécutée avec succès une fois. La modification du paramètre après le démarrage de la première exécution de cette tâche n’a aucun effet sur les ressources de calcul pour les exécutions actuelles ou futures de la tâche.

Notez que la suspension et la reprise d’une tâche ne suppriment pas l’historique des tâches utilisé pour dimensionner les ressources de calcul. L’historique de la tâche n’est supprimé que si la tâche est recréée (en utilisant la syntaxe CREATE OR REPLACETASK).

Pour plus d’informations sur ce paramètre, voir USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE.

SCHEDULE ...

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

Note

  • Une planification doit être définie pour une tâche autonome ou la tâche racine d’un DAG de tâches ; sinon, la tâche ne s’exécute que si elle est exécutée manuellement à l’aide de EXECUTE TASK.

  • Un calendrier ne peut pas être spécifié pour les tâches enfants dans un DAG.

  • USING CRON expr time_zone

    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 Wikipédia).

    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)
    # | | | | |
    # | | | | |
      * * * * *
    
    Copy

    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. Chaque quanta de temps est calculé indépendamment. 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). Le même calendrier est maintenu les années suivantes. En d’autres termes, l’exécution de la tâche n’est pas prévue en janvier (3 mois après l’exécution d’octobre).

    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.

    • La granularité de temps la plus courte en cron est la minute. Si une tâche est reprise pendant la minute définie dans son expression cron, la première exécution planifiée de la tâche est la prochaine occurrence de l’instance de l’expression cron. Par exemple, si une tâche planifiée pour s’exécuter quotidiennement à minuit (USING CRON 0 0 * * *) est reprise à minuit + 5 secondes (00:00:05), la première exécution de la tâche est planifiée pour la prochaine fois qu’il sera minuit.

  • num 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 num 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).

    Note

    La valeur maximale prise en charge est 11520 (8 jours). Les tâches dont la valeur num MINUTE est supérieure ne sont jamais exécutées.

CONFIG = configuration_string

Spécifie une représentation sous forme de chaîne de paires clé-valeur accessible par toutes les tâches de DAG. Doit être au format JSON. Pour plus d’informations sur l’obtention de la chaîne de configuration pour la tâche en cours d’exécution, consultez SYSTEM$GET_TASK_GRAPH_CONFIG.

Note

Ce paramètre ne peut être défini que sur une tâche racine. Le paramètre s’applique à tous les DAG.

Le paramètre peut être défini sur des tâches autonomes mais n’affecte pas le comportement de la tâche. Snowflake garantit qu’une seule instance d’une tâche autonome est en cours d’exécution à un moment donné.

ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE

Spécifie s’il faut autoriser l’exécution simultanée de plusieurs instances d’un DAG.

Note

Ce paramètre ne peut être défini que sur une tâche racine. Le paramètre s’applique à tous les DAG.

Le paramètre peut être défini sur des tâches autonomes mais n’affecte pas le comportement de la tâche. Snowflake garantit qu’une seule instance d’une tâche autonome est en cours d’exécution à un moment donné.

  • TRUE garantit qu’une seule instance d’une tâche racine est en cours d’exécution à un moment donné. Si une tâche racine est toujours en cours d’exécution lors de la prochaine heure d’exécution planifiée, cette heure planifiée est ignorée. Cette garantie ne s’étend pas aux tâches enfants. Si la prochaine exécution programmée de la tâche racine se produit alors que l’exécution actuelle d’une tâche enfant est toujours en cours, une autre instance du DAG commence.

  • FALSE garantit qu’une seule instance d’un DAG particulier est autorisée à fonctionner à la fois. La prochaine exécution d’une tâche racine n’est programmée qu’après la fin de l’exécution de toutes les tâches enfants du DAG. Cela signifie que si le temps cumulé nécessaire à l’exécution de toutes les tâches du DAG dépasse le temps explicitement prévu dans la définition de la tâche racine, au moins une exécution du DAG des tâches est sautée.

Par défaut : FALSE

session_parameter = value [ , session_parameter = value ... ]

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 = num

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.

  • Dans certaines situations, le paramètre STATEMENT_TIMEOUT_IN_SECONDS a une plus grande priorité que USER_TASK_TIMEOUT_MS. Pour plus de détails, voir STATEMENT_TIMEOUT_IN_SECONDS.

Pour plus d’informations sur ce paramètre, voir USER_TASK_TIMEOUT_MS.

Valeurs : 0 - 86400000 (1 jour).

Par défaut : 3600000 (1 heure)

SUSPEND_TASK_AFTER_NUM_FAILURES = num

Spécifie le nombre d’exécutions consécutives de tâches qui ont échoué après lequel la tâche en cours est suspendue automatiquement. Les exécutions de tâches qui ont échoué comprennent les exécutions dans lesquelles le code SQL dans le corps de la tâche produit une erreur de l’utilisateur ou expire. Les exécutions de tâches qui sont ignorées, annulées ou qui échouent en raison d’une erreur système sont considérées comme indéterminées et ne sont pas incluses dans le compte des exécutions de tâches qui ont échoué.

Définissez le paramètre sur une tâche autonome ou la tâche racine dans un DAG. Lorsque le paramètre est défini sur une valeur supérieure à 0, le comportement suivant s’applique aux exécutions de la tâche autonome ou dans le DAG :

  • Les tâches autonomes sont automatiquement suspendues après que le nombre spécifié d’exécutions consécutives de la tâche ait échoué ou ait expiré.

  • La tâche racine est automatiquement suspendue après l’échec de toute tâche unique dans un DAG ou après le nombre spécifié d’exécutions consécutives.

Ce paramètre s’applique aux tâches qui s’appuient sur des ressources informatiques gérées par Snowflake (c’est-à-dire le modèle de calcul sans serveur) ou sur des ressources informatiques gérées par l’utilisateur (c’est-à-dire un entrepôt virtuel).

Pour plus d’informations sur ce paramètre, voir SUSPEND_TASK_AFTER_NUM_FAILURES.

Valeurs : 0 - Pas de limite supérieure.

Défaut : 0 (pas de suspension automatique)

ERROR_INTEGRATION = 'integration_name'

Requis uniquement lors de la configuration d’une tâche pour envoyer des notifications d’erreur à l’aide d’Amazon Simple Notification Service (SNS), de Microsoft Azure Event Grid ou de Google Pub/Sub.

Spécifie le nom de l’intégration de notification utilisée pour communiquer avec Amazon SNS, MS Azure Event Grid ou Google Pub/Sub. Pour plus d’informations, reportez-vous à Activation des notifications d’erreur pour des tâches.

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 = 'string_literal'

Spécifie un commentaire pour la tâche.

Par défaut : aucune valeur

AFTER string [ , string , ... ]

Spécifie un ou plusieurs prédécesseurs pour la tâche actuelle. Utilisez cette option pour créer un DAG de tâches ou ajoutez cette tâche à un DAG existant. Une DAG est une série de tâches qui commence par une tâche racine planifiée et qui est liée par des dépendances.

Notez que la structure d’un DAG peut être définie après la création de toutes les tâches qui le composent. Exécutez les instructions ALTER TASK … ADD AFTER pour spécifier les prédécesseurs de chaque tâche dans le DAG planifié.

Une tâche s’exécute après que tous ses prédécesseurs ont terminé leur propre exécution avec succès (après un bref délai).

Note

  • La tâche racine doit avoir une planification définie. Chaque tâche enfant doit avoir un ou plusieurs prédécesseurs définis (c’est-à-dire des tâches spécifiées à l’aide du paramètre AFTER) pour relier les tâches entre elles.

  • Une tâche unique est limitée à 100 prédécesseurs et 100 tâches enfants. De plus, un DAG est limité à un maximum de 1 000 tâches au total (y compris la tâche racine) dans un état repris ou suspendu.

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

  • Toutes les tâches d’un DAG 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 du DAG).

  • Toutes les tâches d’un DAG doivent exister dans le même schéma.

  • La tâche racine doit être suspendue avant que toute tâche 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 ou ALTER TASK … ADD AFTER) ou supprimé (à l’aide de ALTER TASK … REMOVE AFTER).

  • Si une tâche dans un DAG 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.

  • 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 boolean_expr

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.

Les éléments suivants sont pris en charge dans une clause WHEN de tâche :

  • SYSTEM$STREAM_HAS_DATA est prise en charge pour l’évaluation dans l’expression SQL.

    Cette fonction indique si un flux spécifié contient des données de suivi des modifications. Vous pouvez utiliser cette fonction pour évaluer si le flux spécifié contient des données de modification avant de lancer l’exécution en cours. Si le résultat est FALSE, la tâche ne s’exécute pas.

    Note

    SYSTEM$STREAM_HAS_DATA est conçu pour éviter les faux négatifs (c’est-à-dire qu’elle renvoie une valeur FALSE même si le flux contient des données de changement). Toutefois, cette fonction n’est pas garantie pour éviter les faux positifs (c’est-à-dire qu’elle renvoie une valeur TRUE lorsque le flux ne contient pas de données de modification).

  • SYSTEM$GET_PREDECESSOR_RETURN_VALUE est prise en charge pour l’évaluation dans l’expression SQL.

    Cette fonction récupère la valeur de retour pour le prédécesseur dans un DAG de tâches. La valeur de retour peut être utilisée dans le cadre d’une expression booléenne. Lorsque vous utilisez SYSTEM$GET_PREDECESSOR_RETURN_VALUE, vous pouvez convertir la valeur renvoyée dans le type numérique, chaîne de caractères ou booléen approprié, si nécessaire.

    Voici quelques exemples simples :

    WHEN NOT SYSTEM$GET_PREDECESSOR_RETURN_VALUE('task_name')::BOOLEAN
    
    Copy
    WHEN SYSTEM$GET_PREDECESSOR_RETURN_VALUE('task_name') != 'VALIDATION'
    
    Copy
    WHEN SYSTEM$GET_PREDECESSOR_RETURN_VALUE('task_name')::FLOAT < 0.2
    
    Copy

    Note

    L’utilisation de PARSE_JSON dans les expressions TASK … WHEN n’est pas prise en charge, car elle nécessite des ressources de calcul basées sur l’entrepôt.

  • Opérateurs booléens tels que AND, OR, NOT et autres.

  • Effectue la conversion entre les types numérique, chaîne de caractères et booléen.

  • Opérateurs de comparaison tels que égal, non égal, supérieur à, inférieur à, et autres.

La validation des conditions de l’expression WHEN ne nécessite pas de ressources de calcul. La validation est plutôt traitée dans la couche des services Cloud. Une charge nominale s’accumule chaque fois qu’une tâche évalue sa condition WHEN et ne s’exécute pas. Les frais s’accumulent chaque fois que la tâche est déclenchée jusqu’à son exécution. À ce moment, les frais sont convertis en crédits Snowflake et ajoutés à l’utilisation des ressources de calcul pour l’exécution de la tâche.

En général, le temps de calcul pour valider la condition est insignifiant par rapport au temps d’exécution de la tâche. La meilleure pratique consiste à aligner le plus étroitement possible le déroulement prévu et le déroulement effectif des tâches. Évitez les calendriers de tâches qui sont totalement désynchronisés par rapport aux tâches réelles. Par exemple, si des données sont insérées dans une table avec un flux toutes les 24 heures environ, ne programmez pas une tâche qui vérifie les données du flux toutes les minutes. Les frais pour valider l’expression WHEN à chaque exécution sont généralement insignifiants, mais les frais se cumulent.

Notez que la consommation quotidienne de services Cloud qui tombe en dessous des 10 % de quota de l’utilisation quotidienne des ressources de calcul n’accumule pas de frais de services Cloud.

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

Spécifie le nom de la balise et la valeur de la chaîne de la balise.

La valeur de la balise est toujours une chaîne de caractères et le nombre maximum de caractères pour la valeur de la balise est 256.

Pour plus de détails sur la spécification des balises dans une instruction, voir Quotas de balises pour les objets et les colonnes.

FINALIZE = string

Spécifie le nom d’une tâche racine à laquelle la tâche de finalisation est associée. Une tâche de finalisation gère la publication et le nettoyage des ressources utilisées par un DAG. L’exécution d’une tâche de finalisation est garantie si le graphe est exécuté. Toutefois, si un graphe est ignoré (par exemple, la tâche racine est ignorée), la tâche de finalisation ne s’exécutera pas.

  • Une tâche racine ne peut avoir qu’une seule tâche de finalisation. Si vous créez plusieurs tâches de finalisation pour une tâche racine, la création de la tâche échouera.

  • Une tâche de finalisation ne peut pas avoir de tâches enfants. Toute commande tentant de faire de la tâche de finalisation un prédécesseur échouera.

  • Une tâche de finalisation ne peut pas avoir de planification. La création d’une tâche de finalisation avec une planification échouera.

Par défaut : aucune valeur

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège

Objet

Remarques

EXECUTE MANAGED TASK

Compte

Requis uniquement pour les tâches qui dépendent des ressources de calcul gérées par Snowflake pour les exécutions (tâches sans serveur).

CREATE TASK

Schéma

USAGE

Entrepôt

Requis uniquement pour les tâches qui dépendent des entrepôts gérés par l’utilisateur pour les exécutions.

Notez que l’exploitation d’un objet dans un schéma requiert également le privilège USAGE sur la base de données et le schéma parents.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

  • Les tâches s’exécutent en utilisant les privilèges accordés au propriétaire de la tâche (c’est-à-dire le rôle qui possède le privilège OWNERSHIP sur la tâche). Pour obtenir la liste des privilèges minimums requis pour exécuter les tâches, voir Sécurité des tâches.

    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.

  • Les ressources de calcul pour les exécutions individuelles d’une tâche sont soit gérées par Snowflake (c’est-à-dire les tâches sans serveur), soit par un entrepôt virtuel spécifié par l’utilisateur. Pour utiliser des tâches sans serveur, omettez le paramètre WAREHOUSE = string dans l’instruction CREATE TASK.

    • Les ressources gérées par Snowflake pour une tâche peuvent aller de l’équivalent de XSMALL à XXLARGE en taille d’entrepôt. Si vous souhaitez inclure des tailles d’entrepôt plus importantes dans cette gamme, contactez l’assistance Snowflake pour demander une augmentation de taille.

    • Le modèle sans serveur peut être activé pour une ou plusieurs tâches dans un DAG. Les exécutions de tâches individuelles dans un DAG peuvent s’appuyer sur des ressources informatiques gérées par Snowflake ou par l’utilisateur. Il n’est pas nécessaire d’activer ce modèle de calcul sans serveur pour toutes les tâches du DAG.

  • 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 30 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.

  • Si une tâche échoue avec une erreur inattendue, vous pouvez recevoir une notification concernant l’erreur. Pour plus d’informations sur la configuration des notifications d’erreur de tâche, reportez-vous à Activation des notifications d’erreur pour des tâches.

  • 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. Notez les comportements suivants :

    • La tâche recréée est suspendue par défaut.

    • 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.

    • Si une tâche autonome ou racine est recréée, la prochaine exécution planifiée de la tâche est annulée.

    • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

Exemples

Instruction SQL unique

Créer une tâche sans serveur qui interroge l’horodatage actuel 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 taille initiale de l’entrepôt est XSMALL :

CREATE TASK t1
  SCHEDULE = 'USING CRON 0 9-17 * * SUN America/Los_Angeles'
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
AS
SELECT CURRENT_TIMESTAMP;
Copy

Comme dans l’exemple précédent, mais la tâche s’appuie sur un entrepôt géré par l’utilisateur pour fournir les ressources de calcul pour les exécutions :

CREATE TASK mytask_hour
  WAREHOUSE = mywh
  SCHEDULE = 'USING CRON 0 9-17 * * SUN America/Los_Angeles'
AS
SELECT CURRENT_TIMESTAMP;
Copy

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 sans serveur qui insère l’horodatage actuel dans une table toutes les heures. La tâche définit le paramètre TIMESTAMP_INPUT_FORMAT pour la session dans laquelle la tâche est exécutée. Ce paramètre de session spécifie le format de l’horodatage inséré :

CREATE TASK t1
  SCHEDULE = '60 MINUTE'
  TIMESTAMP_INPUT_FORMAT = 'YYYY-MM-DD HH24'
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
AS
INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);
Copy

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);
Copy

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';
Copy

Créer une tâche enfant sans serveur dans un DAG et ajouter plusieurs tâches prédécesseurs. La tâche enfant ne s’exécute que lorsque toutes les tâches prédécesseurs spécifiées ont terminé avec succès leur propre exécution.

Supposons que la tâche racine d’un DAG soit task1 et que task2, task3, et task4 soient des tâches enfants de task1. Cet exemple ajoute la tâche enfant task5 au DAG et spécifie task2, task3, et task4 comme tâches prédécesseurs :

-- Create task5 and specify task2, task3, task4 as predecessors tasks.
-- The new task is a serverless task that inserts the current timestamp into a table column.
CREATE TASK task5
  AFTER task2, task3, task4
AS
INSERT INTO t1(ts) VALUES(CURRENT_TIMESTAMP);
Copy

Procédure stockée

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();
Copy

Instructions SQL multiples utilisant SnowSQL

Créez une tâche qui exécute plusieurs instructions SQL. Dans cet exemple, la tâche modifie le TIMESTAMP_OUTPUT_FORMAT de la session et interroge ensuite la fonction CURRENT_TIMESTAMP.

Note

Le code SQL dans la définition de la tâche comprend plusieurs instructions. Pour exécuter l’instruction CREATE TASK, vous devez temporairement définir un caractère autre que un point-virgule comme délimiteur des instructions SQL ; sinon, l’instruction CREATE TASK renverrait une erreur utilisateur. La commande permettant de modifier le délimiteur SQL dans SnowSQL est !set sql_delimiter = <caractère>.

!set sql_delimiter=/
CREATE OR REPLACE TASK test_logging
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
  SCHEDULE = 'USING CRON  0 * * * * America/Los_Angeles'
AS
BEGIN
  ALTER SESSION SET TIMESTAMP_OUTPUT_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF';
  SELECT CURRENT_TIMESTAMP;
END;/
!set sql_delimiter=";"
Copy

Logique procédurale à l’aide de l’Exécution de scripts Snowflake

Crée une tâche qui déclare une variable, utilise la variable et renvoie la valeur de la variable toutes les deux minutes :

CREATE TASK t1
  USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL'
  SCHEDULE = '2 minute'
  AS
  EXECUTE IMMEDIATE
  $$
  DECLARE
    radius_of_circle float;
    area_of_circle float;
  BEGIN
    radius_of_circle := 3;
    area_of_circle := pi() * radius_of_circle * radius_of_circle;
    return area_of_circle;
  END;
  $$;

Examples:
Copy

Tâche racine avec configuration

Créez une tâche qui spécifie la configuration, puis lit cette configuration.

CREATE OR REPLACE TASK root_task_with_config
WAREHOUSE=mywarehouse
SCHEDULE='10 m'
CONFIG=$${"output_dir": "/temp/test_directory/", "learning_rate": 0.1}$$
AS
BEGIN
  LET OUTPUT_DIR STRING := SYSTEM$GET_TASK_GRAPH_CONFIG('output_directory')::string;
  LET LEARNING_RATE DECIMAL := SYSTEM$GET_TASK_GRAPH_CONFIG('learning_rate:v1')::DECIMAL;
      ...
END;
Copy