Réutiliser des variables et des fonctions avec des inclusions dans Dataform

Ce document explique comment créer des instructions JavaScript pour réutiliser du code dans Dataform.

Dans le dossier includes/ de votre dépôt, vous pouvez définir des inclusions JavaScript. Les inclusions sont des constantes ou des fonctions globales que vous pouvez réutiliser dans l'ensemble de votre dépôt.

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 Dataform.

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

Rôles requis

Pour obtenir les autorisations dont vous avez besoin pour réutiliser du code avec JavaScript, demandez à votre administrateur de vous attribuer 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 pour les inclusions dans Dataform

Pour créer un fichier JavaScript dans le répertoire includes/, procédez comme suit:

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

  2. Cliquez sur Créer un fichier.

  3. Dans le volet Create new file (Créer un fichier), procédez comme suit:

    1. Dans le champ Ajouter un chemin d'accès au fichier, après includes/, saisissez le nom du fichier suivi de .js. Par exemple, includes/constants.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.

Créer une constante JavaScript

Pour créer une constante que vous pouvez réutiliser dans votre projet, procédez comme suit:

  1. Accédez à votre espace de travail de développement.

  2. Dans le volet Fichiers, développez includes/.

  3. Créez ou sélectionnez un fichier JavaScript avec l'extension .js.

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

     const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };

    Remplacez les éléments suivants :

    • CONSTANT_NAME: nom de votre constante
    • CONSTANT_VALUE: valeur de votre constante

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant définit la constante PROJECT_ID dans le fichier includes/constants.js:

  // filename is includes/constants.js
  const PROJECT_ID = "my_project_name";
  module.exports = { PROJECT_ID };

L'exemple de code suivant fait référence à la constante PROJECT_ID dans une requête de définition de table dans un fichier SQLX:

  config { type: "table" }
  SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name

L'exemple de code suivant montre la requête de définition de table Dataform Core ci-dessus, compilée en SQL:

  SELECT * FROM my_project_name.my_schema_name.my_table_name

Créer une fonction JavaScript personnalisée

Pour créer une fonction JavaScript personnalisée que vous pouvez réutiliser dans votre projet, procédez comme suit:

  1. Accédez à votre espace de travail de développement.

  2. Dans le volet Fichiers, développez includes/.

  3. Créez ou sélectionnez un fichier JavaScript avec l'extension .js.

  4. Écrivez votre fonction JavaScript personnalisée dans le fichier.

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

     module.exports = { FUNCTION_NAME }

    Remplacez FUNCTION_NAME par le nom de votre fonction.

  6. (Facultatif) Cliquez sur Format.

L'exemple de code suivant montre une fonction JavaScript personnalisée, appelée renderScript, dans le fichier includes/functions.js, qui génère un script SQL:

  function renderScript(table, dimensions, metrics) {
    return `
        select
        ${dimensions.map(field => `${field} as ${field}`).join(",")},
        ${metrics.map(field => `sum(${field}) as ${field}`).join(",\n")}
        from ${table}
        group by ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
      `;
  }

  module.exports = { renderScript };

L'exemple de code suivant illustre l'utilisation de la fonction JavaScript renderScript personnalisée dans une requête de définition de table Dataform:

  config {
      type: "table",
      tags: ["advanced", "hourly"],
      disabled: true
  }

  ${functions.renderScript(ref("source_table"),
                                ["country", "device_type"],
                                ["revenue", "pageviews", "sessions"]
                                )}

L'exemple de code suivant montre la requête de définition de table Dataform ci-dessus, compilée en SQL:

  select
    country as country,
    device_type as device_type,
    sum(revenue) as revenue,
    sum(pageviews) as pageviews,
    sum(sessions) as sessions

  from "dataform"."source_table"

  group by 1, 2

Référencer une inclusion dans un fichier SQLX

Vous pouvez référencer n'importe quelle fonction ou constante d'inclusion dans un fichier SQLX. La syntaxe de référencement des inclusions dépend de l'emplacement du fichier d'inclusion. Un fichier d'inclusion de premier niveau se trouve directement dans le répertoire includes/. Un fichier d'inclusion imbriqué se trouve dans un sous-répertoire de includes/.

Référencer une inclusion de niveau supérieur dans un fichier SQLX

  • Pour référencer une fonction d'inclusion ou une constante de niveau supérieur dans une requête de base Dataform, saisissez le nom du fichier de définition d'inclusion sans l'extension .js, suivie du nom de l'objet exporté.

L'exemple de code suivant fait référence à la constante firstDate, définie dans le fichier includes/constants.js, dans un fichier SQLX de définition de table:

  config {type: "table"}
  select * from source_table where date > ${constants.firstDate}

Référencer une inclusion imbriquée dans un fichier SQLX

Pour référencer des inclusions situées dans les sous-répertoires de definitions, importez les inclusions à l'aide de la fonction JavaScript require et d'un bloc js {}.

Pour référencer une inclusion imbriquée avec la fonction JavaScript require, procédez comme suit:

  1. Accédez à votre espace de travail de développement.

  2. Dans le volet Fichiers, développez definitions/.

  3. Sélectionnez un fichier SQLX.

  4. Dans le bloc config, saisissez l'extrait de code suivant:

     js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }

    Remplacez les éléments suivants :

    • VARIABLE_NAME: nom de la constante ou de la fonction que vous souhaitez importer
    • SUBDIRECTORY_INCLUDE: chemin d'accès au fichier includes imbriqué

  5. (Facultatif) Cliquez sur Format.

L'exemple de code suivant fait référence à la constante firstDate, définie dans le fichier includes/allConstants/constants.js imbriqué, dans un fichier SQLX de définition de table:

  config {type: "table"}
  js {
    var { firstDate } = require("includes/allConstants/constants");
  }
  select * from source_table where date > ${firstDate}

Utiliser une fonction d'inclusion JavaScript avec la fonction ref de base de Dataform

Pour utiliser une fonction d'inclusion JavaScript avec la fonction principale ref de Dataform, vous devez transmettre ref en tant qu'argument de la fonction d'inclusion JavaScript dans un fichier SQLX.

L'exemple de code suivant montre le fichier includes/script_builder.js avec la fonction JavaScript renderScript qui agrège les métriques à l'aide de SUM, puis les regroupe par dimension:

function renderScript(table, dimensions, metrics) {
  return `
      SELECT
      ${dimensions.map((field) => `${field} AS ${field}`).join(",\\n")},
      ${metrics.map((field) => `SUM(${field}) AS ${field}`).join(",\\n")}
      FROM ${table}
      GROUP BY ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
    `;
}
module.exports = { renderScript };

L'exemple de code suivant montre la fonction JavaScript renderScript utilisée dans le fichier definitions/stats_per_country_and_device.sqlx avec la fonction ref de base Dataform transmise en tant qu'argument:

${script_builder.renderScript(
  ref("source_table"),
  ["country", "device_type"],
  ["revenue", "pageviews", "sessions"])}

L'exemple de code suivant montre la requête definitions/stats_per_country_and_device.sqlx compilée en SQL:

SELECT country AS country,
       device_type AS device_type,
       SUM(revenue) AS revenue,
       SUM(pageviews) AS pageviews,
       SUM(sessions) AS sessions
FROM my_schema.source_table
GROUP BY 1, 2

Pour en savoir plus sur la fonction ref principale de Dataform, consultez la page Présentation de Dataform Core.

Étapes suivantes