Le noyau Dataform vous permet de créer des actions de workflow avec SQLX et JavaScript. Bien que facultatif, utilisez JavaScript avec SQLX pour créer des éléments similaires à plusieurs reprises dans votre workflow. Par exemple, avec JavaScript, vous pouvez créer une vue de chaque table de votre workflow en supprimant certains ID utilisateur. Vous pouvez également développer des actions de workflow exclusivement avec JavaScript.
Avant de commencer
Dans la console Google Cloud, accédez à la page Dataform page.
Sélectionnez ou créez un dépôt.
Sélectionnez ou créez un espace de travail de développement.
De plus, vous devez connaître la syntaxe JavaScript et les concepts JavaScript suivants:
- Variables
- Tableaux
- Instructions conditionnelles
- Boucles For
- Maps
- Fonctions
- Objets
- Exporter et importer des modules
Rôles requis
Pour obtenir les autorisations nécessaires pour développer un workflow avec JavaScript et réutiliser du code avec des inclusions 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 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.
Ajouter du code JavaScript à un fichier SQLX
Vous pouvez ajouter du code JavaScript à un fichier SQLX de deux manières : en ligne ou dans un bloc JavaScript.
Vous pouvez utiliser un bloc JavaScript pour définir des fonctions ou des constantes dans un fichier SQLX. Vous pouvez utiliser du code JavaScript intégré pour modifier dynamiquement une requête SQLX ou SQL.
L'exemple de code suivant montre la fonction JavaScript intégrée au cœur de Dataform self ajoutée en ligne au bloc post_operations dans un fichier SQLX:
config {type: "table"}
SELECT * FROM ...
post_operations {
GRANT `roles/bigquery.dataViewer`
ON
TABLE ${self()}
TO "group:allusers@example.com", "user:otheruser@example.com"
}
L'exemple de code suivant montre une constante définie dans un bloc JavaScript et utilisée en ligne dans une requête dans un fichier SQLX:
js {
const columnName = "foo";
}
SELECT 1 AS ${columnName} FROM "..."
Réutiliser du code dans un seul fichier SQLX avec l'encapsulation JavaScript
Vous pouvez réutiliser le code JavaScript pour simplifier le développement dans Dataform. Pour réutiliser des constantes et des fonctions JavaScript dans un seul fichier SQLX, vous pouvez les encapsuler dans un bloc JavaScript. Pour réutiliser du code JavaScript dans un seul dépôt Dataform, vous pouvez créer des inclusions. Pour réutiliser du code JavaScript dans plusieurs dépôts Dataform, vous pouvez créer ou importer un package.
Pour créer des parties répétitives de code SQL que vous pouvez réutiliser dans un seul fichier SQLX, vous pouvez encapsuler des fonctions et des constantes dans un bloc JavaScript. Vous ne pouvez réutiliser le code défini dans un bloc JavaScript que dans le fichier SQLX dans lequel le bloc est défini. Pour en savoir plus, consultez la page Dataform Core.
L'exemple de code suivant montre une constante et une fonction définies dans un bloc JavaScript et utilisées en ligne dans une requête dans un fichier SQLX:
js {
const foo = 1;
function bar(number){
return number+1;
}
}
select
${foo} as one,
${bar(foo)} as two
Réutiliser du code dans un seul dépôt avec des inclusions
Les inclusions sont des constantes ou des fonctions JavaScript globales pour votre dépôt.
Vous définissez les inclusions dans le répertoire includes de votre dépôt. Vous pouvez ensuite les réutiliser dans votre dépôt dans des fichiers JavaScript et SQLX.
L'exemple de code suivant montre la définition de la constante launch_date dans le fichier includes/constants.js:
// filename is includes/constants.js
const launch_date = "11.11.2011";
module.exports = { launch_date };
L'exemple de code suivant montre la constante launch_date référencée dans une requête de définition de table dans un fichier SQLX:
config {type: "table"}
SELECT * FROM source_table WHERE date > ${constants.launch_date}
Créer un fichier JavaScript pour les inclusions
Pour créer un fichier JavaScript dans le répertoire includes/, procédez comme suit:
Dans le volet Fichiers, à côté de
includes/, cliquez sur Plus.Cliquez sur Créer un fichier.
Dans le volet Créer un fichier, procédez comme suit :
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.
Cliquez sur Créer un fichier.
Créer une constante JavaScript
Pour créer une constante que vous pouvez réutiliser dans l'ensemble de votre projet, procédez comme suit:
Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez
includes/.Créez ou sélectionnez un fichier JavaScript portant l'extension
.js.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
(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 de base Dataform précédente 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:
Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez
includes/.Créez ou sélectionnez un fichier JavaScript portant l'extension
.js.Dans le fichier, écrivez votre fonction JavaScript personnalisée.
Dans le fichier, saisissez l'extrait de code suivant :
module.exports = { FUNCTION_NAME }Remplacez
FUNCTION_NAMEpar le nom de votre fonction.Facultatif: cliquez sur Format.
L'exemple de code suivant montre une fonction JavaScript personnalisée appelée renderScript et stockée dans le fichier includes/functions.js. La fonction 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 montre comment utiliser la fonction JavaScript renderScript personnalisée dans une requête de définition de table de base 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 de base Dataform précédente 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 faire référence à n'importe quelle fonction ou constante d'inclusion dans un fichier SQLX. La syntaxe des références aux 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 premier niveau dans un fichier SQLX
- Pour faire référence à une fonction ou une constante d'inclusion de niveau supérieur dans une requête de base Dataform, saisissez le nom de fichier de la définition d'inclusion sans l'extension
.js, suivi 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 des sous-répertoires de definitions, importez des 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:
Accédez à votre espace de travail de développement.
Dans le volet Fichiers, développez
definitions/.Sélectionnez un fichier SQLX.
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 du fichier
includesimbriqué
(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 ref de base 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 et 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 du noyau 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 du noyau Dataform, consultez la section Noyau Dataform.
Réutiliser du code dans plusieurs dépôts avec des packages
Les packages sont des collections de code JavaScript que vous pouvez importer et utiliser dans plusieurs dépôts Dataform pour simplifier le développement de workflow.
Vous pouvez créer votre propre package personnalisé dans Dataform ou utiliser l'un des packages Dataform Open Source, disponibles sur la page Dataform Open Source GitHub.
Pour voir un exemple d'utilisation d'un package Open Source dans Dataform, consultez Utiliser des dimensions à évolution lente dans Dataform.
Pour pouvoir utiliser le contenu d'un package dans Dataform, vous devez l'installer dans votre dépôt Dataform, puis l'importer dans le fichier JavaScript ou SQLX individuel dans lequel vous souhaitez l'utiliser. Pour en savoir plus, consultez Installer un package.
Pour pouvoir installer un package NPM privé dans un dépôt Dataform, vous devez authentifier le package.
Créer des workflows exclusivement avec JavaScript
Cette section explique comment utiliser JavaScript pour créer des actions de workflow dans Dataform. Vous pouvez utiliser JavaScript au lieu du noyau Dataform pour créer des éléments similaires à plusieurs reprises dans votre workflow.
Au lieu de développer des workflows en SQLX ou en SQLX combiné à JavaScript, vous pouvez créer des actions de workflow dans des fichiers .js en utilisant uniquement JavaScript. Vous pouvez créer plusieurs actions de workflow dans un même fichier JavaScript avec des méthodes globales Dataform et du code JavaScript ES5 arbitraire, comme des boucles et des constantes. Chacune des méthodes JavaScript globales de Dataform contient des propriétés que vous pouvez utiliser pour configurer les objets créés.
Vous pouvez créer les actions de workflow suivantes en utilisant uniquement JavaScript dans Dataform:
- Déclarations de sources de données
- Tables
- Affirmations manuelles
- Opérations SQL personnalisées
Avec JavaScript, vous pouvez créer des actions similaires à plusieurs reprises dans votre workflow. 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 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 à l'aide de méthodes globales Dataform et de code JavaScript ES5 arbitraire, comme des boucles et des constantes.
Vous pouvez définir les actions suivantes avec JavaScript dans Dataform:
Créer un fichier JavaScript
Stockez les fichiers JavaScript pour les définitions et les déclarations de sources de données dans le répertoire definitions/. Pour créer un fichier JavaScript dans le répertoire definitions/, procédez comme suit:
Dans le volet Fichiers, à côté de
definitions/, cliquez sur Plus.Cliquez sur Créer un fichier.
Dans le volet Créer un fichier, procédez comme suit :
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.
Cliquez sur Créer un fichier.
Définir des propriétés d'action de workflow avec JavaScript
Vous pouvez utiliser les méthodes globales Dataform suivantes pour créer des actions de workflow SQL avec Dataform:
declare: permet de déclarer une source de données.publish: permet de définir une table.assert: permet de 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 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 en tant que deuxième argument de la méthode.
Pour transmettre les propriétés de la table comme deuxième argument de publish(), procédez comme suit:
Dans votre espace de travail de développement, dans le volet Fichiers, développez
definitions/.Sélectionnez un fichier JavaScript.
Dans le fichier, ajoutez des propriétés de 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 pour la méthode publish() en transmettant les propriétés 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érencer des inclusions dans un fichier JavaScript
Vous pouvez faire référence à n'importe quelle fonction, macro ou constante d'inclusion dans un fichier JavaScript. Pour en savoir plus sur les inclusions dans Dataform, consultez la section Réutiliser du code dans un seul dépôt avec des inclusions de ce document.
La syntaxe de référence des inclusions dans un fichier JavaScript dépend de l'emplacement du fichier d'inclusion. Dataform stocke ces fichiers dans le répertoire "includes".
Les éléments de référence de premier niveau incluent
- Pour faire référence à un fichier d'inclusion de premier niveau, faites référence au nom du fichier lorsque vous déclarez vos variables.
L'exemple de code suivant fait référence aux variables serviceName et serviceId du fichier includes/service.js:
const {serviceName, serviceId} = service;
Références imbriquées incluses
Pour faire référence à un fichier d'inclusion imbriqué, saisissez le nom du fichier dans la fonction require JavaScript.
L'exemple de code suivant fait référence aux 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:
Dans votre espace de travail de développement, dans le volet Fichiers, développez
definitions/.Sélectionnez un fichier JavaScript.
Dans le fichier, saisissez une méthode JavaScript Dataform globale.
Dans la méthode, saisissez un argument
ctxcontextuel.Facultatif: Si vous utilisez des chaînes de modèle JavaScript, encapsulez l'argument contextuel entre crochets arrière
``.Dans l'argument contextable, saisissez la fonction de requête avec son paramètre en tant qu'objet de contexte.
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 avec JavaScript
Vous pouvez déclarer plusieurs sources de données dans un même fichier de déclaration JavaScript à l'aide de la méthode JavaScript de déclaration Dataform. Pour en savoir plus sur la méthode declare, consultez la documentation de référence de Dataform. Pour en savoir plus sur les sources de données dans Dataform, consultez la section Déclarer une source de données.
Pour déclarer une source de données dans un fichier JavaScript, procédez comme suit:
Dans votre espace de travail de développement, dans le volet Fichiers, développez
definitions/.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: ID du projet contenant la source de donnéesBIGQUERY_SCHEMA: ensemble de données BigQuery dans lequel la relation externe existeRELATION_NAME: nom de la relation que vous pourrez 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 bloc
declaresupplémentaire au fichier.Facultatif: cliquez sur Format.
Définir une table avec JavaScript
Vous pouvez créer un tableau avec la méthode JavaScript publish de Dataform. Pour en savoir plus sur la méthode de publication, consultez la documentation de référence de Dataform.
Vous pouvez définir les types de tableaux suivants:
- Tableau
- Tableau incrémental
- Afficher
Pour en savoir plus sur la définition de tables dans Dataform, consultez la section Créer une table.
Pour définir un tableau dans un fichier JavaScript, procédez comme suit:
Dans votre espace de travail de développement, dans le volet Fichiers, développez
definitions/.Sélectionnez un fichier JavaScript.
Dans le fichier, saisissez l'extrait de code suivant :
publish("TABLE_NAME").query(ctx => "SELECT_QUERY");Remplacez les éléments suivants :
TABLE_NAME: nom de la tableSELECT_QUERY: instruction SELECT SQL définissant le tableau
Pour définir le type de table, ajouter des dépendances de table et ajouter une description de table, définissez les propriétés de l'objet 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 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 d'assertion, consultez la documentation de référence de Dataform.
Une requête SQL d'assertion manuelle doit renvoyer zéro ligne. Si la requête renvoie des lignes lors de son exécution, 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 section Tester des tables avec des assertions.
Pour créer une assertion manuelle dans un fichier JavaScript, procédez comme suit:
Dans votre espace de travail de développement, dans le volet Fichiers, 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");Remplacez les éléments suivants :
ASSERTION_NAME: nom de votre assertion personnaliséeCUSTOM_ASSERTION_QUERY: votre requête d'assertion SQL
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'aucune valeur de 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 d'exécution Dataform. Pour en savoir plus sur les opérations SQL personnalisées dans Dataform, consultez la section Ajouter des opérations SQL personnalisées.
Pour définir une opération SQL personnalisée avec JavaScript, procédez comme suit:
Dans votre espace de travail de développement, dans le volet Fichiers, 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");Remplacez les éléments suivants :
OPERATION_NAME: nom de l'opération personnaliséeCUSTOM_SQL_QUERY: 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 sur 2:
operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");
Étape suivante
- Pour savoir comment créer un package, consultez la section Créer un package.
- Pour savoir comment installer un paquet, consultez la section Installer un paquet.
- Pour savoir comment authentifier un package privé, consultez la section Authentifier un package privé.
- Pour savoir comment utiliser un package Open Source dans Dataform, consultez Utiliser des dimensions à évolution lente dans Dataform.