Référence de base Dataform

Ce document décrit les méthodes, les propriétés et les options de configuration de Dataform Core. Vous pouvez utiliser Dataform Core dans les fichiers SQLX et JavaScript.

assert()

assert	(name: string, query?: AContextable)
	Ajoute une assertion Dataform au graphique compilé. Disponible uniquement dans le répertoire /definitions.

Exemple :

// definitions/file.js

assert("name").query(ctx => "select 1");

CommonContext

Les méthodes de contexte sont disponibles lors de l'évaluation du code SQL contextuel, par exemple dans les fichiers SQLX ou lors de l'utilisation d'un argument Contextable avec Dataform Core.

database	() => string
	Renvoie la base de données de cet ensemble de données, le cas échéant.
name	() => string
	Renvoie le nom de cette table.
ref	(ref: Resolvable | string[], rest: string[]) => string
	Fait référence à une autre action, en l'ajoutant comme dépendance à cette action, et renvoie un code SQL valide à utiliser dans une expression from. Cette fonction peut être appelée avec un objet Resolvable, par exemple : ${ref({ name: "name", schema: "schema", database: "database" })} Cette fonction peut également être appelée à l'aide d'arguments individuels pour les valeurs "database", "schema" et "name". Lorsque seules deux valeurs sont fournies, la base de données par défaut est utilisée et les valeurs sont interprétées comme "schema" et "name". Lorsqu'une seule valeur est fournie, la base de données et le schéma par défaut sont utilisés, et la valeur fournie est interprétée comme "name". ${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve	(ref: Resolvable | string[], rest: string[]) => string
	Semblable à ref, mais n'ajoute pas l'action référencée comme dépendance à cette action.
self	() => string
	Équivaut à resolve(name()). Renvoie une chaîne SQL valide pouvant être utilisée pour faire référence à la table générée par cette action.
schema	() => string
	Renvoie le schéma de cet ensemble de données.

Contextable

Les arguments contextuels peuvent transmettre une valeur simple pour leur type générique T ou une fonction appelée avec l'objet de contexte pour ce type d'opération.

T | (ctx: Context) => T

Dataform

Variable globale contenant l'objet IProjectConfig. Obligatoire pour obtenir les propriétés IProjectConfig, par exemple :

dataform.projectConfig.vars.myVariableName === "myVariableValue"

déclarer()

declare	(dataset: dataform.ITarget)
	Déclare l'ensemble de données comme source de données Dataform. Disponible uniquement dans le répertoire /definitions.

Exemple :

// definitions/file.js

declare({name: "a-declaration"})

IActionConfig

Définit les tags Dataform et les dépendances appliqués à une action de workflow.

tags	string[]
	Liste des tags définis par l'utilisateur avec lesquels l'action doit être étiquetée.
dependencies	Resolvable| Resolvable[]
	Dépendances de l'action.
disabled	boolean
	Si la valeur est définie sur "true", cette action ne sera pas exécutée. Toutefois, l'action peut toujours être utilisée comme dépendance. Utile pour désactiver temporairement les actions défectueuses.

IAssertionConfig

Options de configuration pour les types d'action assertion.

database	string
	Base de données (ID de projetGoogle Cloud ) dans laquelle créer la vue correspondante pour cette assertion.
description	string
	Description de cette assertion.
disabled	boolean
	Si la valeur est définie sur true, cette action n'est pas exécutée. L'action peut toujours être utilisée comme dépendance. Utile pour désactiver temporairement les actions défectueuses.
hermetic	boolean
	Indique si cette action est hermétique. Une action est hermétique si toutes ses dépendances sont explicitement déclarées. Si cette action dépend de données provenant d'une source qui n'est pas déclarée comme dépendance, définissez hermetic sur false. Sinon, définissez-la sur true.
schema	string
	Schéma (ensemble de données BigQuery) dans lequel créer la vue correspondante pour cette assertion.
tags	string[]
	Liste des tags définis par l'utilisateur appliqués à cette action.

IBigQueryOptions

Options d'entrepôt spécifiques à BigQuery.

additionalOptions
	Paires clé/valeur pour les options table, view et materialized view. Certaines options, par exemple partitionExpirationDays, disposent de champs dédiés pour vérifier le type et la validité. Pour ces options, utilisez les champs dédiés. Les valeurs de chaîne doivent être encapsulées entre guillemets doubles, par exemple : additionalOptions: {numeric_option: "5", string_option: '"string-value"'} Si le nom de l'option contient des caractères spéciaux, placez-le entre guillemets, par exemple : additionalOptions: { "option-name": "value" }.
clusterBy	string[]
	Clés permettant de regrouper les partitions.
labels
	Paires clé/valeur pour les libellés BigQuery. Si le nom du libellé contient des caractères spéciaux, par exemple des tirets, placez-le entre guillemets, par exemple labels: { "label-name": "value" }..
partitionBy	string
	Clé permettant de partitionner la table. Il s'agit généralement du nom d'une colonne d'horodatage ou de date.
partitionExpirationDays	number
	Nombre de jours pendant lesquels BigQuery stocke les données dans chaque partition. Ce paramètre s'applique à toutes les partitions d'une table, mais il est calculé indépendamment pour chaque partition en fonction de l'heure de partition.
requirePartitionFilter	boolean
	Indique si la table partitionnée nécessite un filtre de prédicat de clause WHERE qui filtre la colonne de partitionnement.
updatePartitionFilter	string
	Filtre basé sur SQL pour les mises à jour incrémentielles.

IColumnsDescriptor

Décrit les colonnes d'un tableau.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Options de configuration pour les types d'action declaration.

columns	IColumnsDescriptor
	Description des colonnes du tableau.
database	string
	Base de données (ID du projetGoogle Cloud ) dans laquelle créer la table source.
description	string
	Description de la table.
schema	string
	Schéma (ensemble de données BigQuery) dans lequel se trouve la table source.

IDependenciesConfig

Définit les dépendances d'une action de workflow.

dependencies	Resolvable| Resolvable[]
	Une ou plusieurs dépendances explicites pour cette action. Les actions de dépendance s'exécutent avant les actions dépendantes. En règle générale, cette valeur reste non définie, car la plupart des dépendances sont déclarées comme sous-produit de l'utilisation de la fonction ref.
hermetic	boolean
	Indique si cette action est hermétique ou non. Une action est hermétique si toutes ses dépendances sont explicitement déclarées. Si cette action dépend de données provenant d'une source qui n'a pas été déclarée comme dépendance, hermetic doit être explicitement défini sur false. Sinon, si cette action ne dépend que des données des dépendances déclarées de manière explicite, elle doit être définie sur true.

IDocumentableConfig

Définit les descriptions d'un ensemble de données et de ses colonnes.

columns	IColumnsDescriptor
	Description des colonnes de l'ensemble de données.
description	string
	Description de l'ensemble de données.

INamedConfig

Définit le type et le nom d'une action de workflow.

type	string
	Type d'action.
name	string
	Nom de l'action.

IOperationConfig

Options de configuration pour les types d'action operations.

columns	IColumnsDescriptor
	Description des colonnes du tableau.
database	string
	Base de données (ID du projetGoogle Cloud ) dans laquelle créer le résultat de cette action.
description	string
	Description de la table.
disabled	boolean
	Si la valeur est définie sur true, cette action n'est pas exécutée. L'action peut toujours être utilisée comme dépendance. Utile pour désactiver temporairement les actions défectueuses.
hasOutput	boolean
	Déclare que cette action operations crée une table référençable à l'aide de la fonction ref. Si la valeur est définie sur true, cette action crée une table avec son nom configuré à l'aide de la fonction de contexte self(). Par exemple : create or replace table ${self()} as select ...
hermetic	boolean
	Indique si cette action est hermétique. Une action est hermétique si toutes ses dépendances sont explicitement déclarées. Si cette action dépend de données provenant d'une source qui n'est pas déclarée comme dépendance, définissez hermetic sur false. Sinon, définissez-la sur true.
schema	string
	Schéma (ensemble de données BigQuery) dans lequel créer le résultat de cette action.
tags	string[]
	Liste des tags définis par l'utilisateur appliqués à cette action.

IProjectConfig

Contient les paramètres de compilation d'un dépôt Dataform.

defaultDatabase	string
	Obligatoire. Base de données par défaut (Google Cloud ID de projet).
defaultSchema	string
	Obligatoire. Schéma par défaut (ID de l'ensemble de données BigQuery).
defaultLocation	string
	Obligatoire. Emplacement BigQuery par défaut à utiliser. Pour en savoir plus sur les emplacements BigQuery, consultez https://cloud.google.com/bigquery/docs/locations.
assertionSchema	string
	Obligatoire. Schéma par défaut (ID de l'ensemble de données BigQuery) pour les assertions.
vars	map (key: string, value: string)
	Facultatif. Variables définies par l'utilisateur et mises à la disposition du code du projet lors de la compilation. Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix	string
	Facultatif. Suffixe à ajouter à tous les noms de bases de données (ID de projetGoogle Cloud ).
schemaSuffix	string
	Facultatif. Suffixe à ajouter à tous les noms de schémas (ID d'ensemble de données BigQuery).
tablePrefix	string
	Facultatif. Préfixe à ajouter à tous les noms de tables.
warehouse	string
	Obligatoire. Doit être défini sur bigquery.

Vous pouvez définir les propriétés IProjectConfig dans les paramètres de workflow au niveau du dépôt.

Vous pouvez remplacer les propriétés defaultSchema et defaultDatabase pour des tables individuelles.

Vous pouvez accéder à toutes les propriétés IProjectConfig dans une instruction SQL SELECT d'un fichier SQLX ou JavaScript.

L'exemple de code suivant montre la variable de compilation personnalisée myVariableName définie dans les paramètres du workflow avec la propriété projectConfig.vars, accessible dans une instruction SELECT d'un fichier SQLX :

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

Pour en savoir plus sur le remplacement des paramètres de configuration du projet pour les résultats de compilation individuels, consultez la ressource REST projects.locations.repositories.compilationResults#CodeCompilationConfig dans l'API Dataform.

IRecordDescriptor

Décrit une structure, un objet ou un enregistrement dans une table comportant des colonnes imbriquées.

bigqueryPolicyTags	string | string[]
	Identifiants complets des tags avec stratégie BigQuery appliqués à cette colonne. Un identifiant complet de tag avec stratégie BigQuery inclut le nom du projet, l'emplacement et la taxonomie. Par exemple : "projects/1/locations/eu/taxonomies/2/policyTags/3" BigQuery accepte un tag par colonne.
columns	IColumnsDescriptor
	Description des colonnes dans la structure, l'objet ou l'enregistrement.
description	string
	Description de la structure, de l'objet ou de l'enregistrement.

ITableAssertions

Options permettant de créer des assertions dans une définition de table.

nonNull	string | string[]
	Colonnes qui ne peuvent jamais être NULL. Si cette option est définie, l'assertion correspondante échoue si une ligne contient des valeurs NULL pour ces colonnes.
rowConditions	string[]
	Conditions générales qui doivent être vraies pour toutes les lignes du tableau. Si cette option est définie, l'assertion correspondante échoue si une ligne ne respecte pas l'une de ces conditions.
uniqueKey	string | string[]
	Colonne(s) qui constitue(nt) l'index de clé unique de la table. Si cette option est définie, l'assertion résultante échoue si la table comporte plusieurs lignes avec les mêmes valeurs pour toutes ces colonnes.
uniqueKeys	[]
	Combinaisons de colonnes, chacune constituant un index de clé unique de la table. Si cette option est définie, l'assertion résultante échoue si la table comporte plusieurs lignes avec les mêmes valeurs pour toutes les colonnes de la ou des clés uniques.

ITableConfig

Options de configuration pour les actions table, y compris les types de tableaux table, view et incremental.

Étend IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig et ITargetableConfig.

assertions	ITableAssertions
	Assertions à exécuter sur la table. Si elles sont configurées, les assertions pertinentes sont automatiquement créées et exécutées en tant que dépendance de cette table.
bigquery	IBigQueryOptions
	Options d'entrepôt spécifiques à BigQuery.
columns	IColumnsDescriptor
	Description des colonnes du tableau.
database	string
	Base de données (ID de projetGoogle Cloud ) dans laquelle créer le résultat de cette action.
description	string
	Description de la table.
disabled	boolean
	Si la valeur est définie sur true, cette action n'est pas exécutée. L'action peut toujours être utilisée comme dépendance. Utile pour désactiver temporairement les actions défectueuses.
hermetic	boolean
	Indique si cette action est hermétique. Une action est hermétique si toutes ses dépendances sont explicitement déclarées. Si cette action dépend de données provenant d'une source qui n'est pas déclarée comme dépendance, définissez hermetic sur false. Sinon, définissez-la sur true.
materialized	boolean
	Valable uniquement lorsque le type de tableau est view. Si la valeur est définie sur "true", une vue matérialisée est créée.
protected	boolean
	Autorisé uniquement pour le type de tableau incremental . Si la valeur est définie sur "true", l'exécution de cette action ignore l'option full-refresh. Cela est utile pour les tables créées à partir de données transitoires, afin de vérifier que les données historiques ne sont jamais perdues.
schema	string
	Schéma (ensemble de données BigQuery) dans lequel créer le résultat de cette action.
tags	string[]
	Liste des tags définis par l'utilisateur appliqués à cette action.
type	TableType
	Type de la table.
uniqueKey	string[]
	Clés uniques pour les critères de fusion des tables incrémentielles. Si cette option est configurée, les enregistrements dont la ou les clés uniques correspondent sont mis à jour au lieu d'insérer de nouvelles lignes.

ITableContext

Les méthodes de contexte sont disponibles lors de l'évaluation du code SQL contextuel, par exemple dans les fichiers SQLX ou lors de l'utilisation d'un argument Contextable avec Dataform Core.

incremental	() => boolean
	Renvoie la valeur "true" lorsque le contexte actuel indique que la table sera créée de manière incrémentielle.
name	() => string
	Renvoie le nom complet de cette table.
ref	(ref: Resolvable | string[], rest: string[]) => string
	Fait référence à une autre action, en l'ajoutant comme dépendance à cette action, et renvoie un code SQL valide à utiliser dans une expression "from". Cette fonction peut être appelée avec un objet Resolvable, par exemple : ${ref({ name: "name", schema: "schema", database: "database" })} Cette fonction peut également être appelée à l'aide d'arguments individuels pour les valeurs "database", "schema" et "name". Lorsque seules deux valeurs sont fournies, la base de données par défaut est utilisée et les valeurs sont interprétées comme "schema" et "name". Lorsqu'une seule valeur est fournie, le schéma de base de données par défaut est utilisé, et la valeur fournie est interprétée comme "name". ${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve	(ref: Resolvable | string[], rest: string[]) => string
	Semblable à ref, mais au lieu d'ajouter une dépendance, il résout la référence fournie afin qu'elle puisse être utilisée dans SQL, par exemple dans une expression "from".
self	() => string
	Équivaut à resolve(name()). Renvoie une chaîne SQL valide pouvant être utilisée pour référencer la table produite par cette action.
when	(cond: boolean, trueCase: string, falseCase: string) => string
	Raccourci pour une condition if . Équivaut à cond ? trueCase : falseCase. falseCase est facultatif et sa valeur par défaut est une chaîne vide.

ITarget

Référence à une table dans BigQuery.

database	string
name	string
schema	string

ITargetableConfig

Définit la base de données et le schéma cibles d'une action de workflow.

database	string
	Base de données dans laquelle le résultat de cette action doit être créé. Doit être défini sur BigQuery.
schema	string
	Schéma dans lequel la sortie de cette action doit être créée.

operate()

operate	(name: string, queries?: Contextable)
	Définit une opération SQL. Disponible uniquement dans le répertoire /definitions.

Exemple :

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish	(name: string, queryOrConfig?: Contextable | ITableConfig)
	Crée une table ou une vue. Disponible uniquement dans le répertoire /definitions.

Exemple :

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

Résolvable

Un élément pouvant être résolu peut être le nom d'une table sous la forme string ou l'objet qui décrit le chemin d'accès complet à la relation.

string | ITarget

TableType

Types d'actions sur les tableaux acceptés.

Les tables de type view seront créées en tant que vues.

Les tables de type table seront créées en tant que tables.

Les tables de type incremental doivent inclure une clause where. Pour en savoir plus, consultez Configurer une table incrémentielle.