Lancer un projet à partir d’un modèle

Pour vous permettre d’instancier plus facilement des projets, Snowflake CLI implémente la création de modèles de projet. Vous pouvez créer vos propres modèles de projets ou utiliser les échantillons fournis par Snowflake dans le référentiel public Git de modèles de CLI Snowflake.

La commande snow init crée un répertoire de projet et le remplit avec la structure de fichiers définie dans le modèle spécifié.

  • Si vous ne fournissez pas l’option --no-interactive, la commande invite pour chaque variable spécifiée par le modèle (template.yml) que vous ne fournissez pas avec l’option -D (ou --variable).

  • Si vous fournissez l’option --no-interactive, la commande utilise les valeurs par défaut des variables (définies par le modèle). Si le modèle ne définit pas de valeur par défaut pour une variable et que vous n’utilisez pas l’option -D pour la fournir, la commande fournit une erreur.

La commande snow init utilise la syntaxe suivante :

snow init PATH [--template-source SOURCE] [--template NAME] [-D key1=value1 -D key2=value2...] [--no-interactive]

où :

  • PATH est un nouveau répertoire où la commande initialise le projet. Si vous spécifiez un répertoire existant, la commande se termine avec une erreur.

  • [--template-source SOURCE] est l’un des éléments suivants :

    • Un chemin de fichier local du répertoire du modèle.

    • Une URL Git valide vers le répertoire contenant le modèle de projet. Si non spécifiée, la commande s’effectue par défaut pour le référentiel Git de modèles de CLI Snowflake.

  • [--template NAME] spécifie le sous-répertoire de SOURCE à utiliser comme modèle (utile pour les sources distantes). Si non fourni, SOURCE est traité comme un modèle unique.

  • [-D key1=value1 -D key2=value2...] est une liste d’une ou plusieurs paires nom-valeur, fournissant des valeurs pour les variables définies dans le modèle (dans template.yml). La commande ne demande pas les variables que vous fournissez avec cette option.

  • [--no-interactive] désactive les invites de saisie utilisateur. Si vous utilisez cette option, vous devez fournir toutes les valeurs requises avec les options [-D key1=value1 -D key2=value2...] ; sinon, la commande fournit une erreur.

Pour plus d’informations, voir la référence de commande snow init.

Exemples

  • Initialisez le projet du modèle example_snowpark à partir du référentiel par défaut :

    snow init my_snowpark_test_app --template example_snowpark

    La commande invite les éléments suivants (les valeurs par défaut sont indiquées entre crochets) :

    Project identifier (used to determine artifacts stage path) [my_snowpark_project]:
What stage should the procedures and functions be deployed to? [dev_deployment]: snowpark
Initialized the new project in my_snowpark_test_app

  • Initialisez le projet à partir du modèle local.

    snow init new_streamlit_project --template-source ../local_templates/example_streamlit -D query_warehouse=dev_wareshouse -D stage=testing

    Dans cet exemple, les variables query_warehouse et stage sont spécifiées avec l’option -D, donc la commande invite uniquement les éléments suivants :

    Name of the streamlit app [streamlit_app]:
Initialized the new project in new_streamlit_project

Création de modèles personnalisés

Disposition du modèle

Un modèle de projet nécessite un fichier template.yml qui contient des données expliquant comment la commande snow init doit restituer le modèle. Si le fichier n’est pas présent dans le répertoire racine du modèle, snow init se termine par une erreur. Pour plus d’informations, consultez la syntaxe template.yml.

Syntaxe du modèle

Les variables et expressions de modèle doivent être placées dans <! ... !>. Snowflake CLI prend également en charge les expressions et filtres jinja2 de base, par exemple :

some_file_spec:
  filename: <! file_name !>
  size: "<! [ max_file_size_mb, 4 ] | max !> MB"

Les modèles de projet Snowflake CLI prennent également en charge la variable réservée et le filtre suivants :

  • La variable project_dir_name, qui résout automatiquement le répertoire racine du projet créé.

    Par exemple, supposons que votre fichier snowflake.yml contient les éléments suivants :

    definition_version: "1.1"
snowpark:
  project_name: <! project_dir_name !>
  ...

    Si vous exécutez ensuite la commande suivante pour initialiser le projet à partir de votre modèle personnalisé :

    snow init examples/new_snowpark_project --template-source my_example_template/

    La commande snow init affiche le fichier snowflake.yml comme suit :

    definition_version: "1.1"
snowpark:
  project_name: new_snowpark_project
  ...

  • Le filtre to_snowflake_identifier, qui formate les chaînes fournies par l’utilisateur en identificateurs Snowflake correctement formatés.

    Snowflake recommande fortement d’utiliser ce filtre lorsqu’une variable fait référence à un objet Snowflake.

    Par exemple, supposons que votre fichier snowflake.yml contient les éléments suivants :

    definition_version: "1.1"
streamlit:
  name: <! name | to_snowflake_identifier !>
  ...

    Si vous exécutez ensuite la commande suivante pour initialiser un projet à partir de votre modèle personnalisé :

    snow init examples/streamlit --template-source my_example_template2/ -D name='My test streamlit'

    La commande snow init affiche le fichier snowflake.yml comme suit :

    definition_version: "1.1"
streamlit:
  name: My_test_streamlit
  ...

    Si une chaîne ne peut pas être convertie en identificateur Snowflake valide, la commande snow init se termine par une erreur, comme indiqué :

    snow init examples/streamlit --template-source my_example_template2/ -D name=1234567890

    ╭─ Error ────────────────────────────────────────────────────────────────────────╮
│ Value '123456789' cannot be converted to valid Snowflake identifier.         │
│ Consider enclosing it in double quotes: ""                                   │
╰────────────────────────────────────────────────────────────────────────────────╯

À propos du fichier de modèle de projet template.yml

Le fichier de modèle de projet template.yml stocke toutes les données nécessaires au rendu du projet. Par exemple :

minimum_cli_version: "2.7.0"
files_to_render:
  - snowflake.yml
variables:
  - name: name
    default: streamlit_app
    prompt: "Name of the streamlit app"
    type: string
  - name: stage
    default: my_streamlit_stage
    prompt: "What stage should the app be deployed to?"
    type: string
  - name: query_warehouse
    default: my_streamlit_warehouse
    prompt: "On which warehouse SQL queries issued by the application are run"
    type: string

Le tableau suivant répertorie les propriétés d’un fichier de modèle de projet template.yml.

Propriétés du modèle

Propriété

Définition

minimum_cli_version

optional, string (par défaut : None)

Version minimale de Snowflake CLI. Si spécifiée, la commande snow init vérifie la version de Snowflake CLI installée et se termine avec une erreur si la version installée est inférieure à la version spécifiée.

files_to_render

optional, string list (par défaut : [])

Liste des fichiers à afficher par la commande snow init. Chaque chemin doit être relatif à la racine des modèles.

Note

Les fichiers de modèles non inclus dans cette liste sont ajoutés au nouveau projet, mais leur contenu reste inchangé.

variables

optional, variable list (par défaut : [])

Liste des variables de modèle. Prend en charge la personnalisation des invites, la fourniture de valeurs par défaut pour les variables facultatives et la vérification de type de base. Consultez le tableau Paramètres de propriété des variables ci-dessous pour plus de détails. Les valeurs des variables sont déterminées dans l’ordre à partir de cette liste.

Si vous omettez une variable utilisée dans le fichier snowflake.yml de cette liste, la commande snow init se termine avec l’erreur suivante.

╭─ Error ─────────────────────────────────────────────────────────╮
│ Cannot determine value of variable undefined_variable         │
╰─────────────────────────────────────────────────────────────────╯

Le tableau suivant répertorie les paramètres d’une propriété de variable.

Paramètres de propriétés de variables

Propriété

Définition

name

required, string

Nom de la variable. Il est utilisé dans les fichiers de modèles, tels que <! name !> et dans l’option -D, telle que -D name=value.

prompt

optional, string

Invite à afficher à l’utilisateur pour obtenir une valeur. Si vous ne définissez pas ce paramètre, la commande affiche le nom du paramètre comme texte d’invite.

Si vous définissez l’invite comme suit :

variables:
  - name: project_id
    prompt: The identifier for the project

snow init affiche cette invite pour la variable project_id.

The identifier for the project:

default

optional, string/int/float

Default value of the variable. If not provided, the variable is treated as required, so a user needs to provide the value after a prompt or by specifying it with the -D command-line option.

L’exemple suivant définit deux variables avec des valeurs par défaut :

variables:
  - name: max_file_size_mb
    default: 16
  - name: file_name
    default: 'default_file_name.zip'

Une fois exécutée, la commande snow init affiche les invites suivantes pour ces deux variables :

file_name [default_file_name.zip]:
max_file_size_mb [16]: 5

Dans cet exemple, la commande utilise la valeur par défaut (default_file_name.zip) pour la variable file_name avec une valeur par défaut et définit max_file_size_mb sur la valeur fournie par l’utilisateur (5).

type

optional, string

Type de données de la variable. Les valeurs valides incluent : string, int et float. Si non spécifiée, la commande suppose que la valeur est une string.

L’exemple suivant définit une variable comme un type de données int :

variables:
  - name: max_file_size_mb
    type: int

Une fois exécutée, la commande snow init affiche les erreurs suivantes si l’utilisateur entre une valeur du mauvais type de données :

max_file_size_mb: not an int
Error: 'not an int' is not a valid integer.
max_file_size_mb: 14.5
Error: '14.5' is not a valid integer.
max_file_size_mb: 6
Initialized the new project in example_dir