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 si valuta il codice SQL contestualizzabile, ad esempio all'interno di file SQLX, o quando si utilizza 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 argomenti individuali 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.

Contextable

Gli argomenti contestualizzabili possono passare un valore semplice per il tipo generico T o una funzione 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"

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

defaultLocation

La proprietà defaultLocation specifica la località predefinita del set di dati BigQuery. Dataform utilizza questa località per elaborare il codice e archiviare i risultati. Questa località di elaborazione deve corrispondere a quella dei tuoi set di dati BigQuery. Tuttavia, non deve corrispondere alla posizione del repository Dataform.

Se non imposti la proprietà defaultLocation, Dataform determina la posizione in base ai set di dati a cui fa riferimento la query SQL. Ecco come funziona:

• Se la query fa riferimento a set di dati della stessa località, Dataform utilizza quella località.
• Se la query fa riferimento a set di dati di due o più località diverse, si verifica un errore. Per informazioni dettagliate su questa limitazione, consulta Replica dei set di dati tra regioni.
• Se la query non fa riferimento ad alcun set di dati, la località predefinita per Dataform è la multi-regione US. Per scegliere una località diversa, imposta la proprietà defaultLocation. In alternativa, utilizza la variabile di sistema @@location nella query.

Per saperne di più, consulta Specifica le località.

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 l'azione deve essere etichettata.
dependencies	Resolvable| Resolvable[]
	Dipendenze dell'azione.
disabled	boolean
	Se impostata su true, questa azione non verrà eseguita. Tuttavia, l'azione può comunque essere utilizzata. Utile per disattivare temporaneamente le azioni non funzionanti.

IAssertionConfig

Opzioni di configurazione per i tipi di azioni assertion.

database	string
	Il database (ID progettoGoogle Cloud ) in cui creare la vista corrispondente per questa asserzione.
description	string
	Una descrizione di questa asserzione.
disabled	boolean
	Se impostata su true, questa azione non viene eseguita. L'azione può ancora essere utilizzata. 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 di un'origine 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 di BigQuery.

additionalOptions
	Coppie chiave/valore per le opzioni table, view e vista materializzata. Alcune opzioni, ad esempio partitionExpirationDays, hanno campi dedicati per il controllo del tipo e della 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, racchiudilo 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 tempo di 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 gli aggiornamenti incrementali.
iceberg	IIcebergOptions
	Opzioni specifiche di Apache Iceberg per le tabelle Iceberg gestite.

IIcebergOptions

Opzioni specifiche di Apache Iceberg per le tabelle Iceberg gestite.

connection	string
	Facoltativo. Il nome della risorsa della connessione Cloud Storage, che fornisce le credenziali per la lettura e la scrittura nell'unità di archiviazione esterna. Può essere formattato nei seguenti modi: PROJECT_ID.LOCATION.CONNECTION_ID Sostituisci i seguenti valori: PROJECT_ID: l' Google Cloud ID progetto LOCATION: il nome della località della connessione CONNECTION_ID: il nome o l'ID della connessione projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID DEFAULT Il valore predefinito è DEFAULT. Per saperne di più, consulta la Panoramica della connessione predefinita.
file_format	string
	Facoltativo. Il formato file per i dati della tabella. È supportato soltanto l'ID PARQUET. Il valore predefinito è PARQUET.
bucket_name	string
	Obbligatorio a livello di tabella o workflow. Il nome del bucket Cloud Storage in cui sono archiviati i dati della tabella. Devi fornire bucket_name nel blocco config del file di definizione della tabella oppure impostare un valore predefinito a livello di workflow nel file workflow_settings.yaml. Se non viene fornito nessuno dei due, la compilazione non riesce. Per ulteriori informazioni, consulta Configura i valori predefiniti a livello di workflow per le tabelle Iceberg .
table_folder_root	string
	Facoltativo. Il nome della cartella di primo livello all'interno del bucket Cloud Storage in cui sono archiviati i dati della tabella. Se non imposti questa proprietà, Dataform utilizza il valore predefinito a livello di workflow di workflow_settings.yaml, se impostato. In caso contrario, il valore predefinito è _dataform.
table_folder_subpath	string
	Facoltativo. Una sottocartella all'interno di tableFolderRoot. Se non imposti questa proprietà, Dataform utilizza il valore predefinito a livello di workflow di workflow_settings.yaml, se impostato. Se non vengono impostate né la proprietà né un valore predefinito a livello di workflow, il percorso secondario predefinito è DATASET_NAME/TABLE_NAME.

Questi valori creano l'URI Cloud Storage nel seguente formato: gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH.

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 della tabella.
database	string
	Il database (ID progettoGoogle Cloud ) in cui esiste 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 workflow.

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 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 esplicitamente. Se questa azione dipende da 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 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 impostata 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 (ID progettoGoogle Cloud ).
defaultSchema	string
	Obbligatorio. Lo schema predefinito (ID set di dati BigQuery).
defaultLocation	string
	Facoltativo. La località BigQuery predefinita in cui Dataform crea le tabelle.
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 degli schemi (ID set di dati BigQuery).
tablePrefix	string
	Facoltativo. Il prefisso da aggiungere all'inizio di tutti i nomi delle tabelle.
defaultIcebergConfig	object
	Facoltativo. Valori predefiniti a livello di workflow per le tabelle gestite Apache Iceberg. Contiene i seguenti campi: bucketName: (Facoltativo) Il nome predefinito del bucket Cloud Storage. tableFolderRoot: (Facoltativo) Il nome predefinito della cartella di primo livello all'interno del bucket Cloud Storage. tableFolderSubpath: (Facoltativo) Il nome predefinito di una sottocartella all'interno di tableFolderRoot. Per ulteriori informazioni, vedi Configurare i valori predefiniti a livello di flusso di lavoro per le tabelle Iceberg.
preserveGovernanceControls	boolean
	Facoltativo. Se impostato su true, Dataform conserva automaticamente le policy dei dati e i tag di governance dei dati (anteprima) di BigQuery esistenti in tutte le esecuzioni del workflow per tutte le tabelle nel repository.
warehouse	string
	Obbligatorio. Deve essere impostato su bigquery.

Puoi impostare le proprietà IProjectConfig nelle impostazioni del workflow 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 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 saperne di più sull'override delle impostazioni di configurazione del progetto per i singoli risultati di compilazione, consulta la risorsa REST 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 policy 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 di 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[]
	Condizioni generali che devono essere soddisfatte per tutte le righe della tabella. Se impostata, l'asserzione corrispondente non va a buon fine se una riga viola una di queste condizioni.
uniqueKey	string | string[]
	Le colonne che costituiscono l'indice della chiave univoca della tabella. Se impostata, l'asserzione risultante non va a buon fine 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 va a buon fine 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 tabella 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 ed eseguite automaticamente come dipendenza di questa tabella.
bigquery	IBigQueryOptions
	Opzioni di warehouse specifiche di BigQuery.
columns	IColumnsDescriptor
	Una descrizione delle colonne 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 l'impostazione è 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 esplicitamente. Se questa azione dipende da dati di un'origine 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 impostato su true, verrà creata una vista materializzata.
onSchemaChange	onSchemaChange
	Valido solo quando il tipo di tabella è incremental. L'azione eseguita dopo che Dataform controlla la query SELECT per determinare se sono state aggiunte o rimosse colonne. Questa funzionalità è in anteprima.
preserveGovernanceControls	boolean
	Facoltativo. Se impostato su true, Dataform esegue il backup e riapplica i tag esistenti di policy dei dati e governance dei dati di BigQuery (anteprima) durante la ricreazione di una tabella, una vista o una tabella incrementale durante un aggiornamento completo. Esegue l'override dei valori predefiniti a livello di workflow impostati in workflow_settings.yaml.
protected	boolean
	Consentito solo per il tipo di tabella incremental . Se impostata 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 configurata, i record con chiavi univoche corrispondenti vengono aggiornati anziché inserire nuove righe.

ITableContext

I metodi di contesto sono disponibili quando si valuta il codice SQL contestualizzabile, ad esempio all'interno dei file SQLX, o quando si utilizza 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 workflow.

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.

onSchemaChange

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per fornire un feedback o richiedere assistenza, contatta [e-mail].

Dopo aver impostato la proprietà onSchemaChange, Dataform controlla la query SELECT per determinare se le colonne sono state aggiunte o rimosse. Dataform esegue quindi l'azione specificata dal valore della proprietà onSchemaChange. Puoi impostare l'azione su uno dei seguenti valori:

• IGNORE (predefinito): ignora le colonne aggiunte e mostra un errore per le colonne mancanti. Se onSchemaChange non è impostato, questo è il comportamento predefinito quando lo schema cambia.
• FAIL: interrompe l'azione se Dataform rileva una modifica dello schema, il che contribuisce a mantenere lo schema coerente.
• EXTEND: aggiunge nuove colonne dalla query alla tabella incrementale e aggiunge i valori NULL per i record precedenti. Mostra un errore se una colonna viene rimossa o manca dallo schema originale nella query. Puoi utilizzare questa impostazione per aggiungere nuove colonne alle tabelle incrementali durante il runtime.

• SYNCHRONIZE: aggiunge nuove colonne dalla query alla tabella incrementale e aggiunge valori NULL per i record precedenti. Rimuove le colonne che si trovavano nello schema originale, ma che ora non sono presenti nella query corrente.

  Attenzione: l'azione SYNCHRONIZE non può essere annullata e potresti perdere dati quando rimuovi colonne con questa opzione.
  Nota: l'eliminazione di colonne partizionate e in cluster non è supportata, in quanto può avere conseguenze negative. Se una colonna partizionata o raggruppata in cluster è ancora eliminata, viene gestita con l'istruzione ALTER TABLE DROP COLUMN. Dataform non esegue controlli o convalide per impedire l'esecuzione di istruzioni ALTER TABLE DROP COLUMN su colonne partizionate o raggruppate in cluster. Pertanto, se elimini queste colonne, procedi con cautela e tieni presente le potenziali conseguenze negative.

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 vista. 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 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 saperne di più, consulta Configura una tabella incrementale.