Créer des workflows SQL Dataform avec JavaScript

Ce document explique comment utiliser JavaScript pour créer des éléments de workflow SQL dans Dataform. Vous pouvez utiliser JavaScript sur Dataform Core pour créer des éléments similaires de manière répétée dans votre workflow.

À propos du développement de workflows dans Dataform avec JavaScript

Dataform Core vous permet de créer des actions de workflow SQL avec SQLX et JavaScript. JavaScript vous permet de créer des actions similaires de manière répétée dans votre workflow. Par exemple, vous pouvez créer une vue pour chaque table de votre workflow en supprimant certains ID utilisateur.

L'exemple de code JavaScript suivant vous permet de créer une vue de chaque table dans laquelle la valeur du champ user_id ne correspond pas à l'une des valeurs de la liste blocked_user_ids:

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

Cet exemple de code crée trois vues nommées user_events_blocked_removed, user_settings_blocked_removed et user_logs_blocked_removed, qui ne contiennent aucun des ID utilisateur bloqués.

Vous pouvez créer plusieurs actions dans un même fichier JavaScript avec les méthodes globales Dataform et du code JavaScript ES5 arbitraire, comme des boucles et des constantes.

Vous pouvez définir les actions suivantes avec JavaScript 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.

Rôles requis

Pour obtenir les autorisations dont vous avez besoin pour développer un workflow SQL avec JavaScript, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de données (roles/dataform.editor) pour les espaces de travail. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

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

Créer un fichier JavaScript dans Dataform

Stockez les fichiers JavaScript pour les définitions et les déclarations de source de données dans le répertoire definitions/. Pour créer un fichier JavaScript dans le répertoire definitions/, procédez comme suit:

  1. Dans le volet Fichiers, à côté de definitions/, cliquez sur le menu Plus.

  2. Cliquez sur Créer un fichier.

  3. Dans le volet Créer un fichier, procédez comme suit:

    1. Dans le champ Ajouter un chemin d'accès au fichier, après definitions/, saisissez le nom du fichier suivi de .js. Par exemple, definitions/definitions.js.

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

    2. Cliquez sur Créer un fichier.

Définir les propriétés des objets de workflow SQL Dataform avec JavaScript

Vous pouvez utiliser les méthodes globales suivantes de Dataform pour créer des objets de workflow SQL avec Dataform:

  • declare : permet de déclarer une source de données.
  • publish. Permet de définir une table.
  • assert. Utilisé pour créer une assertion.
  • operate. Utilisé pour définir une opération SQL personnalisée.

Chacune des méthodes globales contient des propriétés que vous pouvez utiliser pour configurer l'objet créé. Pour en savoir plus sur les méthodes globales et leurs propriétés, consultez la documentation de référence de Dataform.

Dans la méthode publish() qui crée une table, vous pouvez définir les propriétés de la table en les transmettant comme deuxième argument de la méthode.

Pour transmettre les propriétés de la table en tant que deuxième argument de publish(), procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Files (Fichiers), développez definitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, ajoutez des propriétés de table à la méthode publish() au format suivant:

     method("first_method_argument", {
   property1: "property1_value",
   property2: "property2_value",
   property3: "property3_value",
 });

  4. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre comment définir les propriétés de la méthode publish() en les transmettant en tant que deuxième argument de la méthode:

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

Références incluses dans un fichier JavaScript

Vous pouvez référencer n'importe quelle fonction, macro ou constante d'inclusion dans un fichier JavaScript. Pour en savoir plus sur les inclusions dans Dataform, consultez la page Réutiliser des variables et des fonctions avec des inclusions JavaScript.

La syntaxe utilisée pour référencer les inclusions dans un fichier JavaScript dépend de l'emplacement du fichier. Dataform stocke ces fichiers dans le répertoire "include".

Inclusions de niveau supérieur de la documentation de référence

  • Pour référencer un fichier d'inclusion de niveau supérieur, référencez le nom de fichier lorsque vous déclarez vos variables.

L'exemple de code suivant référence les variables serviceName et serviceId du fichier includes/service.js:

  const {serviceName, serviceId} = service;

Inclure des références imbriquées

Pour référencer un fichier d'inclusion imbriqué, saisissez le nom du fichier dans la fonction require de JavaScript.

L'exemple de code suivant référence les variables serviceName et serviceId du fichier includes/allServices/service.js:

  const {serviceName, serviceId} = require("includes/allServices/service.js");

Utiliser les fonctions de requête Dataform dans les méthodes JavaScript

Dataform fournit un certain nombre de fonctions intégrées que vous pouvez utiliser dans les requêtes, telles que ref et self. Pour en savoir plus sur les fonctions intégrées de Dataform, consultez la documentation de référence de l'API Dataform.

Pour utiliser une fonction de requête intégrée dans une méthode JavaScript, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Files (Fichiers), développez definitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, saisissez une méthode JavaScript Dataform globale.

  4. Dans la méthode, saisissez un argument ctx contextuel.

  5. Facultatif: Si vous utilisez des chaînes de modèle JavaScript, encapsulez l'argument contextuel entre des accents graves (``).

  6. Dans l'argument contextuel, saisissez la fonction de requête avec son paramètre en tant qu'objet de contexte.

  7. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre la fonction de requête ref encapsulée dans un argument contextuel de la méthode de publication:

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

Déclarer une source de données de workflow SQL avec JavaScript

Vous pouvez déclarer plusieurs sources de données dans un même fichier de déclaration JavaScript avec la méthode de déclaration JavaScript Dataform. Pour en savoir plus sur la méthode de déclaration, consultez la documentation de référence de Dataform. Pour en savoir plus sur les sources de données dans Dataform, consultez la page Déclarer une source de données.

Pour déclarer une source de données dans un fichier JavaScript, procédez comme suit:

  1. Dans le volet Files (Fichiers) de votre espace de travail de développement, développez les définitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, saisissez l'extrait de code suivant :

     declare({
   database: "DATABASE_PROJECT_ID",
   schema: "BIGQUERY_SCHEMA",
   name: "RELATION_NAME",
 });

    Remplacez les éléments suivants :

    • DATABASE_PROJECT_ID: ID du projet qui contient la source de données
    • BIGQUERY_SCHEMA: ensemble de données BigQuery dans lequel existe la relation externe
    • RELATION_NAME: nom de la relation que vous pouvez utiliser ultérieurement pour référencer la source de données dans Dataform.

  4. Pour déclarer une autre source de données dans le même fichier, ajoutez un bloc declare supplémentaire au fichier.

  5. (Facultatif) Cliquez sur Format.

Définir une table avec JavaScript

Vous pouvez créer une table avec la méthode publish JavaScript Dataform. Pour en savoir plus sur la méthode de publication, consultez la documentation de référence sur Dataform.

Vous pouvez définir les types de tables suivants: table, table incrémentielle et vue. Pour en savoir plus sur la définition de tables dans Dataform, consultez la page Créer une table.

Pour définir une table dans un fichier JavaScript, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Files (Fichiers), développez definitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, saisissez l'extrait de code suivant :

     publish("TABLE_NAME").query(ctx => "SELECT_QUERY");

    1. Remplacez TABLE_NAME par le nom de la table.

    2. Remplacez SELECT_QUERY par une instruction SQL SELECT définissant la table.

  4. Pour définir le type de table, ajouter des dépendances de table et ajouter une description de la table, définissez les propriétés de l'objet de la méthode publish.

  5. Pour définir une autre table dans le même fichier, répétez les étapes 3 et 4.

  6. (Facultatif) Cliquez sur Format.

Définir des assertions Dataform manuelles avec JavaScript

Vous pouvez créer des assertions SQL manuelles dans un fichier JavaScript à l'aide de la méthode JavaScript d'assertion Dataform. Pour en savoir plus sur la méthode assert, consultez la documentation de référence de Dataform.

Une requête SQL d'assertion manuelle ne doit renvoyer aucune ligne. Si la requête renvoie des lignes lorsqu'elle est exécutée, l'assertion échoue. Vous pouvez créer plusieurs assertions dans un même fichier JavaScript.

Pour en savoir plus sur les assertions dans Dataform, consultez la page Tester des tables avec des assertions.

Pour créer une assertion manuelle dans un fichier JavaScript, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Files (Fichiers), développez definitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, saisissez l'extrait de code suivant :

     assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");

    1. Remplacez ASSERTION_NAME par le nom de votre assertion personnalisée.

    2. Remplacez CUSTOM_ASSERTION_QUERY par votre requête d'assertion SQL.

  4. Pour créer une autre assertion dans le même fichier, répétez l'étape 3.

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une assertion JavaScript qui affirme qu'aucune valeur dans source_table n'est NULL:

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

Définir des opérations SQL personnalisées avec JavaScript

Vous pouvez définir des opérations SQL personnalisées dans un fichier JavaScript à l'aide de la méthode JavaScript Dataform. Pour en savoir plus sur les opérations SQL personnalisées dans Dataform, consultez la page Ajouter des opérations SQL personnalisées.

Pour définir une opération SQL personnalisée avec JavaScript, procédez comme suit:

  1. Dans votre espace de travail de développement, dans le volet Files (Fichiers), développez definitions/.

  2. Sélectionnez un fichier JavaScript.

  3. Dans le fichier, saisissez l'extrait de code suivant :

     operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");

    1. Remplacez OPERATION_NAME par le nom de l'opération personnalisée.

    2. Remplacez CUSTOM_SQL_QUERY par votre requête SQL personnalisée.

  4. Pour définir une autre opération SQL personnalisée dans le même fichier, répétez l'étape 3.

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une opération SQL personnalisée dans un fichier JavaScript qui insère une seule nouvelle ligne dans some_table et définit test_column de la nouvelle ligne sur 2:

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

Étapes suivantes