Riferimento principale di Dataform

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

assert()

assert (name: string, query?: AContextable)

Aggiunge un'asserzione 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 quando viene valutato il codice SQL contestuale, ad esempio all'interno dei file SQLX o quando viene utilizzato un argomento Contextable con Dataform Core.

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 un 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". Se 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 a cui viene fatto riferimento come dipendenza di 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.

Contextable

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

T | (ctx: Context) => T

Dataform

Variabile globale che contiene 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.

tags string[]

Un elenco di tag definiti dall'utente con cui etichettare l'azione.
dependencies Resolvable| Resolvable[]

Dipendenze dell'azione.
disabled boolean

Se è impostato su true, questa azione non verrà eseguita. Tuttavia, l'azione può comunque essere considerata affidabile. Utile per disattivare temporaneamente le azioni non funzionanti.

IAssertionConfig

Opzioni di configurazione per i tipi di azione assertion.

database string
Il database (ID progettoGoogle Cloud ) in cui creare la visualizzazione corrispondente per questa asserzione.
description string
Una descrizione di questa asserzione.
disabled boolean
Se è impostato su true, questa azione non viene eseguita. L'azione può comunque essere considerata affidabile. 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 in modo esplicito.

Se questa azione dipende da dati di un'origine non dichiarata come dipendenza, imposta hermetic su false. In caso contrario, imposta il valore su 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 warehouse specifiche di BigQuery.

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

Alcune opzioni, ad esempio partitionExpirationDays, hanno campi dedicati per il tipo e la validità. 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 trattini, metti il nome 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 indipendentemente per ogni partizione in base all'ora della partizione.
requirePartitionFilter boolean
Dichiara se la tabella partizionata richiede un filtro predicato della clausola WHERE che filtra la colonna di partizionamento.
updatePartitionFilter string
Filtro basato su SQL per quando vengono applicati gli aggiornamenti incrementali.

IColumnsDescriptor

Descrive le colonne di una tabella.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Opzioni di configurazione per i tipi di azione declaration.

columns IColumnsDescriptor
Una descrizione delle colonne all'interno della tabella.
database string
Esiste il database (ID progettoGoogle 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.

IDependenciesConfig

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

dependencies Resolvable| Resolvable[]

Una o più dipendenze esplicite per questa azione. Le azioni di dipendenza vengono eseguite prima delle azioni dipendenti. In genere questo valore rimane non impostato, perché la maggior parte delle dipendenze viene dichiarata come sottoprodotto dell'utilizzo della funzione ref.
hermetic boolean

Dichiara se questa azione è ermetica o meno. Un'azione è ermetica se tutte le sue dipendenze sono dichiarate in modo esplicito. 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 in modo esplicito, 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.

type string

Il tipo di azione.
name string

Il nome dell'azione.

IOperationConfig

Opzioni di configurazione per i tipi di azione operations.

columns IColumnsDescriptor
Una descrizione delle colonne all'interno della tabella.
database string
Il database (ID progettoGoogle Cloud ) 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 affidabile. 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 in modo esplicito.

Se questa azione dipende da dati di un'origine non dichiarata come dipendenza, imposta hermetic su false. In caso contrario, imposta il valore su 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 località BigQuery predefinita da utilizzare. Per ulteriori informazioni sulle località BigQuery, visita la pagina 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 dei 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 ignorare le proprietà defaultSchema e defaultDatabase per le singole tabelle.

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

Il seguente esempio di codice mostra la variabile di compilazione personalizzata myVariableName impostata nelle impostazioni del 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 di criteri BigQuery include il nome del progetto, la località e la tassonomia.

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 creare asserzioni nell'ambito di una definizione della tabella.

nonNull string | string[]
Colonna o colonne che non possono mai essere NULL.

Se impostata, l'asserzione corrispondente non riesce se una riga contiene valori NULL per queste colonne.
rowConditions string[]
Condizione o condizioni generali che devono essere vere per tutte le righe della tabella.

Se impostata, l'asserzione corrispondente non riesce se una riga viola una qualsiasi di queste condizioni.
uniqueKey string | string[]
Le colonne che costituiscono l'indice della chiave univoca della tabella.

Se impostata, l'asserzione risultante non riesce se nella tabella è presente più di una riga con gli stessi valori per tutte queste colonne.
uniqueKeys []
Combinazioni di colonne, ciascuna delle quali costituisce un indice di chiave univoca della tabella.

Se impostata, l'asserzione risultante non riesce se nella tabella è presente più di una riga con gli stessi valori per tutte le colonne delle 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
Asserzioni da eseguire sulla tabella.

Se configurate, le asserzioni pertinenti vengono create automaticamente ed eseguite come dipendenza di questa tabella.
bigquery IBigQueryOptions
Opzioni di warehouse specifiche di 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 affidabile. 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 in modo esplicito.

Se questa azione dipende da dati di un'origine non dichiarata come dipendenza, imposta hermetic su false. In caso contrario, imposta il valore su 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. Ciò è utile per le tabelle create a partire da dati temporanei, per verificare che i dati storici non vengano 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 configurati, i record con chiavi univoche corrispondenti vengono aggiornati anziché inserire nuove righe.

ITableContext

I metodi di contesto sono disponibili quando viene valutato il codice SQL contestuale, ad esempio all'interno dei file SQLX o quando viene utilizzato un argomento Contextable con Dataform Core.

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 un 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".

Se viene fornito un solo valore, viene utilizzato lo schema del database predefinito e il valore fornito viene 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 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

ITargetableConfig

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

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

string | ITarget

TableType

Tipi di azioni sulla tabella supportati.

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, vedi Configurare una tabella incrementale.