Documentation de référence de Dataform Core

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
Référence une autre action, en l'ajoutant en tant que 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, la valeur fournie étant 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 qui peut être utilisée pour référencer la table produite 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"

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"})

defaultLocation

La propriété defaultLocation spécifie l'emplacement par défaut de votre ensemble de données BigQuery. Dataform utilise cet emplacement pour traiter votre code et stocker les résultats. Cet emplacement de traitement doit correspondre à celui de vos ensembles de données BigQuery. Toutefois, il ne doit pas nécessairement correspondre à l'emplacement du dépôt Dataform.

Si vous ne définissez pas la propriété defaultLocation, Dataform détermine l'emplacement en fonction des ensembles de données référencés par votre requête SQL. Le principe est le suivant :

  • Si votre requête fait référence à des ensembles de données du même emplacement, Dataform utilise cet emplacement.
  • Une erreur se produit si votre requête fait référence à des ensembles de données provenant de deux emplacements différents ou plus. Pour en savoir plus sur cette limitation, consultez la section Réplication interrégionale d'ensembles de données.
  • Si votre requête ne fait référence à aucun ensemble de données, l'emplacement par défaut de Dataform est l'emplacement multirégional US. Pour choisir un autre emplacement, définissez la propriété defaultLocation. Vous pouvez également utiliser la variable système @@location dans votre requête.

Pour en savoir plus, consultez Spécifier des emplacements.

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 dépendante. 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 du 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. 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-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, view et vue matérialisée.

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 par cluster.
labels
Paires clé/valeur pour les étiquettes BigQuery.

Si le nom de l'étiquette contient des caractères spéciaux, par exemple des traits d'union, 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 la 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 l'application des mises à jour incrémentielles.
iceberg IIcebergOptions
Options spécifiques à Apache Iceberg pour les tables gérées Iceberg.

IIcebergOptions

Options spécifiques à Apache Iceberg pour les tables gérées Iceberg.

connection string

Facultatif. Nom de ressource de votre connexion Cloud Storage, qui fournit les identifiants permettant de lire et d'écrire dans un espace de stockage externe. Il peut être mis en forme de l'une des manières suivantes :

  • PROJECT_ID.LOCATION.CONNECTION_ID

    Remplacez les valeurs suivantes :
    • PROJECT_ID : ID du projet Google Cloud
    • LOCATION : nom de l'emplacement de la connexion
    • CONNECTION_ID : nom ou ID de la connexion
  • projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID
  • DEFAULT

La valeur par défaut est DEFAULT. Pour en savoir plus, consultez la présentation de la connexion par défaut.

file_format string

Facultatif. Format de fichier pour les données du tableau.

Seule l'option PARQUET est acceptée. La valeur par défaut est PARQUET.

bucket_name string

Obligatoire au niveau de la table ou du workflow. Nom du bucket Cloud Storage dans lequel les données de la table sont stockées.

Vous devez fournir bucket_name dans le bloc config du fichier de définition de table ou définir une valeur par défaut au niveau du workflow dans le fichier workflow_settings.yaml. Si aucun n'est fourni, la compilation échoue. Pour en savoir plus, consultez Configurer les valeurs par défaut au niveau du workflow pour les tables Iceberg .

table_folder_root string

Facultatif. Nom du dossier de premier niveau dans le bucket Cloud Storage où sont stockées les données de table.

Si vous ne définissez pas cette propriété, Dataform utilise la valeur par défaut au niveau du workflow à partir de workflow_settings.yaml si elle est définie. Sinon, la valeur par défaut est _dataform.

table_folder_subpath string

Facultatif. Un sous-dossier dans tableFolderRoot.

Si vous ne définissez pas cette propriété, Dataform utilise la valeur par défaut au niveau du workflow de workflow_settings.yaml, si elle est définie. Si ni la propriété, ni une valeur par défaut au niveau du workflow ne sont définies, le sous-chemin est défini par défaut sur DATASET_NAME/TABLE_NAME.

Ces valeurs construisent l'URI Cloud Storage au format suivant : gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH.

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 de la table.
database string
Base de données (ID du projetGoogle Cloud ) dans laquelle se trouve 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, ce champ n'est pas défini, car la plupart des dépendances sont déclarées comme un 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 de l'action.
name string

Nom de l'action.

IOperationConfig

Options de configuration pour les types d'actions operations.

columns IColumnsDescriptor
Description des colonnes de la table.
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 le nom configuré, à l'aide de la fonction de contexte self().

Par exemple : create or replace table ${self()} as select ...
hermetic boolean
Déclare 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-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
Facultatif. Emplacement BigQuery par défaut où Dataform crée des tables.
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 base 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 au début de tous les noms de table.
defaultIcebergConfig object
Facultatif. Paramètres par défaut au niveau du workflow pour les tables gérées Apache Iceberg. Contient les champs suivants :
  • bucketName : facultatif. Nom par défaut du bucket Cloud Storage.
  • tableFolderRoot : facultatif. Nom par défaut du dossier de premier niveau dans le bucket Cloud Storage.
  • tableFolderSubpath : facultatif. Nom par défaut d'un sous-dossier dans tableFolderRoot.
Pour en savoir plus, consultez Configurer les valeurs par défaut au niveau du workflow pour les tables Iceberg.
preserveGovernanceControls boolean
Facultatif. Si la valeur est définie sur true, Dataform conserve automatiquement les règles de données et les tags de gouvernance des données (aperçu) BigQuery existants lors des exécutions de workflow pour toutes les tables du dépôt.
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 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 des résultats de compilation individuels, consultez la ressource REST 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 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 n'accepte qu'un seul 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[]
Colonne(s) 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[]
Condition(s) générale(s) 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) constituant l'index de clé unique de la table.

Si cette option est définie, l'assertion obtenue échoue s'il existe plusieurs lignes dans la table 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 obtenue échoue s'il existe plusieurs lignes dans la 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 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 de la table.
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. 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 en tant que dépendance, définissez hermetic sur false. Sinon, définissez-le sur true.
materialized boolean
Valide uniquement lorsque le type de tableau est view.

Si la valeur est "true", une vue matérialisée est créée.
onSchemaChange onSchemaChange
Valide uniquement lorsque le type de table est incremental.

Action effectuée après que Dataform a vérifié la requête SELECT pour déterminer si des colonnes ont été ajoutées ou supprimées.

Cette fonctionnalité est disponible en version bêta.
preserveGovernanceControls boolean
Facultatif. Si la valeur est définie sur true, Dataform sauvegarde et réapplique les règles de données et les tags de gouvernance des données BigQuery existants (version Preview) lors de la recréation d'une table, d'une vue ou d'une table incrémentielle lors d'une actualisation complète. Remplace les valeurs par défaut au niveau du workflow définies dans workflow_settings.yaml.
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 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 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
Référence une autre action, l'ajoute en tant que 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é, la valeur fournie étant 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 qui peut ê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 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 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.

onSchemaChange

Une fois la propriété onSchemaChange définie, Dataform vérifie la requête SELECT pour déterminer si des colonnes ont été ajoutées ou supprimées. Dataform effectue ensuite l'action spécifiée par la valeur de la propriété onSchemaChange. Vous pouvez définir l'action sur l'une des valeurs suivantes :

  • IGNORE (par défaut) : ignore les colonnes ajoutées et affiche une erreur pour les colonnes manquantes. Si onSchemaChange n'est pas défini, il s'agit du comportement par défaut lorsque le schéma change.
  • FAIL : arrête l'action si Dataform détecte un changement de schéma, ce qui permet de maintenir la cohérence du schéma.
  • EXTEND : ajoute de nouvelles colonnes de la requête à la table incrémentielle et ajoute des valeurs NULL pour les enregistrements précédents. Affiche une erreur si une colonne est supprimée ou manquante dans le schéma d'origine de la requête. Vous pouvez utiliser ce paramètre pour ajouter des colonnes à vos tables incrémentielles lors de l'exécution.

  • SYNCHRONIZE : ajoute de nouvelles colonnes de la requête à la table incrémentielle et ajoute des valeurs NULL pour les enregistrements précédents. Supprime les colonnes qui figuraient dans le schéma d'origine, mais qui sont désormais absentes de la requête actuelle.

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 résolvable 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 Configurer une table incrémentielle.