Dataform-Referenz

In diesem Dokument werden die Methoden, Eigenschaften und Konfigurationsoptionen von Dataform Core beschrieben. Sie können Dataform Core in SQLX- und JavaScript-Dateien verwenden.

assert()

assert (name: string, query?: AContextable)

Fügen Sie dem kompilierten Diagramm eine Dataform-Bestätigung hinzu.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

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

CommonContext

Kontextmethoden sind verfügbar, wenn kontextabhängiger SQL-Code ausgewertet wird, z. B. in SQLX-Dateien oder wenn ein Contextable-Argument mit dem Dataform-Kern verwendet wird.

database () => string
Gibt gegebenenfalls die Datenbank dieses Datensatzes zurück.
name () => string
Gibt den Namen dieser Tabelle zurück.
ref (ref: Resolvable | string[], rest: string[]) => string
Verweist auf eine andere Aktion, die dieser Aktion als Abhängigkeit hinzugefügt wird, und gibt gültige SQL-Anweisungen zurück, die in einem from-Ausdruck verwendet werden können.

Diese Funktion kann mit einem Resolvable-Objekt aufgerufen werden, z. B.: ${ref({ name: "name", schema: "schema", database: "database" })}

Diese Funktion kann auch mit einzelnen Argumenten für die Werte "database", "schema" und "name" aufgerufen werden. Wenn nur zwei Werte angegeben werden, wird die Standarddatenbank verwendet und die Werte werden als "schema" und "name" interpretiert. Wenn nur ein Wert angegeben wird, werden die Standarddatenbank und das Standardschema verwendet. Der angegebene Wert wird als „name“ interpretiert.

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Ähnlich wie ref, aber die referenzierte Aktion wird dieser Aktion nicht als Abhängigkeit hinzugefügt.
self () => string
Entspricht resolve(name()).

Gibt einen gültigen SQL-String zurück, der als Verweis auf die durch diese Aktion erstellte Tabelle verwendet werden kann.
schema () => string
Gibt das Schema dieses Datensatzes zurück.

Kontextbezogen

Kontextbezogene Argumente können entweder einen einfachen Wert für ihren generischen Typ T oder eine Funktion übergeben, die mit dem Kontextobjekt für diesen Vorgangstyp aufgerufen wird.

T | (ctx: Context) => T

Dataform

Globale Variable, die das IProjectConfig-Objekt enthält. Erforderlich zum Abrufen von IProjectConfig-Properties, z. B.:

dataform.projectConfig.vars.myVariableName === "myVariableValue"

declare()

declare (dataset: dataform.ITarget)

Das Dataset wird als Dataform-Datenquelle deklariert.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

declare({name: "a-declaration"})

IActionConfig

Hier werden Dataform-Tags und Abhängigkeiten definiert, die auf eine SQL-Workflow-Aktion angewendet werden.

tags string[]

Eine Liste mit benutzerdefinierten Tags, mit denen die Aktion getaggt werden soll.
dependencies Resolvable| Resolvable[]

Abhängigkeiten der Aktion.
disabled boolean

Wenn diese Option auf „true“ gesetzt ist, wird die Aktion nicht ausgeführt. Die Aktion kann jedoch weiterhin verwendet werden. Nützlich, um fehlerhafte Aktionen vorübergehend zu deaktivieren.

IAssertionConfig

Konfigurationsoptionen für assertion-Aktionstypen

database string
Die Datenbank (Google Cloud Projekt-ID), in der die entsprechende Ansicht für diese Behauptung erstellt werden soll.
description string
Eine Beschreibung dieser Behauptung.
disabled boolean
Wenn diese Option auf true festgelegt ist, wird diese Aktion nicht ausgeführt. Die Aktion kann weiterhin ausgeführt werden. Nützlich, um fehlerhafte Aktionen vorübergehend zu deaktivieren.
hermetic boolean
Gibt an, ob diese Aktion hermetisch ist. Eine Aktion ist hermetisch, wenn alle Abhängigkeiten explizit deklariert sind.

Wenn diese Aktion von Daten aus einer Quelle abhängt, die nicht als Abhängigkeit deklariert ist, setzen Sie hermetic auf false. Andernfalls setzen Sie true.

schema string
Das Schema (BigQuery-Dataset), in dem die entsprechende Ansicht für diese Behauptung erstellt werden soll.
tags string[]
Eine Liste der benutzerdefinierten Tags, die auf diese Aktion angewendet werden.

IBigQueryOptions

BigQuery-spezifische Warehouse-Optionen

additionalOptions
Schlüssel/Wert-Paare für die Optionen Tabelle, Ansicht und materialisierte Ansicht.

Einige Optionen, z. B. partitionExpirationDays, haben spezielle Felder für die Prüfung des Typs und der Gültigkeit. Verwenden Sie für solche Optionen die dafür vorgesehenen Felder.

Stringwerte müssen in doppelte Anführungszeichen gesetzt werden, z. B.: additionalOptions: {numeric_option: "5", string_option: '"string-value"'}

Wenn der Optionsname Sonderzeichen enthält, setzen Sie ihn in Anführungszeichen, z. B. additionalOptions: { "option-name": "value" }.
clusterBy string[]
Die Schlüssel, nach denen Partitionen gruppiert werden.
labels
Schlüssel/Wert-Paare für BigQuery-Labels.

Wenn der Labelname Sonderzeichen wie Bindestrich enthält, setzen Sie ihn in Anführungszeichen, z. B. labels: { "label-name": "value" }..
partitionBy string
Der Schlüssel, nach dem die Tabelle partitioniert wird. In der Regel der Name eines Zeitstempels oder der Datumsspalte.
partitionExpirationDays number
Die Anzahl der Tage, für die BigQuery Daten in jeder Partition speichert. Die Einstellung gilt für alle Partitionen in einer Tabelle, wird jedoch für jede Partition separat basierend auf der Partitionszeit berechnet.
requirePartitionFilter boolean
Gibt an, ob für die partitionierte Tabelle ein Prädikatfilter der WHERE-Klausel erforderlich ist, der die Partitionierungsspalte filtert.
updatePartitionFilter string
SQL-basierter Filter für die Anwendung von inkrementellen Updates.

IColumnsDescriptor

Beschreibt Spalten in einer Tabelle.

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

Konfigurationsoptionen für declaration-Aktionstypen

columns IColumnsDescriptor
Eine Beschreibung der Spalten in der Tabelle.
database string
Die Datenbank (Google Cloud Projekt-ID), in der die Quelltabelle erstellt werden soll, muss vorhanden sein.
description string
Eine Beschreibung der Tabelle.
schema string
Das Schema (BigQuery-Dataset), in dem sich die Quelltabelle befindet.

IDependenciesConfig

Hiermit werden Abhängigkeiten einer SQL-Workflow-Aktion definiert.

dependencies Resolvable| Resolvable[]

Eine oder mehrere explizite Abhängigkeiten für diese Aktion. Abhängigkeitsaktionen werden vor abhängigen Aktionen ausgeführt. Normalerweise bleibt diese Option deaktiviert, da die meisten Abhängigkeiten als Nebenprodukt der Verwendung der Funktion ref deklariert werden.
hermetic boolean

Gibt an, ob diese Aktion hermetisch ist. Eine Aktion ist hermetisch, wenn alle Abhängigkeiten explizit deklariert sind. Wenn diese Aktion von Daten aus einer Quelle abhängt, die nicht als Abhängigkeit deklariert wurde, sollte hermetic explizit auf false gesetzt werden. Andernfalls, wenn diese Aktion nur von Daten aus explizit deklarierten Abhängigkeiten abhängt, sollte sie auf true festgelegt werden.

IDocumentableConfig

Hier werden Beschreibungen für einen Datensatz und seine Spalten definiert.

columns IColumnsDescriptor

Eine Beschreibung der Spalten im Datensatz.
description string

Eine Beschreibung des Datensatzes.

INamedConfig

Hiermit werden der Typ und der Name einer SQL-Workflow-Aktion definiert.

type string

Der Aktionstyp.
name string

Der Name der Aktion.

IOperationConfig

Konfigurationsoptionen für operations-Aktionstypen

columns IColumnsDescriptor
Eine Beschreibung der Spalten in der Tabelle.
database string
Die Datenbank (Google Cloud Projekt-ID), in der die Ausgabe dieser Aktion erstellt werden soll.
description string
Eine Beschreibung der Tabelle.
disabled boolean
Wenn diese Option auf true festgelegt ist, wird diese Aktion nicht ausgeführt. Die Aktion kann weiterhin ausgeführt werden. Nützlich, um fehlerhafte Aktionen vorübergehend zu deaktivieren.
hasOutput boolean
Hiermit wird erklärt, dass durch diese operations-Aktion eine Tabelle erstellt wird, auf die mithilfe der Funktion ref verwiesen werden kann.

Wenn diese Aktion auf true festgelegt ist, wird mithilfe der Kontextfunktion self() eine Tabelle mit dem konfigurierten Namen erstellt.

Beispiel: create or replace table ${self()} as select ...
hermetic boolean
Gibt an, ob diese Aktion hermetisch ist. Eine Aktion ist hermetisch, wenn alle Abhängigkeiten explizit deklariert sind.

Wenn diese Aktion von Daten aus einer Quelle abhängt, die nicht als Abhängigkeit deklariert ist, setzen Sie hermetic auf false. Andernfalls setzen Sie true.
schema string
Das Schema (BigQuery-Dataset), in dem die Ausgabe dieser Aktion erstellt werden soll.
tags string[]
Eine Liste der benutzerdefinierten Tags, die auf diese Aktion angewendet werden.

IProjectConfig

Enthält die Kompilierungseinstellungen eines Dataform-Repositorys.

defaultDatabase string
Erforderlich. Die Standarddatenbank (Google Cloud Projekt-ID).
defaultSchema string
Erforderlich. Das Standardschema (BigQuery-Dataset-ID).
defaultLocation string
Erforderlich. Der zu verwendende BigQuery-Standardstandort. Weitere Informationen zu BigQuery-Standorten finden Sie unter https://cloud.google.com/bigquery/docs/locations.
assertionSchema string
Erforderlich. Das Standardschema (BigQuery-Dataset-ID) für Behauptungen.
vars map (key: string, value: string)
Optional. Benutzerdefinierte Variablen, die während der Kompilierung dem Projektcode zur Verfügung gestellt werden. Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
databaseSuffix string
Optional. Das Suffix, das an alle Datenbanknamen (Google Cloud Projekt-ID) angehängt werden soll.
schemaSuffix string
Optional. Das Suffix, das an alle Schemanamen (BigQuery-Dataset-ID) angehängt werden soll.
tablePrefix string
Optional. Das Präfix, das allen Tabellennamen vorangestellt werden soll.
warehouse string
Erforderlich. Dieses Feld muss auf bigquery festgelegt sein.

Sie können IProjectConfig-Attribute in den Workflow-Einstellungen auf Repository-Ebene festlegen.

Sie können die defaultSchema- und defaultDatabase-Eigenschaften für einzelne Tabellen überschreiben.

Sie können in einer SQLX- oder JavaScript-Datei in einer SQL-SELECT-Anweisung auf alle IProjectConfig-Eigenschaften zugreifen.

Im folgenden Codebeispiel wird die benutzerdefinierte myVariableName-Kompilierungsvariable gezeigt, die in den Workflow-Einstellungen mit der Eigenschaft projectConfig.vars festgelegt wurde und in einer SQLX-Datei in einer SELECT-Anweisung verwendet wird:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Weitere Informationen zum Überschreiben der Projektkonfigurationseinstellungen für einzelne Kompilierungsergebnisse finden Sie in der REST-Ressource projects.locations.repositories.compilationResults#CodeCompilationConfig in der Dataform API.

IRecordDescriptor

Beschreibt ein Struktur-, Objekt- oder Datensatzelement in einer Tabelle mit verschachtelten Spalten.

bigqueryPolicyTags string | string[]
Vollständige IDs der BigQuery-Richtlinien-Tags, die auf diese Spalte angewendet werden. Eine vollständige Kennung eines BigQuery-Richtlinien-Tags enthält den Projektnamen, den Standort und die Taxonomie.

Beispiel: "projects/1/locations/eu/taxonomies/2/policyTags/3"

In BigQuery ist nur ein Tag pro Spalte zulässig.
columns IColumnsDescriptor
Eine Beschreibung der Spalten innerhalb des Typs „struct“, des Objekts oder des Datensatzes.
description string
Eine Beschreibung des Typs, Objekts oder Datensatzes.

ITableAssertions

Optionen zum Erstellen von Behauptungen als Teil einer Tabellendefinition.

nonNull string | string[]
Spalten, die niemals NULL sein können.

Wenn diese Option festgelegt ist, schlägt die entsprechende Prüfung fehl, wenn eine Zeile NULL-Werte für diese Spalte(n) enthält.
rowConditions string[]
Allgemeine Bedingungen, die für alle Zeilen in der Tabelle gelten müssen.

Wenn diese Option festgelegt ist, schlägt die entsprechende Prüfung fehl, wenn eine Zeile gegen eine dieser Bedingungen verstößt.
uniqueKey string | string[]
Spalte(n), die den eindeutigen Schlüsselindex der Tabelle bilden.

Wenn diese Option festgelegt ist, schlägt die resultierende Prüfung fehl, wenn die Tabelle mehr als eine Zeile mit denselben Werten für alle Spalten enthält.
uniqueKeys []
Kombinationen von Spalten, von denen jede einen eindeutigen Schlüsselindex der Tabelle darstellt.

Wenn diese Option festgelegt ist, schlägt die resultierende Prüfung fehl, wenn die Tabelle mehr als eine Zeile mit denselben Werten für alle Spalten in den eindeutigen Schlüsseln enthält.

ITableConfig

Konfigurationsoptionen für table-Aktionen, einschließlich der Tabellentypen table, view und incremental.

Erweitert IActionConfig, IDependenciesConfig, IDocumentableConfig, INamedConfig und ITargetableConfig.

assertions ITableAssertions
Behauptungen, die für die Tabelle ausgeführt werden sollen.

Wenn sie konfiguriert sind, werden entsprechende Behauptungen automatisch erstellt und als Abhängigkeit dieser Tabelle ausgeführt.
bigquery IBigQueryOptions
BigQuery-spezifische Warehouse-Optionen
columns IColumnsDescriptor
Eine Beschreibung der Spalten in der Tabelle.
database string
Die Datenbank (Google Cloud Projekt-ID), in der die Ausgabe dieser Aktion erstellt werden soll.
description string
Eine Beschreibung der Tabelle.
disabled boolean
Wenn diese Option auf true festgelegt ist, wird diese Aktion nicht ausgeführt. Die Aktion kann weiterhin ausgeführt werden. Nützlich, um fehlerhafte Aktionen vorübergehend zu deaktivieren.
hermetic boolean
Gibt an, ob diese Aktion hermetisch ist. Eine Aktion ist hermetisch, wenn alle Abhängigkeiten explizit deklariert sind.

Wenn diese Aktion von Daten aus einer Quelle abhängt, die nicht als Abhängigkeit deklariert ist, setzen Sie hermetic auf false. Andernfalls setzen Sie true.
materialized boolean
Nur gültig, wenn der Tabellentyp view ist.

Wenn diese Option auf „true“ gesetzt ist, wird eine materialisierte Ansicht erstellt.
protected boolean
Nur für den Tabellentyp incremental zulässig.

Wenn dieser Wert auf „true“ gesetzt ist, wird beim Ausführen dieser Aktion die Option full-refresh ignoriert. Das ist nützlich für Tabellen, die aus sitzungsspezifischen Daten erstellt werden, damit Verlaufsdaten nicht verloren gehen.
schema string
Das Schema (BigQuery-Dataset), in dem die Ausgabe dieser Aktion erstellt werden soll.
tags string[]
Eine Liste der benutzerdefinierten Tags, die auf diese Aktion angewendet werden.
type TableType
Der Typ der Tabelle.
uniqueKey string[]
Eindeutige Schlüssel für Zusammenführungskriterien für inkrementelle Tabellen.

Wenn dies konfiguriert ist, werden Einträge mit übereinstimmenden eindeutigen Schlüsseln aktualisiert, anstatt neue Zeilen einzufügen.

ITableContext

Kontextmethoden sind verfügbar, wenn kontextabhängiger SQL-Code ausgewertet wird, z. B. in SQLX-Dateien oder wenn ein Contextable-Argument mit dem Dataform-Kern verwendet wird.

incremental () => boolean
Gibt „wahr“ zurück, wenn der aktuelle Kontext angibt, dass die Tabelle inkrementell erstellt wird.
name () => string
Gibt den voll qualifizierten Namen dieser Tabelle zurück.
ref (ref: Resolvable | string[], rest: string[]) => string
Verweist auf eine andere Aktion, fügt sie dieser Aktion als Abhängigkeit hinzu und gibt gültige SQL-Anweisungen zurück, die in einem From-Ausdruck verwendet werden können.

Diese Funktion kann mit einem Resolvable-Objekt aufgerufen werden, z. B. so:

${ref({ name: "name", schema: "schema", database: "database" })}

Diese Funktion kann auch mit einzelnen Argumenten für die Werte "database", "schema" und "name" aufgerufen werden.

Wenn nur zwei Werte angegeben werden, wird die Standarddatenbank verwendet und die Werte werden als "schema" und "name" interpretiert.

Wenn nur ein Wert angegeben wird, wird das Standarddatenbankschema verwendet und der angegebene Wert wird als „name“ interpretiert.

${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}
resolve (ref: Resolvable | string[], rest: string[]) => string
Ähnlich wie ref, aber anstatt eine Abhängigkeit hinzuzufügen, wird die angegebene Referenz aufgelöst, damit sie in SQL verwendet werden kann, z. B. in einem „from“-Ausdruck.
self () => string
Entspricht resolve(name()).

Gibt einen gültigen SQL-String zurück, mit dem auf die durch diese Aktion erstellte Tabelle verwiesen werden kann.
when (cond: boolean, trueCase: string, falseCase: string) => string
Kurzschreibweise für eine if -Bedingung. Entspricht cond ? trueCase : falseCase.

falseCase ist optional und hat standardmäßig den Wert „leer“.

ITarget

Ein Verweis auf eine Tabelle in BigQuery.

database string
name string
schema string

ITargetableConfig

Definiert die Zieldatenbank und das Zielschema einer SQL-Workflow-Aktion.

database string

Die Datenbank, in der die Ausgabe dieser Aktion erstellt werden soll. Muss auf „BigQuery“ festgelegt sein.
schema string

Das Schema, in dem die Ausgabe dieser Aktion erstellt werden soll.

operate()

operate (name: string, queries?: Contextable)

Definiert einen SQL-Vorgang.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

Erstellt eine Tabelle oder Ansicht.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

Behebbar

Ein auflösbarer Wert kann entweder der Name einer Tabelle wie string oder das Objekt sein, das den vollständigen Pfad zur Beziehung beschreibt.

string | ITarget

TableType

Unterstützte Arten von Tabellenaktionen.

Tabellen vom Typ view werden als Ansichten erstellt.

Tabellen vom Typ table werden als Tabellen erstellt.

Tabellen vom Typ incremental müssen eine where-Klausel enthalten. Weitere Informationen finden Sie unter Inkrementelle Tabellen konfigurieren.