Documentation de référence sur 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 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, comme dans les fichiers SQLX, ou lorsque vous utilisez 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 en tant que dépendance à cette action renvoyant 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 la fonction Valeurs "database", "schema" et "name". Lorsque seulement deux valeurs sont fournies, la base de données par défaut est utilisée et les valeurs sont interprétés 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. avec la valeur fournie 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'objet référencé comme une dépendance à cette action.
self	() => string
	Équivaut à resolve(name()). Renvoie une chaîne SQL valide pouvant être utilisée pour référencer la table générées par cette action.
schema	() => string
	Affiche le schéma de cet ensemble de données.

Contextables

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 cette type d'opération.

T | (ctx: Context) => T

Dataform

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

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

declare()

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

Exemple :

// definitions/file.js

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

IActionConfig

Définit les balises Dataform et les dépendances appliquée à une action de workflow SQL.

tags	string[]
	Liste des tags définis par l'utilisateur auxquels l'action doit être associée.
dependencies	Resolvable| Resolvable[]
	Dépendances de l'action.
disabled	boolean
	Si elle est définie sur "true", cette action n'est pas exécutée. Toutefois, l'action peut dépendre toujours. Utile pour désactiver temporairement les actions erronées.

IAssertionConfig

Options de configuration pour les types d'action assertion.

database	string
	Base de données (ID du projet Google Cloud) dans laquelle créer la vue correspondante pour cette assertion.
description	string
	Description de cette assertion.
disabled	boolean
	Si la valeur est true, cette action n'est pas exécutée. L'action peut toujours dépendre. Utile pour temporairement et la désactivation des actions erronées.
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 non déclarée en tant que dépendance, puis 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 la table, la vue, et de vue matérialisée. Certaines options, par exemple partitionExpirationDays, disposent de champs dédiés au type ou à la validité vérifiés. 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. Exemple: additionalOptions: { "option-name": "value" }.
clusterBy	string[]
	Clés par lesquelles utiliser les partitions pour le clustering.
labels
	Paires clé-valeur pour les étiquettes BigQuery. Si le nom de l'étiquette contient des caractères spéciaux, comme des traits d'union, puis citer son nom, par exemple labels: { "label-name": "value" }.
partitionBy	string
	La clé par laquelle partitionner la table. Il s'agit généralement du nom d'un code temporel ou de la colonne de date.
partitionExpirationDays	number
	Nombre de jours pendant lesquels BigQuery stocke les données chaque partition. Le paramètre s'applique à toutes les partitions d'une table, mais il est calculé indépendamment pour chaque partition en fonction la durée de partition.
requirePartitionFilter	boolean
	Indique si la table partitionnée nécessite un WHERE filtre de prédicat de clause qui filtre la colonne de partitionnement.
updatePartitionFilter	string
	Filtre basé sur SQL indiquant quand mises à jour incrémentielles s'appliquent.

IColumnsDescriptor

Décrit les colonnes d'une table.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Options de configuration pour les types d'action declaration.

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

IDependenciesConfig

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

dependencies	Resolvable| Resolvable[]
	Une ou plusieurs dépendances explicites pour cette action. Actions de dépendance s'exécutera avant les actions dépendantes. En général, cette valeur n'est pas définie, car la plupart des dépendances sont déclarées comme résultat 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 des données provenant d'une source qui n'a pas été déclarée en tant que dépendance, hermetic doit être explicitement défini sur false. Dans le cas contraire, si cette action ne dépend que des données provenant de des dépendances, il doit être défini 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 SQL.

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 de la table.
database	string
	Base de données (ID du projet Google Cloud) dans laquelle créer le résultat de cette action.
description	string
	Description de la table.
disabled	boolean
	Si la valeur est true, cette action n'est pas exécutée. L'action peut toujours dépendre. Utile pour désactiver temporairement les actions erronées.
hasOutput	boolean
	Indique que l'action operations crée une table pouvant être référencé à l'aide de la fonction ref. Si la valeur est true, cette action crée un tableau avec ses à 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 non déclarée en tant que dépendance, puis 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 (ID du projet Google Cloud).
defaultSchema	string
	Obligatoire. Schéma par défaut (ID de l'ensemble de données BigQuery).
defaultLocation	string
	Obligatoire. Emplacement BigQuery à utiliser par défaut. 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 mises à disposition au 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 à toutes les bases de données (ID de projet Google Cloud).
schemaSuffix	string
	Facultatif. Suffixe à ajouter à tous les schémas (ID d'ensemble de données BigQuery).
tablePrefix	string
	Facultatif. Préfixe devant être ajouté à tous les noms de table.
warehouse	string
	Obligatoire. Doit être défini sur bigquery.

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

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

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

L'exemple de code suivant montre la variable de compilation personnalisée myVariableName défini dans les paramètres du workflow avec la 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!"
  )}

En savoir plus sur le remplacement des paramètres de configuration d'un projet Pour obtenir les résultats de compilation individuels, consultez Ressource REST projects.locations.repositories.compilationResults#CodeCompilationConfig dans API Dataform :

IRecordDescriptor

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

bigqueryPolicyTags	string | string[]
	Identifiants complets des tags avec stratégie BigQuery appliqués dans cette colonne. Identifiant complet d'un 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 de création d'assertions dans une définition de table.

nonNull	string | string[]
	Colonne(s) qui ne peuvent jamais être NULL. Si cette règle est définie, l'assertion correspondante échoue si une ligne contient NULL valeurs pour cette ou ces colonnes.
rowConditions	string[]
	Condition(s) générale(s) devant être vraie(s) pour toutes les lignes de la table. Si cette règle est définie, l'assertion correspondante échoue si une ligne enfreint l'une de ces conditions.
uniqueKey	string | string[]
	Colonne(s) constituant l'index de clé unique de la table. S'il est défini, l'assertion qui en résulte échoue s'il y a plusieurs lignes du tableau avec les mêmes valeurs pour toutes ces colonnes.
uniqueKeys	[]
	Combinaisons de colonnes, chacune constituant un index de clé unique de la table. S'il est défini, l'assertion résultante échoue s'il y a plus d'une ligne dans table 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 Types de tables table, view et incremental.

Développe IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig et ITargetableConfig.

assertions	ITableAssertions
	Assertions à exécuter sur la table. Si elle est configurée, les assertions pertinentes sont automatiquement créées et s'exécuter en tant que dépendance de cette table.
bigquery	IBigQueryOptions
	Options d'entrepôt spécifiques à BigQuery
columns	IColumnsDescriptor
	Description des colonnes de la table.
database	string
	La base de données (ID du projet Google Cloud) pour créer le résultat de cette action.
description	string
	Description de la table.
disabled	boolean
	Si la valeur est true, cette action n'est pas exécutée. L'action peut toujours dépendre. Utile pour désactiver temporairement les actions erronées.
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 non déclarée en tant que dépendance, puis définissez hermetic sur false. Sinon, définissez-la sur true.
materialized	boolean
	N'est valide que lorsque le type de la table est view. Si cette règle est définie sur "True", une vue matérialisée est créée.
protected	boolean
	Autorisé uniquement pour le type de table incremental . Si elle est définie sur "true", l'exécution de cette action ignore l'option full-refresh. Ceci est utile pour les tables qui sont créées à partir de données temporaires, pour garantir que les données historiques ne sont jamais perdues.
schema	string
	Schéma (ensemble de données BigQuery) dans lequel crée 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 elle est configurée, les enregistrements avec une ou plusieurs clés uniques correspondantes 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, comme dans les fichiers SQLX, ou lorsque vous utilisez un Contextable avec Dataform Core.

incremental	() => boolean
	Renvoie la valeur "true" lorsque le contexte actuel indique que le tableau sera créé progressivement.
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 en tant que dépendance à cette action en renvoyant 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 la fonction Valeurs "database", "schema" et "name". Lorsque seulement deux valeurs sont fournies, la base de données par défaut est utilisée et les valeurs sont interprétés comme "schema" et "name". Lorsqu'une seule valeur est fournie, le schéma de base de données par défaut est utilisé, avec le valeur fournie interprétée comme "nom". ${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 en 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 le tableau généré par cette action.
when	(cond: boolean, trueCase: string, falseCase: string) => string
	Raccourci d'une condition if . Équivaut à cond ? trueCase : falseCase. falseCase est facultatif et est défini par défaut sur 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 cible et le schéma d'une action de workflow SQL.

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 le résultat de cette action doit être créé.

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ésolu

Un résolvable peut être soit le nom d'une table, soit string, ou l'objet qui décrit le chemin complet de la relation.

string | ITarget

TableType

Types d'actions possibles pour les tables.

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 Configurez des tables incrémentielles.