Riferimento principale Dataform

Questo documento descrive metodi, proprietà e opzioni di configurazione Core Dataform. Puoi usare il core Dataform in 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 durante la valutazione di codice SQL contestuale, ad esempio all'interno di file SQLX o quando si utilizza Argomento Contextable con il core Dataform.

database () => string
Restituisce il database di questo set di dati, se applicabile.
name () => string
Restituisce il nome della tabella.
ref (ref: Resolvable | string[], rest: string[]) => string
Fa riferimento a un'altra azione, aggiungendola come dipendenza a questa azione, che restituisce un codice SQL valido da usare 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 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 specificato 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 il riferimento dell'azione 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 generate da questa azione.
schema () => string
Restituisce lo schema di questo set di dati.

Contestuale

Gli argomenti contestuali possono passare un valore normale per il tipo generico T o una funzione che viene richiamata con l'oggetto di 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 applicata 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 il valore è impostato su true, questa azione non verrà eseguita. Tuttavia, l'azione può da cui dipende ancora. Utile per disattivare temporaneamente le azioni non funzionanti.

IAssertionConfig

Opzioni di configurazione per i tipi di azione assertion.

database string
Il database (ID progetto Google Cloud) in cui creare la vista corrispondente per questa affermazione.
description string
Una descrizione di questa asserzione.
disabled boolean
Se impostato su true, questa azione non viene eseguita. L'azione può comunque dipendere da questa azione. Utile per temporaneamente disattivare le azioni non funzionanti.
hermetic boolean
Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze vengono dichiarate esplicitamente.

Se questa azione dipende da dati provenienti da un'origine non dichiarata come dipendenza, quindi imposta hermetic su false. In caso contrario, imposta su true.

schema string
Lo schema (set di dati BigQuery) in cui creare la vista corrispondente per questa affermazione.
tags string[]
Un elenco di tag definiti dall'utente applicati a questa azione.

IBigQueryOptions

Opzioni di warehouse specifiche per BigQuery.

additionalOptions
Coppie chiave-valore per table, view, e le opzioni di vista materializzata.

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

I valori delle stringhe devono essere racchiusi tra virgolette, 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 eseguire le partizioni nel cluster.
labels
Coppie chiave-valore per le etichette BigQuery.

Se il nome dell'etichetta contiene caratteri speciali, ad esempio trattini, quindi cita il suo nome, ad esempio labels: { "label-name": "value" }.
partitionBy string
La chiave tramite la quale 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 ogni partizione. L'impostazione si applica a tutte le partizioni di una tabella, ma viene calcolata in modo indipendente per ogni partizione in base il tempo di partizione.
requirePartitionFilter boolean
Dichiara se la tabella partizionata richiede un valore WHERE di una clausola, che filtra la colonna di partizionamento.
updatePartitionFilter string
Filtro basato su SQL per quando 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
Il database (ID progetto Google Cloud) in cui creare la tabella di origine esiste.
description string
Una descrizione della tabella.
schema string
Lo schema (set di dati BigQuery) in cui si trova 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. Azioni di dipendenza verrà eseguita prima delle azioni dipendenti. In genere questo comportamento non viene impostato perché la maggior parte delle dipendenze viene dichiarata come risultato dell'uso della funzione ref.
hermetic boolean

Dichiara se questa azione è o meno ermetica. Un'azione è ermetica se tutte le sue dipendenze vengono dichiarate esplicitamente. Se questa azione dipende da un'origine che non è stata dichiarata come dipendenza, hermetic deve essere impostato esplicitamente su false. Altrimenti, se questa azione dipende solo dai dati provenienti da delle dipendenze, il valore deve essere impostato su true.

IDocumentableConfig

Definisce le descrizioni di un set di dati e delle sue 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 azione operations.

columns IColumnsDescriptor
Una descrizione delle colonne all'interno della 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 impostato su true, questa azione non viene eseguita. L'azione può comunque dipendere da questa azione. Utile per disattivare temporaneamente le azioni non funzionanti.
hasOutput boolean
Dichiara che l'azione operations crea una tabella a cui è possibile fare riferimento usando la funzione ref.

Se il valore è impostato su true, questa azione crea una tabella con le relative 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 vengono dichiarate esplicitamente.

Se questa azione dipende da dati provenienti da un'origine non dichiarata come dipendenza, quindi imposta hermetic su false. In caso contrario, imposta 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 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à BigQuery, consulta https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Obbligatorio. 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 durante la compilazione. Un oggetto contenente un elenco di "key": value coppie. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Facoltativo. Il suffisso da aggiungere a tutto il database (ID progetto Google Cloud).
schemaSuffix string
Facoltativo. Il suffisso da aggiungere a tutto lo 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 configurare le proprietà IProjectConfig nelle impostazioni del flusso di lavoro 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.

Il seguente esempio di codice mostra la variabile di compilazione personalizzata myVariableName configurato nelle impostazioni del flusso di lavoro con 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 risultati delle singole compilazioni, consulta projects.locations.repositories.compilationResults#CodeCompilationConfig Risorsa REST in API Dataform.

IRecordDescriptor

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

bigqueryPolicyTags string | string[]
Identificatori completi dei tag di criterio BigQuery applicati a questa colonna. Un identificatore completo di un tag di criteri BigQuery include il nome, la località 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 dello struct, dell'oggetto o del record.
description string
Una descrizione dello struct, dell'oggetto o del record.

ITableAssertions

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

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

Se impostata, l'asserzione corrispondente ha esito negativo se una riga contiene NULL valori per queste colonne.
rowConditions string[]
Condizioni generali che devono essere soddisfatte per tutte le righe della tabella.

Se impostato, l'asserzione corrispondente ha esito negativo se una riga viola una o più di queste condizioni.
uniqueKey string | string[]
Colonne che costituiscono l'indice 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 queste colonne.
uniqueKeys []
Combinazioni di colonne, ognuna delle quali costituisce un indice di chiave univoco della tabella.

Se impostata, l'asserzione risultante ha esito negativo se c'è più di una riga in la tabella con gli stessi valori per tutte le colonne nelle chiavi univoche.

ITableConfig

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

Estende IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig e ITargetableConfig.

assertions ITableAssertions
Asserzioni da eseguire nella tabella.

Se configurate, le asserzioni pertinenti vengono create automaticamente ed eseguirla come dipendenza da questa tabella.
bigquery IBigQueryOptions
Opzioni di warehouse specifiche per BigQuery.
columns IColumnsDescriptor
Una descrizione delle colonne all'interno della 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 impostato su true, questa azione non viene eseguita. L'azione può comunque dipendere da questa azione. Utile per disattivare temporaneamente le azioni non funzionanti.
hermetic boolean
Dichiara se questa azione è ermetica. Un'azione è ermetica se tutte le sue dipendenze vengono dichiarate esplicitamente.

Se questa azione dipende da dati provenienti da un'origine non dichiarata come dipendenza, quindi imposta hermetic su false. In caso contrario, imposta 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 il valore è impostato su true, l'esecuzione di questa azione ignora l'opzione full-refresh. È utile per le tabelle create a partire da dati temporanei, per non perdere mai i dati storici.
schema string
Lo schema (set di dati BigQuery) in cui crea 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 delle tabelle incrementali.

Se configurati, i record con chiavi univoche corrispondenti vengono anziché l'inserimento di nuove righe.

ITableContext

I metodi di contesto sono disponibili durante la valutazione di codice SQL contestuale, ad esempio all'interno di file SQLX o quando utilizzi un file Contextable con il core Dataform.

incremental () => boolean
Restituisce true quando il contesto corrente 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, che restituisce un codice SQL valido da usare 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 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 del database predefinito, con 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 "from".
self () => string
Equivalente a resolve(name()).

Restituisce una stringa SQL valida che può essere utilizzata come riferimento la 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 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");

Risolubile

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 della 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 le tabelle incrementali.