Riferimento principale Dataform

Questo documento descrive i metodi, le proprietà e le opzioni di configurazione del core Dataform. Puoi usare 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 durante la valutazione di codice SQL contestualizzabile, ad esempio all'interno di 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 della tabella.
ref (ref: Resolvable | string[], rest: string[]) => string
Fa riferimento a un'altra azione, aggiungendola come dipendenza a questa azione, restituendo un codice 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 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 l'azione a cui viene fatto 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 passare un valore normale per il tipo generico T o una funzione che viene chiamata 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"

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

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 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ò essere ancora dipendente. 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 asserzione.
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 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 dai dati di un'origine che non è dichiarata come dipendenza, 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 asserzione.
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 le opzioni tabella, vista e vista materializzata.

Per alcune opzioni, ad esempio partitionExpirationDays, sono presenti campi dedicati per il tipo/convalida controllati. 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, cita il nome, ad esempio labels: { "label-name": "value" }.
partitionBy string
La chiave per 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 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 tempo di partizione.
requirePartitionFilter boolean
Dichiara se la tabella partizionata richiede un filtro del predicato WHERE che filtra la colonna di partizionamento.
updatePartitionFilter string
Filtro basato su SQL per l'applicazione degli 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.
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. Le azioni di dipendenza verranno eseguite prima di quelle dipendenti. In genere questo comportamento rimarrebbe non impostato, perché la maggior parte delle dipendenze è dichiarata come un sottoprodotto dell'utilizzo 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 dai dati di un'origine che non è stata dichiarata come dipendenza, allora 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 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 utilizzando la funzione ref.

Se il valore è 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 vengono dichiarate esplicitamente.

Se questa azione dipende dai dati di un'origine che non è dichiarata come dipendenza, 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 la pagina 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 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
Facoltativo. Il suffisso da aggiungere a tutti i nomi di database (ID progetto Google Cloud).
schemaSuffix string
Facoltativo. Il suffisso da aggiungere a tutti i nomi degli schemi (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 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 saperne di più sull'override delle impostazioni di configurazione del progetto per i singoli risultati delle compilazioni, consulta la risorsa REST projects.locations.repositories.compilationResults#CodeCompilationConfig nell'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. L'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 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 valori NULL per queste colonne.
rowConditions string[]
Condizioni generali che devono essere soddisfatte per tutte le righe della tabella.

Se impostata, l'asserzione corrispondente ha esito negativo se una riga viola una di queste condizioni.
uniqueKey string | string[]
Colonne che costituiscono l'indice chiave univoco della tabella.

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

Se impostata, l'asserzione risultante ha esito negativo 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, tra cui i 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 ed eseguite automaticamente come dipendenza.
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 dai dati di un'origine che non è dichiarata come dipendenza, 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. Ciò è utile per le tabelle create a partire 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 delle tabelle incrementali.

Se configurati, i record con chiavi univoche corrispondenti vengono aggiornati invece di inserire nuove righe.

ITableContext

I metodi di contesto sono disponibili durante la valutazione di codice SQL contestualizzabile, ad esempio all'interno dei file SQLX, o quando si utilizza un argomento 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, restituendo un codice 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 del 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
In modo 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 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 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.

operare()

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 oppure 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, consulta Configurare le tabelle incrementali.