Configurer les paramètres du workflow Dataform

Cette page explique comment modifier les paramètres de traitement du workflow SQL Dataform pour un dépôt spécifique.

Vous pouvez modifier le fichier de paramètres pour renommer les schémas ou ajouter des variables de compilation personnalisées à votre dépôt.

À propos des paramètres du dépôt

Chaque dépôt Dataform contient un fichier de paramètres de workflow unique. Le fichier contient l'ID du projet Google Cloud et le schéma dans lequel Dataform publie des composants dans BigQuery. Dataform utilise des paramètres par défaut que vous pouvez remplacer pour mieux répondre à vos besoins en modifiant le fichier de paramètres.

À partir de Dataform Core 3.0.0, les paramètres de workflow sont stockés dans le fichier workflow_settings.yaml par défaut. Dans les versions antérieures du noyau Dataform, les paramètres de workflow sont stockés dans le fichier dataform.json. Le fichier workflow_settings.yaml du noyau Dataform 3.0 est rétrocompatible avec dataform.json. Vous pouvez continuer à utiliser dataform.json pour stocker les paramètres de workflow. Nous vous recommandons de migrer les paramètres de votre workflow de dépôt vers le format workflow_settings.yaml pour assurer la compatibilité à l'avenir.

À propos de workflow_settings.yaml

Le fichier workflow_settings.yaml, introduit dans Dataform Core 3.0, stocke les paramètres de workflow Dataform au format YAML.

L'exemple de code suivant montre un exemple de fichier workflow_settings.yaml:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

Dans l'exemple de code précédent, les paires clé-valeur sont décrites comme suit:

  • defaultProject: ID de votre projet Google Cloud BigQuery.
  • defaultDataset: ensemble de données BigQuery dans lequel Dataform crée des éléments, appelé dataform par défaut.
  • defaultLocation: région de votre ensemble de données BigQuery par défaut. Pour en savoir plus sur les emplacements des ensembles de données BigQuery, consultez la section Emplacements des ensembles de données. À cet emplacement, Dataform traite votre code et stocke les données exécutées. Cette région de traitement doit correspondre à l'emplacement de vos ensembles de données BigQuery, mais pas nécessairement à la région du dépôt Dataform.
  • defaultAssertionDataset: ensemble de données BigQuery dans lequel Dataform crée des vues avec des résultats d'assertion, appelé dataform_assertions par défaut.

Pour en savoir plus sur les propriétés workflow_settings.yaml, consultez la documentation de référence sur les configurations pour les paramètres de workflow sur GitHub.

Vous pouvez accéder aux propriétés définies dans workflow_settings.yaml dans votre code Dataform en tant que propriétés de l'objet dataform.projectConfig.

Les mappages suivants des options workflow_settings.yaml aux options dataform.projectConfig accessibles au code s'appliquent:

  • defaultProject => defaultDatabase.
  • defaultDataset => defaultSchema.
  • defaultAssertionDataset => assertionSchema.
  • projectSuffix => databaseSuffix.
  • datasetSuffix => schemaSuffix.
  • namePrefix => tablePrefix.

L'exemple de code suivant montre l'objet dataform.projectConfig référencé dans une instruction SELECT dans une vue:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

À propos de dataform.json

Le fichier dataform.json stocke les paramètres de workflow Dataform au format JSON.

L'exemple de code suivant montre un exemple de fichier dataform.json:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

Dans l'exemple de code précédent, les paires clé-valeur sont décrites comme suit:

  • warehouse: pointeur vers BigQuery, où Dataform crée des éléments.
  • defaultDatabase: ID de votre projet Google Cloud BigQuery.
  • defaultSchema: ensemble de données BigQuery dans lequel Dataform crée des éléments.
  • defaultLocation: région de votre ensemble de données BigQuery par défaut. Pour en savoir plus sur les emplacements des ensembles de données BigQuery, consultez la page Emplacements des ensembles de données. À cet emplacement, Dataform traite votre code et stocke les données exécutées. Cette région de traitement doit correspondre à l'emplacement de vos ensembles de données BigQuery, mais pas nécessairement à la région du dépôt Dataform.
  • assertionSchema: ensemble de données BigQuery dans lequel Dataform crée des vues avec des résultats d'assertion, appelé dataform_assertions par défaut.

Vous pouvez accéder aux propriétés définies dans dataform.json dans le code de votre projet en tant que propriétés de l'objet dataform.projectConfig.

Avant de commencer

  1. Créez un dépôt.

  2. Créez et initialisez un espace de travail de développement dans votre dépôt.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer les paramètres Dataform, 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 via des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer les noms de schéma

Pour configurer les noms de schéma, vous devez modifier les propriétés defaultDataset et defaultAssertionSchema dans le fichier workflow_settings.yaml, ou les propriétés defaultSchema et assertionSchema dans le fichier dataform.json.

Pour configurer le nom d'un schéma, procédez comme suit:

workflow_settings.yaml

  1. Dans votre espace de travail de développement, dans le volet Fichiers, cliquez sur le fichier workflow_settings.yaml.

  2. Modifiez la valeur de defaultDataset, defaultAssertionSchema ou les deux.

L'exemple de code suivant montre un nom defaultDataset personnalisé défini dans le fichier workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. Dans votre espace de travail de développement, dans le volet Fichiers, cliquez sur le fichier dataform.json.

  2. Modifiez la valeur de defaultSchema, assertionSchema ou les deux.

L'exemple de code suivant montre un nom defaultSchema personnalisé défini dans le fichier dataform.json:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Créer des variables de compilation personnalisées

Les variables de compilation contiennent des valeurs que vous pouvez modifier à l'aide de forçages de compilation dans une configuration de version ou dans une requête d'API Dataform.

Une fois que vous avez défini une variable de compilation dans workflow_settings.yaml et l'avez ajoutée à des tables sélectionnées, vous pouvez modifier sa valeur dans une configuration de version ou des remplacements de compilation de l'API Dataform pour exécuter des tables de manière conditionnelle.

Pour en savoir plus sur l'exécution conditionnelle de tables à l'aide de variables de compilation, consultez la section Présentation du cycle de vie du code dans Dataform.

Pour créer une variable de compilation que vous pouvez utiliser dans un dépôt, procédez comme suit:

workflow_settings.yaml

  1. Accédez à votre espace de travail de développement Dataform.
  2. Dans le volet Fichiers, sélectionnez le fichier workflow_settings.yaml.

  3. Saisissez l'extrait de code suivant:

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

    Remplacez les éléments suivants :

    • YOUR_VARIABLE par le nom de la variable.
    • VALUE avec la valeur par défaut de la variable de compilation.

L'exemple de code suivant montre la variable de compilation myVariableName définie sur myVariableValue dans le fichier workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

L'exemple de code suivant montre le fichier workflow_settings.yaml avec la variable de compilation executionSetting définie sur dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Accédez à votre espace de travail de développement Dataform.
  2. Dans le volet Fichiers, sélectionnez le fichier dataform.json.

  3. Saisissez l'extrait de code suivant:

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

    Remplacez les éléments suivants :

    • YOUR_VARIABLE par le nom de la variable.
    • VALUE avec la valeur par défaut de la variable de compilation.

L'exemple de code suivant montre la variable de compilation myVariableName définie sur myVariableValue dans le fichier dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

L'exemple de code suivant montre le fichier dataform.json avec la variable de compilation executionSetting définie sur dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Ajouter une variable de compilation à un tableau

Pour ajouter une variable de compilation à un fichier de définition de table SQLX, procédez comme suit:

  1. Accédez à votre espace de travail de développement Dataform.
  2. Dans le volet Fichiers, sélectionnez un fichier de définition de table SQLX.

  3. Dans le fichier, saisissez une clause when au format suivant:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Remplacez les éléments suivants :

    • YOUR_VARIABLE par le nom de votre variable, par exemple executionSetting.
    • SET_VALUE avec une valeur pour la variable, par exemple staging.
    • CONDITION avec une condition d'exécution de la table.

L'exemple de code suivant montre un fichier SQLX de définition de table avec une clause when et la variable executionSetting qui exécute 10% des données dans le paramètre d'exécution de préproduction:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

L'exemple de code suivant montre un fichier SQLX de définition de vue avec une clause when et la variable myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Migrer les paramètres de workflow vers workflow_settings.yaml

Pour vous assurer que votre fichier de paramètres de workflow est compatible avec les futures versions du framework de base Dataform, vous devez migrer vos paramètres de workflow du fichier dataform.json vers le fichier workflow_settings.yaml.

Le fichier workflow_settings.yaml remplace le fichier dataform.json.

Si le noyau Dataform est le seul package de dépendance de votre dépôt, le fichier workflow_settings.yaml remplace également le fichier package.json. Pour en savoir plus sur le remplacement de package.json par workflow_settings.yaml, consultez la section Gérer le package principal Dataform.

Le tableau suivant présente le mappage des propriétés des paramètres de workflow de dataform.json à workflow_settings.yaml:

Propriété à dataform.json Propriété à workflow_settings.yaml Description
assertionSchema defaultAssertionDataset Obligatoire. Ensemble de données par défaut pour les assertions.
defaultDatabase defaultProject Obligatoire. Nom du projet Google Cloud par défaut.
defaultLocation defaultLocation Obligatoire. Emplacement BigQuery par défaut dans lequel Dataform créera des tables. Pour en savoir plus sur les emplacements BigQuery, consultez la page Emplacements des ensembles de données.
defaultSchema defaultDataset Obligatoire. Ensemble de données par défaut.
databaseSuffix projectSuffix Facultatif. Suffixe à ajouter à toutes les références de projet Google Cloud .
schemaSuffix datasetSuffix Facultatif. Suffixe à ajouter à tous les ensembles de données d'action.
tablePrefix namePrefix Facultatif. Préfixe à ajouter à tous les noms d'action.
vars vars Facultatif. Variables définies par l'utilisateur qui sont mises à la disposition du code du projet lors de la compilation. Objet contenant une liste de paires key: value.
warehouse - Obligatoire dans dataform.json. Doit être défini sur bigquery. Non disponible dans workflow_settings.yaml.
- dataformCoreVersion Non disponible dans dataform.json. Installé dans workflow_settings.yaml par défaut pour les nouveaux dépôts. Pour en savoir plus, consultez Gérer le package principal Dataform.

Pour migrer les paramètres de workflow vers workflow_settings.yaml, procédez comme suit:

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

    Accéder à la page Dataform

  2. Sélectionnez un dépôt, puis un espace de travail.

  3. Dans le volet Fichiers, cliquez sur AjouterAjouter, puis sur Créer un fichier.

  4. Dans le champ Ajouter un chemin d'accès au fichier, saisissez workflow_settings.yaml.

  5. Cliquez sur Créer un fichier.

  6. Dans le fichier workflow_settings.yaml, ajoutez les paramètres de votre fichier dataform.json, mappés au format YAML.

  7. Dans le volet Fichiers, cliquez sur le menu Plus à côté de dataform.json, puis sur Supprimer.

  8. Pour confirmer la suppression de dataform.json, cliquez sur Supprimer.

L'exemple de code suivant montre les paramètres de workflow définis dans un fichier dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

L'exemple de code suivant montre le fichier dataform.json précédent converti en workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

Étape suivante