Configurer les compilations

Ce document vous explique comment effectuer les opérations suivantes dans Dataform :

Avant de commencer

  1. Dans la console Google Cloud , accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez ou créez un dépôt.

  3. Sélectionnez ou créez un espace de travail de développement.

  4. Facultatif : Pour remplacer le projet Google Cloud par défaut dans la configuration de la version, accordez l'accès à votre compte de service Dataform au projet que vous prévoyez d'utiliser.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Dataform (roles/dataform.admin) sur les dépôts. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour pouvoir mettre à jour la version d'une configuration de version pour un dépôt Dataform lorsque le mode strict "Agir en tant que" est activé, vous devez disposer de l'autorisation iam.serviceAccounts.actAs sur chaque compte de service dans les configurations de workflow qui utilisent cette configuration de version. Cette autorisation est disponible dans le rôle Utilisateur du compte de service (roles/iam.serviceAccountUser).

Présentation du cycle de vie des workflows dans Dataform

Cette section décrit le cycle de vie des workflows dans Dataform et les méthodes permettant de configurer la compilation et l'exécution dans Dataform.

Le cycle de vie du workflow Dataform se compose des phases suivantes :

Développement
Vous développez un workflow dans un espace de travail Dataform.
Compilation

Dataform compile le code du workflow dans votre espace de travail en SQL en temps réel, ce qui crée un résultat de compilation de l'espace de travail que vous pouvez exécuter dans BigQuery. Dataform utilise les paramètres que vous définissez dans le fichier de paramètres de votre workflow pour créer le résultat de la compilation.

La compilation Dataform est hermétique pour garantir la cohérence de la compilation. Cela signifie que le même code est compilé dans le même résultat de compilation SQL à chaque fois. Dataform compile votre code dans un environnement de bac à sable sans accès à Internet. Aucune action supplémentaire, comme l'appel d'API externes, n'est disponible pendant la compilation.

Exécution

Dans une invocation de workflow, Dataform exécute le résultat de la compilation de l'espace de travail dans BigQuery.

Pour adapter le cycle de vie du workflow Dataform à vos besoins, vous pouvez configurer le résultat de la compilation pour définir où et comment Dataform exécute votre workflow. Vous pouvez ensuite déclencher les exécutions manuellement ou les planifier pour déterminer quand Dataform doit exécuter tout ou partie de votre workflow.

Configurer la compilation Dataform

Par défaut, Dataform utilise les paramètres du fichier de paramètres du workflow pour créer les résultats de la compilation. Vous pouvez remplacer les paramètres par défaut par des substitutions de compilation pour créer des résultats de compilation personnalisés. Vous pouvez ensuite déclencher manuellement l'exécution d'un résultat de compilation personnalisé ou programmer des exécutions.

Dataform propose les options suivantes pour configurer les résultats de compilation :

Remplacements de compilation d'espace de travail
Vous pouvez configurer des remplacements de compilation qui s'appliquent à tous les espaces de travail d'un dépôt. Vous pouvez utiliser les remplacements de compilation d'espace de travail pour créer des environnements de développement isolés.
Configurations des versions
Vous pouvez créer des configurations de version pour configurer des modèles permettant de créer des résultats de compilation d'un dépôt Dataform. Vous pouvez ensuite créer une configuration de workflow pour planifier les exécutions des résultats de compilation créés dans une configuration de version sélectionnée.
Remplacements de compilation de l'API Dataform
Vous pouvez transmettre des requêtes à l'API Dataform dans le terminal pour créer et exécuter un résultat de compilation unique avec des remplacements de compilation.

Configurer des remplacements de compilation d'espace de travail

Les remplacements de compilation d'espace de travail vous permettent de créer des remplacements de compilation pour tous les espaces de travail d'un dépôt Dataform. Vous pouvez créer une configuration de remplacements de compilation d'espace de travail pour chaque dépôt.

Lorsque vous déclenchez manuellement une exécution dans un espace de travail d'un dépôt avec des remplacements de compilation d'espace de travail, Dataform applique ces remplacements au résultat de la compilation de l'espace de travail.

Vous pouvez configurer les remplacements de compilation d'espace de travail suivants :

  • Google Cloud  : projet dans lequel Dataform exécute le contenu de l'espace de travail
  • Préfixe de la table
  • Suffixe du schéma

Vous pouvez utiliser des remplacements de compilation d'espace de travail pour créer des environnements de développement isolés en isolant les résultats de compilation d'espace de travail dans BigQuery avec des remplacements de compilation dynamiques. Les remplacements de compilation de préfixe de table et de suffixe de schéma dynamiques contiennent la variable ${workspaceName}. Lorsque vous déclenchez une exécution dans un espace de travail, Dataform remplace la variable ${workspaceName} par le nom de l'espace de travail actuel, ce qui crée des remplacements de compilation propres à l'espace de travail.

N'oubliez pas que vous ne pouvez pas planifier l'exécution des résultats de compilation créés avec des remplacements de compilation d'espace de travail.

Créer des configurations de version

Les configurations de version vous permettent de configurer des modèles de paramètres pour créer des résultats de compilation de dépôts.

Dans une configuration de version, vous pouvez configurer des remplacements de compilation des paramètres de workflow, des variables de compilation et de la fréquence de création des résultats de compilation de l'ensemble de votre dépôt.

Dans une configuration de version, vous pouvez configurer les remplacements de compilation suivants :

Vous pouvez créer plusieurs configurations de publication dans un dépôt Dataform, une pour chaque étape de votre cycle de développement, ce qui permet de créer des résultats de compilation de dépôt isolés.

Vous pouvez ensuite créer des configurations de workflow pour planifier des exécutions des résultats de compilation créés dans une configuration de version sélectionnée.

Vous pouvez également déclencher manuellement l'exécution d'un résultat de compilation dans une configuration de version sélectionnée.

Configurer un seul résultat de compilation avec les remplacements de compilation de l'API Dataform

En transmettant des requêtes d'API Dataform dans le terminal, vous pouvez configurer des remplacements de compilation pour un seul résultat de compilation.

Dans la requête compilationResults.create, vous pouvez créer un résultat de compilation unique pour un espace de travail Dataform ou un commit Git spécifié.

Dans l'objet CodeCompilationConfig de la requête compilationResults.create, vous pouvez configurer des remplacements de compilation pour la requête de compilation.

Vous pouvez configurer les remplacements de compilation de l'API Dataform suivants :

N'oubliez pas que les forçages de compilation de l'API Dataform s'appliquent à un seul résultat de compilation et à une seule exécution. Vous ne pouvez pas les utiliser pour planifier des exécutions Dataform.

Vous pouvez exécuter un résultat de compilation dans la requête workflowInvocations.create.

Configurer l'exécution Dataform

Dataform propose les options suivantes pour configurer l'exécution :

Exécution manuelle dans un espace de travail
Vous pouvez déclencher manuellement l'exécution instantanée d'un workflow dans un espace de travail Dataform, en dehors de toute planification. Vous pouvez exécuter les actions sélectionnées dans le workflow.
Configurations de workflow
Vous pouvez planifier l'exécution des résultats de compilation créés dans une configuration de version sélectionnée. Vous pouvez sélectionner les actions de workflow à exécuter, et définir la fréquence et le fuseau horaire des exécutions.

Déclencher une exécution instantanée dans un espace de travail

Dans un espace de travail Dataform, vous pouvez déclencher manuellement l'exécution instantanée d'un workflow dans votre espace de travail, en dehors de toute planification.

Vous pouvez exécuter manuellement les éléments suivants du workflow dans votre espace de travail :

Si votre dépôt contient des remplacements de compilation d'espace de travail, vous pouvez voir quels remplacements de compilation Dataform appliquera au résultat de la compilation de l'espace de travail.

Créer des configurations de workflow

Les configurations de workflow vous permettent de planifier des exécutions de résultats de compilation à partir d'une configuration de version sélectionnée. Vous pouvez créer plusieurs configurations de workflow dans un dépôt Dataform.

Dans une configuration de workflow, vous pouvez configurer les paramètres d'exécution suivants :

  • Configuration de version de compilation appliquée.
  • Sélection des actions de workflow à exécuter.
  • Planification et fuseau horaire des exécutions.

Vous pouvez sélectionner les actions de workflow suivantes à exécuter :

  • Toutes les actions
  • Actions sélectionnées
  • Actions avec les tags sélectionnés

Ensuite, lors d'une exécution planifiée de votre configuration de workflow, Dataform déploie votre sélection d'actions à partir du résultat de compilation appliqué dans BigQuery.

Les configurations de version et de workflow Dataform vous permettent de configurer la compilation et de planifier les exécutions dans Dataform, sans avoir besoin de faire appel à des services supplémentaires.

Expiration des ressources de cycle de vie

Dataform stocke les résultats de compilation et les appels de workflow pendant une période spécifique.

Expiration des appels de workflows

Les invocations de workflow expirent au bout de 90 jours ou lorsque vous les supprimez manuellement.

Dans une configuration de workflow, vous pouvez afficher la liste des invocations de workflow les plus récentes créées par la configuration. Lorsqu'une invocation de workflow créée par une configuration de workflow expire, Dataform la supprime de la liste des invocations récentes.

Expiration des résultats de compilation

L'expiration des résultats de compilation dépend de leur mode de création : dans un espace de travail de développement, dans une configuration de version ou par l'invocation d'un workflow.

Lorsque vous développez un workflow dans un espace de travail Dataform, Dataform compile votre code en temps réel pour valider les requêtes. Les résultats de compilation créés de cette manière expirent au bout de 24 heures.

Dans une configuration de version, le dernier résultat de compilation devient le résultat de compilation en direct. Un nouveau résultat de compilation remplace le résultat de compilation en direct actuel. Dataform conserve le résultat de la compilation en direct jusqu'à ce qu'il soit remplacé par un nouveau résultat de compilation. Un résultat de compilation remplacé expire au bout de 24 heures maximum.

Dataform supprime les résultats de compilation expirés de la liste des résultats de compilation passés sur la page Détails d'une configuration de version.

Dataform conserve les résultats de compilation créés par les appels de workflow pendant toute la durée de vie de l'appel de workflow, jusqu'à 24 heures après l'expiration ou la suppression de l'appel de workflow.

Créer des remplacements de compilation d'espace de travail

Les sections suivantes expliquent comment créer des remplacements de compilation d'espace de travail pour isoler les tables et les vues créées à partir de vos espaces de travail Dataform dans BigQuery. Vous pouvez utiliser des remplacements de compilation d'espace de travail pour créer des environnements de développement Dataform isolés.

Lorsque vous développez du code de workflow dans un espace de travail Dataform, Dataform compile le code de votre espace de travail en temps réel pour créer un résultat de compilation de l'espace de travail. Dataform utilise les paramètres définis dans le fichier de paramètres du workflow pour créer le résultat de la compilation de l'espace de travail. Ensuite, lorsque vous déclenchez l'exécution dans un espace de travail, Dataform exécute le résultat de la compilation de l'espace de travail dans BigQuery.

Pour remplacer les paramètres par défaut définis dans les paramètres de workflow pour tous les espaces de travail de votre dépôt, vous pouvez créer des remplacements de compilation d'espace de travail.

Les remplacements de compilation d'espace de travail vous permettent de remplacer les paramètres suivants pour tous les espaces de travail de votre dépôt :

Projet
Le Google Cloud projet dans lequel Dataform exécute le résultat de la compilation de l'espace de travail, défini dans workflow_settings.yaml comme defaultProject ou dans dataform.json comme defaultDatabase.
Préfixe de la table
Préfixe personnalisé ajouté à tous les noms de tables dans tous les espaces de travail du dépôt.
Suffixe du schéma
Suffixe personnalisé ajouté au schéma des tables. Définissez-le sur defaultDataset dans workflow_settings.yaml, sur defaultSchema dans dataform.json ou dans le paramètre schema du bloc config d'un tableau.

Pour créer des environnements de développement isolés, vous pouvez isoler des espaces de travail avec des remplacements de compilation uniques. Vous pouvez modifier de manière dynamique les remplacements de compilation du préfixe de table et du suffixe de schéma avec la variable ${workspaceName}.

Lorsque vous déclenchez manuellement l'exécution dans un espace de travail, la variable ${workspaceName} injecte le nom de l'espace de travail dans les remplacements de compilation de l'espace de travail.

Lorsque vous définissez ${workspaceName} comme préfixe de table, Dataform ajoute le nom de l'espace de travail à tous les noms de tables de l'espace de travail. Après l'exécution, vous pouvez identifier dans BigQuery l'espace de travail d'origine d'une table.

Lorsque vous définissez ${workspaceName} comme suffixe de schéma, Dataform ajoute le nom de l'espace de travail à defaultSchema, créant ainsi un schéma personnalisé dédié à l'espace de travail. Après l'exécution, vous pouvez localiser toutes les tables exécutées à partir d'un espace de travail spécifique dans le schéma dédié de BigQuery.

Exemple de remplacements de compilation d'espace de travail dynamiques

L'exemple suivant montre des remplacements de compilation d'espace de travail dynamique appliqués à un dépôt contenant des espaces de travail nommés d'après les développeurs qui travaillent sur le dépôt : Sasha et Kai.

Dans cet exemple, l'objectif des remplacements de compilation d'espace de travail est de créer des environnements de développement isolés pour Sasha et Kai.

Les paramètres par défaut suivants sont définis dans workflow_settings.yaml :

  • defaultProject : analytics
  • defaultDataset : dataform

Les remplacements de compilation d'espace de travail suivants créent un préfixe de table et un suffixe de schéma dynamiques pour chaque espace de travail du dépôt :

  • ID du projet Google Cloud : analytics_dev
  • Préfixe de table : ${workspaceName}
  • Suffixe du schéma : ${workspaceName}

Lorsque Sasha déclenche manuellement l'exécution dans l'espace de travail Sasha, Dataform exécute son contenu avec les paramètres suivants :

  • Google Cloud project: analytics_dev
  • Schéma : dataform_sasha
  • Noms de tables : sasha_name, par exemple sasha_orders

Lorsque Kai déclenche manuellement l'exécution dans l'espace de travail Kai, Dataform exécute son contenu avec les paramètres suivants :

  • Google Cloud project: analytics_dev
  • Schéma : dataform_kai
  • Noms des tables : kai_name, par exemple kai_orders

Créer des remplacements de compilation d'espace de travail

Pour créer des remplacements de compilation d'espace de travail Dataform, procédez comme suit :

  1. Dans votre dépôt, accédez à Settings (Paramètres).
  2. Cliquez sur Modifier.
  3. Dans le volet Remplacements de compilation d'espace de travail, saisissez l'ID du projet dans le champ ID du projet Google Cloud.
  4. Dans le champ Préfixe de table, saisissez un préfixe pour tous les noms de table.
    1. Facultatif : Pour créer un préfixe de table dynamique unique pour chaque espace de travail, saisissez ${workspaceName} comme préfixe de table.
  5. Dans le champ Suffixe du schéma, saisissez un suffixe à ajouter au schéma de la table ou de la vue créée.
    1. Facultatif : Pour créer un suffixe de schéma dynamique unique pour chaque espace de travail, saisissez ${workspaceName} comme suffixe de table.
  6. Cliquez sur Enregistrer.

Dataform applique des remplacements de compilation d'espace de travail à tous les espaces de travail de votre dépôt.

Modifier les remplacements de compilation d'espace de travail

Pour modifier les remplacements de compilation d'espace de travail Dataform, procédez comme suit :

  1. Dans votre dépôt, accédez à Settings (Paramètres).
  2. Cliquez sur Modifier.
  3. Modifiez les remplacements de compilation de l'espace de travail, puis cliquez sur Enregistrer.

Supprimer les remplacements de compilation d'espace de travail

Pour supprimer les remplacements de compilation d'espace de travail Dataform, procédez comme suit :

  1. Dans votre dépôt, accédez à Settings (Paramètres).
  2. Cliquez sur Modifier.
  3. Dans le volet Remplacements de compilation d'espace de travail, cliquez sur Tout effacer, puis sur Enregistrer.

Configurer les remplacements de compilation avec l'API Dataform

Cette section explique comment créer et exécuter un résultat de compilation avec des remplacements de compilation à l'aide de l'API Dataform.

À propos des remplacements de compilation de l'API Dataform

Pour exécuter votre workflow, Dataform compile votre code en SQL afin de créer un résultat de compilation. Ensuite, lors d'une invocation de workflow, Dataform exécute le résultat de la compilation dans BigQuery.

Par défaut, Dataform utilise les paramètres du fichier de paramètres du workflow pour créer le résultat de la compilation. Pour isoler les données exécutées à différentes étapes de votre cycle de développement, vous pouvez remplacer les paramètres par défaut par des remplacements de compilation.

En transmettant des requêtes à l'API Dataform dans le terminal, vous pouvez créer et exécuter un résultat de compilation unique avec des remplacements de compilation. Vous pouvez créer un résultat de compilation d'un espace de travail ou d'un committish Git sélectionné.

Pour créer un résultat de compilation avec des remplacements de compilation, vous devez envoyer une requête compilationResults.create à l'API Dataform. Dans la requête, vous devez spécifier une source, qui doit être un espace de travail ou un commitish Git, pour que Dataform la compile dans le résultat de la compilation. Dans l'objet CodeCompilationConfig de la requête compilationResults.create, vous pouvez configurer des remplacements de compilation.

Vous pouvez ensuite exécuter le résultat de la compilation créé dans une requête workflowInvocations.create de l'API Dataform.

Vous pouvez configurer les forçages de compilation suivants à l'aide de l'API Dataform :

Google Cloud project
Projet dans lequel Dataform exécute le résultat de la compilation, défini dans le fichier workflow_settings.yaml en tant que propriété defaultProject ou dans le fichier dataform.json en tant que propriété defaultDatabase.
Préfixe de la table
Préfixe personnalisé ajouté à tous les noms de tables dans le résultat de la compilation.
Suffixe de schéma
Suffixe personnalisé ajouté au schéma des tables définies dans la propriété defaultDataset du fichier workflow_settings.yaml, dans la propriété defaultSchema du fichier dataform.json ou dans le paramètre schema du bloc config d'une table.
Valeur d'une variable de compilation
Valeur d'une variable de compilation à utiliser dans le résultat de la compilation. Vous pouvez utiliser des variables de compilation pour exécuter des tableaux de manière conditionnelle.

Au lieu des remplacements de compilation de l'API Dataform, que vous ne pouvez utiliser que pour un seul résultat de compilation, vous pouvez configurer les remplacements de compilation de l'espace de travail dans la console Google Cloud .

Pour découvrir d'autres façons de configurer les remplacements de compilation dans Dataform, consultez Présentation du cycle de vie des workflows dans Dataform.

Définir une source de résultat de compilation

Pour envoyer une demande compilationResults.create à l'API Dataform, vous devez spécifier une source pour le résultat de la compilation.

Vous pouvez définir un espace de travail Dataform ou une branche Git, un tag Git ou un SHA de commit Git comme source dans la requête compilationResults.create.

Définir un espace de travail comme source de résultat de compilation

  • Dans la requête compilationResults.create, renseignez la propriété workspace avec le chemin d'accès d'un espace de travail Dataform sélectionné au format suivant :

    {
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

    Remplacez les éléments suivants :

    • PROJECT_NAME : nom de votre projet Google Cloud .
    • LOCATION : emplacement de votre dépôt Dataform, défini dans les paramètres du workflow.
    • REPOSITORY_NAME : nom de votre dépôt Dataform.
    • WORKSPACE_NAME : nom de votre espace de travail Dataform.

L'exemple de code suivant montre la propriété workspace dans la requête compilationResults.create définie sur un espace de travail appelé "sales-test" :

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Définir un commit Git comme source de résultat de compilation

  • Dans la requête compilationResults.create, renseignez la propriété gitCommitish avec la branche, le tag ou le SHA de commit Git sélectionnés, au format suivant :

    {
  "gitCommitish": "GIT_COMMITISH"
}

    Remplacez GIT_COMMITISH par la branche Git, le tag Git ou le SHA de commit Git sélectionnés pour le résultat de la compilation.

L'exemple de code suivant montre la propriété gitCommitish dans la requête compilationResults.create définie sur "staging" :

{
  "gitCommitish": "staging"
}

Remplacer le projet par défaut

Pour créer des tables de staging ou de production dans un projet Google Cloud distinct de celui utilisé pour le développement, vous pouvez transmettre un ID de projet différent dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

Si vous transmettez un ID de projet par défaut distinct dans la requête compilationResults.create, il remplacera l'ID de projet par défaut configuré dans le fichier de paramètres du workflow, mais pas les ID de projet configurés dans les tables individuelles.

  • Pour remplacer l'ID de projet par défaut, définissez la propriété defaultDatabase sur l'ID de projet sélectionné dans l'objet CodeCompilationConfig au format suivant :

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

    Remplacez PROJECT_NAME par l'ID du projet que vous souhaitez définir pour le résultat de la compilation.

Ajouter un préfixe de table

Pour identifier rapidement les tables à partir du résultat de la compilation, vous pouvez ajouter un préfixe à tous les noms de tables du résultat de la compilation en transmettant le préfixe de table dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

  • Pour ajouter un préfixe de table, définissez la propriété tablePrefix dans l'objet CodeCompilationConfig au format suivant :

    {
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

    Remplacez PREFIX par le préfixe que vous souhaitez ajouter, par exemple staging.

    Par exemple, si le nom de votre table est table_name, Dataform crée des tables avec le nom staging_table_name.

Ajouter un suffixe de schéma

Pour séparer les données de développement, de préproduction et de production, vous pouvez ajouter un suffixe aux schémas dans un résultat de compilation en transmettant le suffixe de schéma dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

  • Pour ajouter un suffixe de schéma, définissez la propriété schemaSuffix dans l'objet CodeCompilationConfig au format suivant :

    {
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

    Remplacez SUFFIX par le suffixe que vous souhaitez ajouter, par exemple _staging.

    Par exemple, si votre propriété defaultDataset dans le fichier workflow_settings.yaml est définie sur dataform, Dataform crée des tables dans le schéma dataform_staging.

Exécuter des fichiers sélectionnés de manière conditionnelle avec des variables de compilation

Pour n'exécuter qu'un tableau sélectionné dans un paramètre d'exécution spécifique, vous pouvez créer une variable de compilation pour le paramètre d'exécution, puis transmettre sa valeur dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

Pour exécuter une table de manière conditionnelle dans un paramètre d'exécution spécifique à l'aide de l'API Dataform, procédez comme suit :

  1. Créez une variable de compilation et ajoutez-la aux tables sélectionnées.

  2. Définissez la paire clé/valeur YOUR_VARIABLE et VALUE dans le bloc codeCompilationConfig d'une requête de compilation de l'API Dataform au format suivant :

    {
  "codeCompilationConfig": {
    "vars": {
      "YOUR_VARIABLE": "VALUE"
    }
  }
}

  3. Remplacez YOUR_VARIABLE par le nom de votre variable, par exemple executionSetting.

  4. Remplacez VALUE par la valeur de la variable pour ce résultat de compilation qui remplit la condition when définie dans les tables sélectionnées.

L'exemple de code suivant montre la variable executionSetting transmise à une requête de compilation de l'API Dataform :

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Exécuter un résultat de compilation avec des remplacements de compilation

L'exemple de code suivant montre un ID de résultat de compilation transmis dans une requête workflowInvocations.create :

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Créer une configuration de version

Les sections suivantes vous expliquent comment créer une configuration de version dans Dataform pour configurer des modèles de paramètres de compilation que vous pouvez exécuter selon une programmation. Vous pouvez utiliser des configurations de version pour configurer des environnements d'exécution, par exemple, de préproduction et de production.

Pour exécuter des workflows dans BigQuery, Dataform compile le code de workflow SQL dans un résultat de compilation. Ce processus est automatique lorsque vous développez un workflow dans un espace de travail Dataform.

Les configurations de version vous permettent de personnaliser les résultats de compilation. Vous pouvez les utiliser pour créer des environnements d'exécution, par exemple, la préproduction.

Paramètres de configuration des versions

Dans une configuration de version, vous pouvez configurer des remplacements de compilation des paramètres de workflow, définir des variables de compilation et définir la fréquence de création des résultats de compilation.

Une configuration de version Dataform contient les paramètres de compilation suivants :

Paramètres de publication
ID de la version, commitish Git pour les résultats de compilation et fréquence de création des résultats de compilation. La fréquence est un paramètre facultatif. Si elle est définie, la fréquence minimale est d'une heure.
Remplacements de compilation
Remplacements de l'Google Cloud projet, du préfixe de table, du suffixe de schéma et des variables de compilation définis dans les paramètres de workflow.

Fonctionnement d'une configuration de version

Dataform crée des résultats de compilation à partir d'une configuration de version à la fréquence spécifiée ou lorsque vous déclenchez la compilation. La fréquence est un paramètre facultatif. Vous n'êtes pas obligé de la définir pour créer une configuration de version. Si elle est définie, la fréquence minimale est d'une heure. Vous pouvez déclencher manuellement la compilation sur la page Détails de la configuration de la version ou la déclencher avec la méthode releaseConfigs de l'API Dataform.

Lors de la compilation, Dataform extrait le code du commit Git spécifié de votre dépôt. Dataform compile ensuite le code avec les remplacements de compilation appliqués (le cas échéant) et crée le résultat de la compilation. Le dernier résultat de compilation créé pour la configuration de version est le résultat de compilation en direct.

Vous pouvez planifier des exécutions de résultats de compilation à partir de configurations de version dans les configurations de workflow. Vous pouvez également exécuter une configuration de version sélectionnée en dehors de toute planification. Lors de l'exécution d'une configuration de workflow, Dataform exécute le résultat de la compilation en direct à partir de la configuration de version sélectionnée.

Créer une configuration de version

Pour créer une configuration de version Dataform, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. Dans la section Configurations de version, cliquez sur Créer.

  3. Dans le volet Créer une configuration de version, configurez les paramètres de version.

    1. Dans le champ ID de version, saisissez un ID unique pour la configuration de la version.

      Les ID ne peuvent contenir que des chiffres, des lettres, des traits d'union et des traits de soulignement.

    2. Dans le champ Commitish Git, saisissez la branche Git ou le SHA de commit Git pour la version.

      Dans un dépôt Dataform non associé à un dépôt distant, la valeur est toujours main.

    3. Facultatif : Dans le champ Fréquence, sélectionnez la fréquence de création des résultats de compilation.

      Si elle est définie, la fréquence minimale est d'une heure.

      Pour désactiver les publications automatiques, laissez le champ Fréquence vide.

  4. (Facultatif) Dans la section Remplacements de compilation, configurez les paramètres de compilation.

    1. Dans le champ ID du projet Google Cloud, saisissez l'ID du projetGoogle Cloud dans lequel vous souhaitez stocker le résultat de la compilation.
    2. Dans le champ Suffixe du schéma, saisissez un suffixe à ajouter au schéma configuré dans les paramètres du workflow.
    3. Dans le champ Préfixe de table, saisissez un préfixe pour tous les noms de table.

  5. (Facultatif) Dans la section Variables de compilation, définissez les variables de compilation.

    1. Cliquez sur Ajouter une variable.
    2. Dans le champ Clé, saisissez la variable de compilation.
    3. Dans le champ Valeur, saisissez la valeur de la variable de compilation.
    4. Pour ajouter une autre variable de compilation, cliquez sur Ajouter une variable.

  6. Cliquez sur Créer.

Si vous remplacez le projet par défaut, assurez-vous que votre compte de service Dataform a accès au projet défini dans la configuration de la version.

Par exemple, la configuration de version suivante crée un résultat de compilation production à partir de la branche main toutes les heures, sans aucun remplacement de compilation :

  • ID de la version : production
  • Git commitish : main
  • Fréquence : toutes les heures
  • Aucun remplacement de compilation

Afficher les détails d'une configuration de version

Vous pouvez afficher les informations suivantes sur une configuration de version :

  • Paramètres de publication
    • Commitish Git
    • Code temporel du dernier résultat de compilation
    • Planification Cron
    • Remplacements de compilation
    • Variables de compilation
  • Résultat de la compilation en direct
    • Code temporel de création
    • Commitish Git
    • SHA du commit
  • Résultats de compilation précédents

Pour afficher les détails d'une configuration de version, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. Sélectionnez une configuration de version.
  3. Sur la page Détails sur les configurations de versions, examinez les détails de la configuration de la version.

Le tableau Résultats de la compilation programmée affiche les résultats de compilation passés créés automatiquement par la configuration de version.

Le tableau Résultats de compilation manuelle/par API affiche les résultats de compilation créés manuellement ou via des appels à l'API Dataform parmi les 1 000 derniers résultats de compilation du dépôt.

Déclencher manuellement la compilation

Pour créer manuellement un résultat de compilation à partir d'une configuration de version sélectionnée, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. Sélectionnez une configuration de version.
  3. Sur la page Détails de la configuration de version, cliquez sur Nouvelle compilation.

Si vous utilisez l'UI, un résultat nouvellement compilé est automatiquement mis en ligne pour votre configuration de version. Si vous utilisez l'API, vous devez créer un résultat de compilation à partir de la configuration de la version, puis mettre à jour la configuration de la version pour définir le champ releaseCompilationResult avec cette nouvelle valeur.

Les résultats de la compilation manuelle s'affichent dans le tableau Résultats de compilation manuelle/par API de la page Détails de la configuration de la version.

Déclencher l'exécution d'une configuration de version

Pour déclencher l'exécution du résultat de la compilation en direct dans une configuration de version sélectionnée vers BigQuery, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. Dans la section Configurations des versions, cliquez sur Démarrer l'exécution.
  3. Dans le volet Execute manual workflow (Exécuter un workflow manuel), sélectionnez une configuration de version dans la liste Release configuration (Configuration de version).
  4. Sélectionnez les actions de workflow à exécuter :
    1. Pour exécuter l'intégralité du workflow, cliquez sur Toutes les actions.
    2. Pour exécuter les actions sélectionnées dans le workflow, cliquez sur Sélection d'actions, puis sélectionnez les actions.
    3. Pour exécuter des actions avec les tags sélectionnés, cliquez sur Sélection de tags, puis sélectionnez les tags.
  5. Facultatif : Pour exécuter les actions ou les balises sélectionnées et leurs dépendances, sélectionnez l'option Inclure les dépendances.
  6. Facultatif : Pour exécuter les actions ou les balises sélectionnées et leurs dépendances, sélectionnez l'option Inclure les dépendances.

  7. Facultatif : Pour reconstruire toutes les tables à partir de zéro, sélectionnez l'option Exécuter avec actualisation complète.

    Sans cette option, Dataform met à jour les tables incrémentielles sans les reconstruire à partir de zéro.

  8. Cliquez sur Démarrer l'exécution.

Modifier une configuration de version

Pour modifier une configuration de version, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. À côté de la configuration de version que vous souhaitez modifier, cliquez sur le menu Plus, puis sur Modifier.
  3. Dans le volet Modifier la configuration de version, modifiez les paramètres de configuration de la version, puis cliquez sur Enregistrer.

Supprimer une configuration de version

Pour supprimer une configuration de version, procédez comme suit :

  1. Dans votre dépôt, accédez à Releases & Scheduling (Versions et planification).
  2. À côté de la configuration de version que vous souhaitez supprimer, cliquez sur le menu Plus, puis sur Supprimer.
  3. Dans la boîte de dialogue Supprimer la configuration de version, cliquez sur Supprimer.

Étapes suivantes