Référence de base Dataform

Ce document décrit les méthodes, les propriétés et les options de configuration du noyau Dataform. Vous pouvez utiliser le noyau Dataform 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 lorsque vous utilisez un argument Contextable avec le noyau Dataform.

database () => string
Renvoie la base de données de cet ensemble de données, le cas échéant.
name () => string
Renvoie le nom de ce tableau.
ref (ref: Resolvable | string[], rest: string[]) => string
Fait référence à une autre action, en l'ajoutant en tant que dépendance à cette action, et renvoie du 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 en tant que dépendance à cette action.
self () => string
Équivaut à resolve(name()).

Renvoie une chaîne SQL valide pouvant être utilisée pour faire référence au tableau produit par cette action.

schema () => string
Renvoie le schéma de cet ensemble de données.

Contextuel

Les arguments contextables 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"

declare()

declare (dataset: dataform.ITarget)

Déclarer 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 balises Dataform et les dépendances appliquées à une action de workflow SQL.

tags string[]

Liste des balises définies par l'utilisateur avec lesquelles l'action doit être libellée.

dependencies Resolvable| Resolvable[]

Dépendances de l'action.

disabled boolean

Si cette valeur est définie sur "true", cette action ne sera pas exécutée. Toutefois, l'action peut toujours être fiable. Utile pour désactiver temporairement les actions défectueuses.

IAssertionConfig

Options de configuration pour les types d'actions 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 true, cette action n'est pas exécutée. L'action peut toujours être fiable. 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 déclarées explicitement.

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-le 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, vue et vue matérialisée.

Certaines options, comme partitionExpirationDays, disposent de champs dédiés à la vérification du type/de 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 par lesquelles mettre en cluster 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 traits de soulignement, 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'un code temporel ou de la colonne 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'une table.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Options de configuration pour les types d'actions declaration.

columns IColumnsDescriptor
Description des colonnes du tableau.
database string
La base de données (ID de projetGoogle 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 se trouve la table source.

IDependenciesConfig

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

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 ne sera pas 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 déclarées explicitement. Si cette action dépend des données 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 explicitement, 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 SQL.

type string

Type d'action.

name string

Nom de l'action.

IOperationConfig

Options de configuration pour les types d'actions operations.

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 true, cette action n'est pas exécutée. L'action peut toujours être fiable. Utile pour désactiver temporairement les actions défectueuses.
hasOutput boolean
Déclarer que cette action operations crée une table référençable à l'aide de la fonction ref.

Si la valeur est true, cette action crée un tableau 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 déclarées explicitement.

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-le sur true.

schema string
Schéma (ensemble de données BigQuery) dans lequel créer la sortie 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 de projetGoogle Cloud ).
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 la page https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Obligatoire. Schéma par défaut (ID d'ensemble de données BigQuery) pour les assertions.
vars map (key: string, value: string)
Facultatif. Variables définies par l'utilisateur qui sont 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 base de données (ID de projetGoogle Cloud ).
schemaSuffix string
Facultatif. Suffixe à ajouter à tous les noms de schéma (ID d'ensemble de données BigQuery).
tablePrefix string
Facultatif. Préfixe à ajouter au début de tous les noms de table.
warehouse string
Obligatoire. Doit être défini sur bigquery.

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

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

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

L'exemple de code suivant montre la variable de compilation personnalisée myVariableName définie dans les paramètres de workflow avec la propriété projectConfig.vars, accessible dans une instruction SELECT dans 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 forçage des paramètres de configuration du projet pour des résultats de compilation individuels, consultez la ressource REST projects.locations.repositories.compilationResults#CodeCompilationConfig dans l'API Dataform.

IRecordDescriptor

Décrit une struct, 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 d'un tag avec stratégie BigQuery inclut le nom, l'emplacement et la taxonomie du projet.

Par exemple : "projects/1/locations/eu/taxonomies/2/policyTags/3"

BigQuery accepte une seule balise par colonne.
columns IColumnsDescriptor
Description des colonnes de la struct, de l'objet ou de l'enregistrement.
description string
Description de la struct, de l'objet ou de l'enregistrement.

ITableAssertions

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

nonNull string | string[]
Colonne(s) qui ne peuvent jamais être NULL.

Si elle est définie, l'assertion correspondante échoue si une ligne contient des valeurs NULL pour cette ou ces colonnes.

rowConditions string[]
(Une ou plusieurs) condition(s) générale(s) qui doivent être vraie(s) pour toutes les lignes de la table.

Si elle est définie, l'assertion correspondante échoue si une ligne ne respecte pas l'une de ces conditions.

uniqueKey string | string[]
Colonne(s) qui constituent l'index de clé unique de la table.

Si elle 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 indice de clé unique de la table.

Si elle est définie, l'assertion générée é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.

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

assertions ITableAssertions
Affirmations à exécuter sur le tableau.

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 la sortie 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 être fiable. 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 déclarées explicitement.

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-le sur true.

materialized boolean
Valable uniquement lorsque le type de table est view.

Si cette valeur est définie sur "True", une vue matérialisée est créée.

protected boolean
Autorisé uniquement pour le type de table incremental .

Si cette valeur est définie sur "true", l'exécution de cette action ignore l'option full-refresh. Cela est utile pour les tableaux créés à partir de données temporaires, afin de s'assurer que les données historiques ne sont jamais perdues.

schema string
Schéma (ensemble de données BigQuery) dans lequel créer la sortie 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 la ou les 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, par exemple dans les fichiers SQLX, ou lorsque vous utilisez un argument Contextable avec le noyau Dataform.

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 en tant que dépendance à cette action, et renvoie du 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 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 la table générée par cette action.

when (cond: boolean, trueCase: string, falseCase: string) => string
Raccourci pour une condition if . Équivaut à cond ? trueCase : falseCase.

falseCase est facultatif et utilise par défaut 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 SQL.

database string

Base de données dans laquelle la sortie de cette action doit être créée. 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ésoluble

Un élément résoluble 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 de table compatibles.

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 la section Configurer des tables incrémentielles.