Cette page a été traduite par l'API Cloud Translation.

Créer des workflows Dataform SQL avec JavaScript

Ce document explique comment utiliser JavaScript pour créer des éléments de workflow SQL dans Dataform Vous pouvez utiliser JavaScript plutôt que Dataform Core. afin de créer des éléments similaires de façon répétée dans votre flux de travail.

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

Dataform Core permet vous pouvez créer des actions de workflow SQL avec SQLX et JavaScript. Avec JavaScript, vous pouvez créer des actions similaires à plusieurs reprises dans votre flux de travail. Par exemple : vous pouvez créer une vue de 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 où la valeur du champ user_id ne correspond pas à l'une des valeurs du champ 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 ne contenant 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 le code JavaScript ES5 arbitraire, tels que sous forme de boucles et de constantes.

Vous pouvez définir les actions suivantes avec JavaScript dans Dataform:

Tables
Déclarations de sources de données
Assertions
Opérations SQL personnalisées

Avant de commencer

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

Accéder à Dataform
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.

Rôles requis

Pour obtenir les autorisations nécessaires pour développer un workflow SQL avec JavaScript, demandez à votre administrateur de vous accorder le Rôle IAM Éditeur Dataform (roles/dataform.editor) sur 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 definitions/ , procédez comme suit:

Dans le volet Fichiers, à côté de definitions/, cliquez sur Menu Plus.
Cliquez sur Créer un fichier.
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 des propriétés d'objet de workflow SQL Dataform avec JavaScript

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

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

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

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

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

Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
Sélectionnez un fichier JavaScript.

Dans le fichier, ajoutez les propriétés du tableau à la méthode publish(). au format suivant:

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

(Facultatif) Cliquez sur Format.

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

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

Inclusions de référence dans un fichier JavaScript

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

La syntaxe de référencement inclut à l'intérieur d'un fichier JavaScript dépend de la Emplacement du fichier d'inclusion. Dataform stocke ces fichiers inclut un répertoire.

Inclusions de premier niveau de référence

Pour référencer un fichier d'inclusion de premier niveau, indiquez le nom de fichier lorsque de déclarer vos variables.

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

  const {serviceName, serviceId} = service;

Inclusions imbriquées de référence

Pour référencer un fichier d'inclusion imbriquée, saisissez son nom dans le code JavaScript ont besoin d'une fonction.

L'exemple de code suivant fait référence à 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 des requêtes, telles que ref et self. Pour en savoir plus sur Fonctions intégrées 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:

Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
Sélectionnez un fichier JavaScript.
Dans le fichier, saisissez une méthode Dataform JavaScript globale.
Dans la méthode, saisissez un argument ctx contextuel.
Facultatif: Si vous utilisez des chaînes de modèle JavaScript, encapsulez la macro argument contextualisé dans des accents graves ``.
Dans l'argument contextuel, saisissez la fonction de requête avec son paramètre en tant que un objet de contexte.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre la fonction de requête ref encapsulée dans une Argument contextuel de la méthode publish:

  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 "déclarer", consultez la documentation de référence sur Dataform. Pour plus sur les sources de données dans Dataform, consultez Déclarez une source de données.

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

Dans le volet Files (Fichiers) de votre espace de travail de développement, développezdefinitions/.
Sélectionnez un fichier JavaScript.
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: l'ID du projet auquel contient la source de données.
- BIGQUERY_SCHEMA: ensemble de données BigQuery dans lequel relation externe existe
- RELATION_NAME: nom de la relation que vous pouvez utiliser ultérieurement pour référencer la source de données dans Dataform
Pour déclarer une autre source de données dans le même fichier, ajoutez un declare supplémentaire au fichier.
(Facultatif) Cliquez sur Format.

Définir une table avec JavaScript

Vous pouvez créer une table avec le publish JavaScript Dataform . Pour en savoir plus sur la méthode "publish", consultez 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 Créez une table.

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

Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
Sélectionnez un fichier JavaScript.
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. Remplacer SELECT_QUERY par une instruction SQL SELECT définir le tableau.
Pour définir le type de table, ajouter des dépendances de table et une description de la table, Définissez les propriétés des objets de la méthode publish.
Pour définir une autre table dans le même fichier, répétez les étapes 3 et 4.
(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 propriété Méthode JavaScript d'assertion Dataform. Pour en savoir plus sur les assert, consultez la documentation de référence sur 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 fichier JavaScript.

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

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

Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
Sélectionnez un fichier JavaScript.
Dans le fichier, saisissez l'extrait de code suivant :
```
 assert("ASSERTION_NAME").query(ctx => "CUSTOM_ASSERTION_QUERY");
```
1. Remplacez ASSERTION_NAME par le nom de votre une assertion.
2. Remplacez CUSTOM_ASSERTION_QUERY par votre code SQL. d'assertion.
Pour créer une autre assertion dans le même fichier, répétez l'étape 3.
(Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une assertion JavaScript qui affirme qu'aucun la valeur dans source_table 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 propriété Dataform utilise la méthode JavaScript. Pour en savoir plus sur des opérations SQL personnalisées dans Dataform, consultez Ajoutez des opérations SQL personnalisées.

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

Dans le volet Fichiers de votre espace de travail de développement, développez definitions/.
Sélectionnez un fichier JavaScript.
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'élément personnalisé. opération.
2. Remplacez CUSTOM_SQL_QUERY par votre requête SQL personnalisée.
Pour définir une autre opération SQL personnalisée dans le même fichier, répétez l'étape 3.
(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 ligne dans some_table et définit test_column de la nouvelle ligne vers 2:

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

Étape suivante

Pour en savoir plus sur les méthodes JavaScript Dataform et les fonctionnalités intégrées de requête, consultez les Documentation de référence sur Dataform
Pour en savoir plus sur le développement dans Dataform avec JavaScript, consultez Présentation de JavaScript dans Dataform