Cette page a été traduite par l'API Cloud Translation.

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

Des méthodes de contexte sont disponibles lors de l'évaluation du code SQL contextuel, par exemple dans des 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 en tant que dépendance à cette action, renvoyant ainsi 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" (nom). `${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 référencer la table produite 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 ce 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"

déclarer()

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 tags Dataform et les dépendances appliquées à 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. Cependant, l'action peut toujours dépendre de la capacité. 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 de projet Google Cloud) dans laquelle créer la vue correspondant à 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 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 qui n'est pas déclarée en tant que 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 à 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, 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, encapsulez-le entre guillemets, par 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, tels que des traits d'union, mettez son nom entre guillemets (par exemple, `labels: { "label-name": "value" }.`).
`partitionBy`	`string`
	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 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 indiquant quand les mises à jour incrémentielles sont appliquées.

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`
	La 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. Les actions de dépendance s'exécutent avant les actions dépendantes. En règle générale, cette valeur n'est pas définie, 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 en tant que dépendance, `hermetic` doit être explicitement défini sur `false`. Sinon, si cette action ne dépend que des données provenant de dépendances explicitement déclarées, 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'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`
	Il indique que cette action `operations` crée une table pouvant être référencée à l'aide de la fonction `ref`. Si la valeur est `true`, cette action crée une table avec son nom configuré, à l'aide de la fonction de contexte `self()`. 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 en tant que 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 (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 à 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 projet Google Cloud).
`schemaSuffix`	`string`
	Facultatif. Suffixe à ajouter à tous les noms de schéma (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 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 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 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 de 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 contenant des colonnes imbriquées.

`bigqueryPolicyTags`	`string \| string[]`
	Identifiants complets des tags avec stratégie BigQuery appliqués à cette colonne. L'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 des valeurs `NULL` 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 elle 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. Si cette option est définie, l'assertion résultante échoue si plusieurs lignes de la table présentent 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 plusieurs lignes de la table présentent 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 table table, view et incremental.

Développe 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 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.
`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-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`. Cette fonctionnalité est utile pour les tables créées à partir de données temporaires, afin de garantir 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. S'ils sont configurés, 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, par exemple dans des fichiers SQLX, ou lors de l'utilisation d'un argument Contextable avec Dataform Core.

`incremental`	`() => boolean`
	Renvoie "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, renvoyant ainsi 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" (nom). `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Semblable à `ref`, à la différence qu'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 produite 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éé.

fonctionner()

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 élément pouvant être résolu peut être le nom d'une table (string) ou l'objet qui décrit le chemin d'accès complet à 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 plus d'informations, consultez la page Configurer des tables incrémentielles.