Riferimento principale di Dataform

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

assert()

assert (name: string, query?: AContextable)

Aggiunge un'affermazione Dataform al grafico compilato.

Disponibile solo nella directory /definitions.

Esempio:

// definitions/file.js

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

CommonContext

I metodi di contesto sono disponibili durante la valutazione del codice SQL contestuale, ad esempio all'interno dei file SQLX, o quando si utilizza un argomento Contextable con il nucleo di 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ò essere chiamata anche utilizzando singoli argomenti per i valori "database", "schema" e "name". Quando 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"name".

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Simile a ref, ma non aggiunge l'azione di riferimento come dipendenza a 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 trasmettere un valore normale per il loro tipo genericoT o una funzione chiamata con l'oggetto 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"

declare()

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

IActionConfig

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 l'azione deve essere etichettata.
dependencies Resolvable| Resolvable[]

Dipendenze dell'azione.
disabled boolean

Se impostato su true, questa azione non verrà eseguita. Tuttavia, l'azione può essere ancora considerata attendibile. È utile per disattivare temporaneamente le azioni non funzionanti.

IAssertionConfig

Opzioni di configurazione per i tipi di azioni assertion.

database string
Il database (Google Cloud ID progetto) in cui creare la vista corrispondente per questa asserzione.
description string
Una descrizione di questa affermazione.
disabled boolean
Se impostato su true, questa azione non viene eseguita. L'azione può comunque essere considerata attendibile. 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 dai dati di un'origine 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 asserzione.
tags string[]
Un elenco di tag definiti dall'utente applicati a questa azione.

IBigQueryOptions

Opzioni di data warehouse specifiche per BigQuery.

additionalOptions
Coppie chiave/valore per le opzioni tabella, visualizzazione e vista materializzata.

Alcune opzioni, ad esempio partitionExpirationDays, hanno campi di controllo di tipo/validità dedicati. Per queste opzioni, utilizza i campi dedicati.

I valori stringa devono essere racchiusi tra virgolette doppie, ad esempio: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Se il nome dell'opzione contiene caratteri speciali, racchiudilo tra virgolette, ad esempio: additionalOptions: { "option-name": "value" }.
clusterBy string[]
Le chiavi in base alle quali raggruppare le partizioni.
labels
Coppie chiave-valore per le etichette BigQuery.

Se il nome dell'etichetta contiene caratteri speciali, ad esempio i trattini, chiudelo tra virgolette, ad esempio labels: { "label-name": "value" }.
partitionBy string
La chiave in base alla quale partizionare la tabella. In genere, il nome di un timestamp o della colonna della data.
partitionExpirationDays number
Il numero di giorni per i quali BigQuery archivia i dati in ogni partizione. L'impostazione si applica a tutte le partizioni di una tabella, ma viene calcolata in modo indipendente per ogni partizione in base al momento della partizione.
requirePartitionFilter boolean
Dichiara se la tabella partizionata richiede un filtro del predicato della clausola WHERE che filtra la colonna di partizionamento.
updatePartitionFilter string
Filtro basato su SQL per quando vengono applicati aggiornamenti incrementali.

IColumnsDescriptor

Descrive le colonne di una tabella.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Opzioni di configurazione per i tipi di azioni declaration.

columns IColumnsDescriptor
Una descrizione delle colonne all'interno della tabella.
database string
Esista il database (Google Cloud ID progetto) 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.

IDependenciesConfig

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 verranno eseguite prima delle azioni dipendenti. In genere, questo valore non viene impostato, perché la maggior parte delle dipendenze viene dichiarata come sottoprodotto dell'utilizzo della funzione ref.
hermetic boolean

Dichiara se questa azione è o meno ermetica. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate esplicitamente. Se questa azione dipende da dati di un'origine che non è stata dichiarata come dipendenza, hermetic deve essere impostato esplicitamente su false. In caso contrario, se questa azione dipende solo dai dati delle dipendenze dichiarate esplicitamente, deve essere impostata su true.

IDocumentableConfig

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

columns IColumnsDescriptor

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

Una descrizione del set di dati.

INamedConfig

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.

IOperationConfig

Opzioni di configurazione per i tipi di azioni operations.

columns IColumnsDescriptor
Una descrizione delle colonne all'interno della tabella.
database string
Il database (Google Cloud ID progetto) in cui creare l'output di questa azione.
description string
Una descrizione della tabella.
disabled boolean
Se impostato su true, questa azione non viene eseguita. L'azione può comunque essere considerata attendibile. È 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 impostato 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 dai dati di un'origine 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 di tag definiti dall'utente applicati a questa azione.

IProjectConfig

Contiene le impostazioni di compilazione di un repository Dataform.

defaultDatabase string
Obbligatorio. Il database predefinito (Google Cloud ID progetto).
defaultSchema string
Obbligatorio. Lo schema predefinito (ID set di dati BigQuery).
defaultLocation string
Obbligatorio. La posizione BigQuery predefinita da utilizzare. Per ulteriori informazioni sulle località 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)
Facoltativo. Variabili definite dall'utente rese disponibili al codice del progetto durante la compilazione. Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Facoltativo. Il suffisso da aggiungere a tutti i nomi del database (Google Cloud ID progetto).
schemaSuffix string
Facoltativo. Il suffisso da aggiungere a tutti i nomi dello schema (ID set di dati BigQuery).
tablePrefix string
Facoltativo. Il prefisso da anteporre a tutti i nomi delle tabelle.
warehouse string
Obbligatorio. Deve essere impostato su bigquery.

Puoi impostare le proprietà IProjectConfig nelle impostazioni del flusso di lavoro a livello di repository.

Puoi sostituire le proprietà defaultSchema e defaultDatabase per le singole tabelle.

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

Il seguente esempio di codice mostra la variabile di compilazione personalizzata myVariableName impostata nelle impostazioni di flusso di lavoro con la proprietà projectConfig.vars, a cui si accede 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 projects.locations.repositories.compilationResults#CodeCompilationConfig nell'API Dataform.

IRecordDescriptor

Descrive una struttura, 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 criterio BigQuery include il nome, la posizione e la tassonomia del progetto.

Ad esempio: "projects/1/locations/eu/taxonomies/2/policyTags/3"

BigQuery supporta un tag per colonna.
columns IColumnsDescriptor
Una descrizione delle colonne all'interno della struttura, dell'oggetto o del record.
description string
Una descrizione della struttura, dell'oggetto o del record.

ITableAssertions

Opzioni per la creazione di asserzioni nell'ambito di una definizione di tabella.

nonNull string | string[]
Colonne che non possono mai essere NULL.

Se impostato, l'affermazione corrispondente non va a buon fine se una riga contiene valori NULL per queste colonne.
rowConditions string[]
Condizioni generali che devono essere vere per tutte le righe della tabella.

Se impostato, l'affermazione corrispondente non va a buon fine se una riga viola una di queste condizioni.
uniqueKey string | string[]
Colonne che costituiscono l'indice della chiave univoca della tabella.

Se impostato, l'affermazione risultante non va a buon fine se nella tabella è presente più di una riga con gli stessi valori per tutte le colonne.
uniqueKeys []
Combinazioni di colonne, ciascuna delle quali costituisce un indice di chiave univoca della tabella.

Se impostato, l'affermazione risultante non va a buon fine se nella tabella è presente più di una riga con gli stessi valori per tutte le colonne nelle chiavi univoche.

ITableConfig

Opzioni di configurazione per le azioni table, inclusi i tipi di tabelle table, view e incremental.

Estende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig e ITargetableConfig.

assertions ITableAssertions
Verifiche da eseguire sulla tabella.

Se configurate, le asserzioni pertinenti vengono create automaticamente e eseguite come dipendenza di questa tabella.
bigquery IBigQueryOptions
Opzioni di data warehouse specifiche per BigQuery.
columns IColumnsDescriptor
Una descrizione delle colonne all'interno della tabella.
database string
Il database (Google Cloud ID progetto) in cui creare l'output di questa azione.
description string
Una descrizione della tabella.
disabled boolean
Se impostato su true, questa azione non viene eseguita. L'azione può comunque essere considerata attendibile. È 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 dai dati di un'origine non dichiarata come dipendenza, imposta hermetic su false. In caso contrario, imposta true.
materialized boolean
Valido solo quando il tipo di tabella è view.

Se viene impostato su true, verrà creata una vista materializzata.
protected boolean
Consentito solo per il tipo di tabella incremental .

Se impostato su true, l'esecuzione di questa azione ignora l'opzione full-refresh. Questo è utile per le tabelle create da 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 di 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 configurato, i record con chiavi univoche corrispondenti vengono aggiornati anziché inserire nuove righe.

ITableContext

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

incremental () => boolean
Restituisce true quando il contesto corrente indica che la tabella verrà creata in modo incrementale.
name () => string
Restituisce il nome completo 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ò essere chiamata anche utilizzando singoli argomenti per i valori "database", "schema" e "name".

Quando 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 ""name"".

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Simile a ref, ma anziché aggiungere una dipendenza, risolve il riferimento fornito in modo che possa essere utilizzato in SQL, ad esempio in un'espressione "from".
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 per una condizione if . Equivalente a cond ? trueCase : falseCase.

falseCase è facoltativo e il valore predefinito è una stringa vuota.

ITarget

Un riferimento a una tabella in BigQuery.

database string
name string
schema string

ITargetableConfig

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

database string

Il database in cui deve essere creato l'output di questa azione. Deve essere impostato su BigQuery.
schema string

Lo schema in cui deve essere creato l'output di questa azione.

operate()

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 alla relazione.

string | ITarget

TableType

Tipi di azioni della tabella supportati.

Le tabelle di tipo view verranno create come visualizzazioni.

Le tabelle di tipo table verranno create come tabelle.

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