Riferimento principale per Dataform

Questo documento descrive i metodi, le proprietà e le opzioni di configurazione del core Dataform. Puoi utilizzare il core Dataform nei file SQLX e JavaScript.

dichiara()

assert (name: string, query?: AContextable)

Aggiunge un'asserzione Dataform nel grafico compilato.

Disponibile solo nella directory /definitions.

Esempio:

// definitions/file.js

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

Contesto comune

I metodi di contesto sono disponibili durante la valutazione del codice SQL contestualizzabile, ad esempio all'interno dei file SQLX, o quando si utilizza un argomento Contextable con il core Dataform.

`database`	`() => string`
	Restituisce il database di questo set di dati, se applicabile.
`name`	`() => string`
	Restituisce il nome di questa tabella.
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Fa riferimento a un'altra azione, aggiungendola come dipendenza a questa azione, restituendo SQL valido da utilizzare in un'espressione `from`. Questa funzione può essere chiamata con un oggetto `Resolvable`, ad esempio: `${ref({ name: "name", schema: "schema", database: "database" })}` Questa funzione può anche essere chiamata utilizzando singoli argomenti per i valori `"database"`, `"schema"` e `"name"`. Se vengono forniti solo due valori, viene utilizzato il database predefinito e i valori vengono interpretati come `"schema"` e `"name"`. Quando viene fornito un solo valore, vengono utilizzati il database e lo schema predefiniti, con il valore fornito interpretato come ""nome"". `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Simile a `ref`, ma l'azione di riferimento non viene aggiunta come dipendenza da questa azione.
`self`	`() => string`
	Equivalente a `resolve(name())`. Restituisce una stringa SQL valida che può essere utilizzata per fare riferimento alla tabella prodotta da questa azione.
`schema`	`() => string`
	Restituisce lo schema di questo set di dati.

Contestuale

Gli argomenti contestuali possono passare un valore normale per il loro tipo generico T o una funzione chiamata con l'oggetto di contesto per questo tipo di operazione.

T | (ctx: Context) => T

Dataform

Variabile globale contenente l'oggetto IProjectConfig. Obbligatorio per ottenere le proprietà IProjectConfig, ad esempio:

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

dichiara()

declare (dataset: dataform.ITarget)

Dichiara il set di dati come origine dati Dataform.

Disponibile solo nella directory /definitions.

Esempio:

// definitions/file.js

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

Configurazione Iaction

Definisce i tag Dataform e le dipendenze applicate a un'azione del flusso di lavoro SQL.

`tags`	`string[]`
	Un elenco di tag definiti dall'utente con cui deve essere etichettata l'azione.
`dependencies`	`Resolvable\| Resolvable[]`
	Dipendenze dell'azione.
`disabled`	`boolean`
	Se è impostata su true, questa azione non verrà eseguita. Tuttavia, l'azione può comunque dipendere. Utile per disattivare temporaneamente le azioni non funzionanti.

Configurazione asserzione

Opzioni di configurazione per assertion tipi di azione.

`database`	`string`
	Il database (ID progetto Google Cloud) in cui creare la vista corrispondente per questa affermazione.
`description`	`string`
	Una descrizione di questa affermazione.
`disabled`	`boolean`
	Se è impostata su `true`, questa azione non viene eseguita. L'azione può comunque dipendere. Utile per disattivare temporaneamente le azioni non funzionanti.
`hermetic`	`boolean`
	Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate esplicitamente. Se questa azione dipende da dati provenienti da un'origine che non è dichiarata come dipendenza, imposta `hermetic` su `false`. In caso contrario, imposta `true`.
`schema`	`string`
	Lo schema (set di dati BigQuery) in cui creare la vista corrispondente per questa affermazione.
`tags`	`string[]`
	Un elenco dei tag definiti dall'utente applicati a questa azione.

Opzioni BigQuery

Opzioni di warehouse specifiche per BigQuery

`additionalOptions`
	Coppie chiave-valore per le opzioni table, view e materialized. Alcune opzioni, ad esempio `partitionExpirationDays`, hanno campi controllati di tipo/validità dedicati. Per queste opzioni, utilizza i campi dedicati. I valori delle stringhe devono essere racchiusi tra virgolette doppie, ad esempio: `additionalOptions: {numeric_option: "5"`, `string_option: '"string-value"'}` Se il nome dell'opzione contiene caratteri speciali, racchiudi il nome tra virgolette, ad esempio `additionalOptions: { "option-name": "value" }`.
`clusterBy`	`string[]`
	Le chiavi in base alle quali eseguire il clustering delle partizioni.
`labels`
	Coppie chiave-valore per etichette BigQuery. Se il nome dell'etichetta contiene caratteri speciali, ad esempio trattini, cita il nome, ad esempio `labels: { "label-name": "value" }.`
`partitionBy`	`string`
	La chiave con cui partizionare la tabella. In genere il nome di un timestamp o la colonna della data.
`partitionExpirationDays`	`number`
	Il numero di giorni in cui BigQuery archivia i dati in ciascuna partizione. L'impostazione si applica a tutte le partizioni di una tabella, ma viene calcolata in modo indipendente per ogni partizione in base all'ora di partizione.
`requirePartitionFilter`	`boolean`
	Dichiara se la tabella partizionata richiede un filtro del predicato con clausola `WHERE` che filtra la colonna di partizionamento.
`updatePartitionFilter`	`string`
	Filtro basato su SQL per il caso di applicazione degli aggiornamenti incrementali.

descrittoreIColonne

Descrive le colonne in una tabella.

{ [name]: string | IRecordDescriptor }

Configurazione IDeclaration

Opzioni di configurazione per declaration tipi di azione.

`columns`	`IColumnsDescriptor`
	Una descrizione delle colonne nella tabella.
`database`	`string`
	Il database (ID progetto Google Cloud) in cui creare la tabella di origine.
`description`	`string`
	Una descrizione della tabella.
`schema`	`string`
	Lo schema (set di dati BigQuery) in cui esiste la tabella di origine.

Configurazione IDependence

Definisce le dipendenze di un'azione del flusso di lavoro SQL.

`dependencies`	`Resolvable\| Resolvable[]`
	Una o più dipendenze esplicite per questa azione. Le azioni di dipendenza vengono eseguite prima delle azioni dipendenti. In genere questo stato non viene impostato perché la maggior parte delle dipendenze viene dichiarata come sottoprodotto dell'utilizzo della funzione `ref`.
`hermetic`	`boolean`
	Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate esplicitamente. Se questa azione dipende da dati provenienti da un'origine che non è stata dichiarata come dipendenza, `hermetic` deve essere esplicitamente impostato su `false`. Altrimenti, se questa azione dipende solo dai dati di dipendenze dichiarate esplicitamente, deve essere impostata su `true`.

Configurazione IDocumentable

Definisce le descrizioni di un set di dati e le relative colonne.

`columns`	`IColumnsDescriptor`
	Una descrizione delle colonne all'interno del set di dati.
`description`	`string`
	Una descrizione del set di dati.

Configurazione IDNome

Definisce il tipo e il nome di un'azione del flusso di lavoro SQL.

`type`	`string`
	Il tipo di azione.
`name`	`string`
	Il nome dell'azione.

Configurazione operazione

Opzioni di configurazione per operations tipi di azione.

`columns`	`IColumnsDescriptor`
	Una descrizione delle colonne nella tabella.
`database`	`string`
	Il database (ID progetto Google Cloud) in cui creare l'output di questa azione.
`description`	`string`
	Una descrizione della tabella.
`disabled`	`boolean`
	Se è impostata su `true`, questa azione non viene eseguita. L'azione può comunque dipendere. Utile per disattivare temporaneamente le azioni non funzionanti.
`hasOutput`	`boolean`
	Dichiara che questa azione `operations` crea una tabella a cui è possibile fare riferimento utilizzando la funzione `ref`. Se è impostata su `true`, questa azione crea una tabella con il nome configurato, utilizzando la funzione di contesto `self()`. Ad esempio: `create or replace table ${self()} as select ...`
`hermetic`	`boolean`
	Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate esplicitamente. Se questa azione dipende da dati provenienti da un'origine che non è dichiarata come dipendenza, imposta `hermetic` su `false`. In caso contrario, imposta `true`.
`schema`	`string`
	Lo schema (set di dati BigQuery) in cui creare l'output di questa azione.
`tags`	`string[]`
	Un elenco dei tag definiti dall'utente applicati a questa azione.

ConfigurazioneProgetto

Contiene le impostazioni di compilazione di un repository Dataform.

`defaultDatabase`	`string`
	Obbligatorio. Il database predefinito (ID progetto Google Cloud).
`defaultSchema`	`string`
	Obbligatorio. Lo schema predefinito (ID set di dati BigQuery).
`defaultLocation`	`string`
	Obbligatorio. La località BigQuery predefinita da utilizzare. Per ulteriori informazioni sulle località di BigQuery, consulta https://cloud.google.com/bigquery/docs/locations.
`assertionSchema`	`string`
	Obbligatorio. Lo schema predefinito (ID set di dati BigQuery) per le asserzioni.
`vars`	`map (key: string, value: string)`
	Campo facoltativo. Variabili definite dall'utente che vengono rese disponibili per il codice del progetto durante la compilazione. Un oggetto contenente un elenco di `"key": value` coppie. Esempio: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`.
`databaseSuffix`	`string`
	Campo facoltativo. Il suffisso da aggiungere a tutti i nomi di database (ID progetto Google Cloud).
`schemaSuffix`	`string`
	Campo facoltativo. Il suffisso da aggiungere a tutti i nomi dello schema (ID set di dati BigQuery).
`tablePrefix`	`string`
	Campo facoltativo. Il prefisso che deve essere anteposto a tutti i nomi delle tabelle.
`warehouse`	`string`
	Obbligatorio. Deve essere impostato su `bigquery`.

Puoi impostare le proprietà IProjectConfig in dataform.json a livello di repository.

Puoi eseguire l'override delle proprietà defaultSchema e defaultDatabase per singole tabelle.

Puoi accedere a tutte le proprietà IProjectConfig in un'istruzione SELECT SQL in un file SQLX o JavaScript.

L'esempio di codice riportato di seguito mostra la variabile di compilazione personalizzata myVariableName impostata in dataform.json con la proprietà projectConfig.vars, a cui è stato eseguito l'accesso in un'istruzione SELECT in un file SQLX:

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

Per ulteriori informazioni sull'override delle impostazioni di configurazione del progetto per i singoli risultati di compilazione, consulta la risorsa REST di projects.locations.repositories.compilationResults#CodeCompilationConfig nell'API Dataform.

Descrittore IRecord

Descrive uno struct, un oggetto o un record in una tabella con colonne nidificate.

`bigqueryPolicyTags`	`string \| string[]`
	Identificatori completi dei tag di criteri BigQuery applicati a questa colonna. Un identificatore completo di un tag di criteri BigQuery include il nome del progetto, la località e la tassonomia, Ad esempio: `"projects/1/locations/eu/taxonomies/2/policyTags/3"` Attualmente, BigQuery supporta un tag per colonna.
`columns`	`IColumnsDescriptor`
	Una descrizione delle colonne all'interno dello struct, dell'oggetto o del record.
`description`	`string`
	Una descrizione dello struct, dell'oggetto o del record.

Asserzioni ITable

Opzioni per la creazione di asserzioni come parte di una definizione tabella.

`nonNull`	`string \| string[]`
	Colonne che non possono mai essere `NULL`. Se impostata, la dichiarazione corrispondente non andrà a buon fine se una riga contiene `NULL` valori per queste colonne.
`rowConditions`	`string[]`
	Condizioni generali che devono rimanere valide per tutte le righe della tabella. Se viene impostata, la dichiarazione corrispondente non riesce se una riga viola una o più di queste condizioni.
`uniqueKey`	`string \| string[]`
	Colonne che costituiscono l'indice di chiave univoco della tabella. Se impostata, l'asserzione risultante non andrà a buon fine se è presente più di una riga nella tabella con gli stessi valori per tutte queste colonne.
`uniqueKeys`	`[]`
	Combinazioni di colonne, ciascuna delle quali costituisce un indice di chiave univoco della tabella. Se impostata, l'asserzione risultante non riesce se è presente più di una riga nella tabella con gli stessi valori per tutte le colonne delle chiavi univoche.

Configurazione ITable

Opzioni di configurazione per table azioni, tra cui table, view e incremental.

Estende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig e ITargetableConfig.

`assertions`	`ITableAssertions`
	Asserzioni da eseguire sulla tabella. Se configurate, le asserzioni pertinenti vengono create automaticamente ed eseguite come una dipendenza di questa tabella.
`bigquery`	`IBigQueryOptions`
	Opzioni di warehouse specifiche per BigQuery
`columns`	`IColumnsDescriptor`
	Una descrizione delle colonne nella tabella.
`database`	`string`
	Il database (ID progetto Google Cloud) in cui creare l'output di questa azione.
`description`	`string`
	Una descrizione della tabella.
`disabled`	`boolean`
	Se è impostata su `true`, questa azione non viene eseguita. L'azione può comunque dipendere. Utile per disattivare temporaneamente le azioni non funzionanti.
`hermetic`	`boolean`
	Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate esplicitamente. Se questa azione dipende da dati provenienti da un'origine che non è dichiarata come dipendenza, imposta `hermetic` su `false`. In caso contrario, imposta `true`.
`materialized`	`boolean`
	Valido solo quando il tipo di tabella è `view`. Se impostato su true, verrà creata una vista materializzata.
`protected`	`boolean`
	Consentito solo per il tipo di tabella `incremental` . Se è impostata su true, l'esecuzione di questa azione ignora l'opzione `full-refresh`. Questo è utile per le tabelle create con dati temporanei, per garantire che i dati storici non vadano mai persi.
`schema`	`string`
	Lo schema (set di dati BigQuery) in cui creare l'output di questa azione.
`tags`	`string[]`
	Un elenco dei tag definiti dall'utente applicati a questa azione.
`type`	`TableType`
	Il tipo di tabella.
`uniqueKey`	`string[]`
	Chiavi univoche per i criteri di unione per le tabelle incrementali. Se configurati, i record con chiavi univoche corrispondenti vengono aggiornati anziché con le nuove righe inserite.

Contesto ITable

`incremental`	`() => boolean`
	Restituisce true quando il contesto attuale indica che la tabella verrà creata in modo incrementale.
`name`	`() => string`
	Restituisce il nome completo della tabella.
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Fa riferimento a un'altra azione, aggiungendola come dipendenza a questa azione, restituendo SQL valido da utilizzare in un'espressione from. Questa funzione può essere chiamata con un oggetto `Resolvable`, ad esempio: `${ref({ name: "name", schema: "schema", database: "database" })}` Questa funzione può anche essere chiamata utilizzando singoli argomenti per i valori `"database"`, `"schema"` e `"name"`. Se vengono forniti solo due valori, viene utilizzato il database predefinito e i valori vengono interpretati come `"schema"` e `"name"`. Quando viene fornito un solo valore, viene utilizzato lo schema di database predefinito, con il valore fornito interpretato come ""nome"". `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Simile a `ref`, ma invece di aggiungere una dipendenza, risolve il riferimento fornito in modo che possa essere utilizzato in SQL, ad esempio in un'espressione "da".
`self`	`() => string`
	Equivalente a `resolve(name())`. Restituisce una stringa SQL valida che può essere utilizzata per fare riferimento alla tabella prodotta da questa azione.
`when`	`(cond: boolean, trueCase: string, falseCase: string) => string`
	abbreviazione di una condizione `if` . Equivalente a `cond ? trueCase : falseCase`. `falseCase` è facoltativo e il valore predefinito è una stringa vuota.

ITarget

Un riferimento a una tabella all'interno di BigQuery.

`database`	`string`
`name`	`string`
`schema`	`string`

Configurazione ITargetable

Definisce il database e lo schema di destinazione di un'azione del flusso di lavoro SQL.

`database`	`string`
	Il database in cui creare l'output di questa azione. Deve essere impostato su BigQuery.
`schema`	`string`
	Lo schema in cui creare l'output di questa azione.

opera()

operate (name: string, queries?: Contextable)

Definisce un'operazione SQL.

Disponibile solo nella directory /definitions.

Esempio:

// definitions/file.js

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

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

Crea una tabella o una visualizzazione.

Disponibile solo nella directory /definitions.

Esempio:

// definitions/file.js

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

Risolvibile

Un elemento risolvibile può essere il nome di una tabella come string o l'oggetto che descrive il percorso completo della relazione.

string | ITarget

Tipo di tabella

Tipi di azioni supportati dalla tabella.

Le tabelle di tipo view verranno create come viste.

Le tabelle di tipo table verranno create come tabelle.

Le tabelle di tipo incremental devono includere una clausola where. Per ulteriori informazioni, consulta la pagina Configurare le tabelle incrementali.