Dataform-Kernreferenz

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ügt der kompilierten Grafik eine Dataform-Assertion hinzu.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

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

CommonContext

Kontextmethoden sind für die Auswertung von kontextsensitivem SQL-Code verfügbar, z. B. in SQLX-Dateien oder bei Verwendung eines Contextable-Arguments mit Dataform Core.

`database`	`() => string`
	Gibt die Datenbank dieses Datasets zurück, falls zutreffend.
`name`	`() => string`
	Gibt den Namen dieser Tabelle zurück.
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	Verweist auf eine andere Aktion und fügt sie als Abhängigkeit hinzu. Dadurch wird eine gültige SQL-Anweisung zurückgegeben, die in einem `from`-Ausdruck verwendet werden kann. Diese Funktion kann mit einem `Resolvable`-Objekt aufgerufen werden. Beispiel: `${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 sind, wird die Standarddatenbank verwendet und die Werte als `"schema"` und `"name"` interpretiert. Wenn nur ein Wert angegeben ist, 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`, fügt die referenzierte Aktion jedoch nicht als Abhängigkeit zu dieser Aktion hinzu.
`self`	`() => string`
	Entspricht `resolve(name())`. Gibt einen gültigen SQL-String zurück, mit dem auf die von dieser Aktion erstellte Tabelle verwiesen werden kann.
`schema`	`() => string`
	Gibt das Schema dieses Datasets zurück.

Kontextierbar

Kontextfähige Argumente können entweder einen einfachen Wert für ihren generischen Typ T oder eine Funktion übergeben, die mit dem Kontextobjekt für diese Art von Vorgang aufgerufen wird.

T | (ctx: Context) => T

Dataform

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

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

declare()

declare (dataset: dataform.ITarget)

Deklariert das Dataset als Dataform-Datenquelle.

Nur im Verzeichnis /definitions verfügbar.

Beispiel:

// definitions/file.js

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

IActionConfig

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

`tags`	`string[]`
	Eine Liste von benutzerdefinierten Tags, mit denen die Aktion gekennzeichnet werden soll.
`dependencies`	`Resolvable\| Resolvable[]`
	Abhängigkeiten der Aktion.
`disabled`	`boolean`
	Ist die Richtlinie auf „true“ gesetzt, wird diese Aktion nicht ausgeführt. Die Aktion kann jedoch weiterhin genutzt 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 Assertion erstellt werden soll.
`description`	`string`
	Eine Beschreibung dieser Assertion.
`disabled`	`boolean`
	Wenn `true` festgelegt ist, wird diese Aktion nicht ausgeführt. Es ist immer noch möglich, von dieser Aktion abhängig zu sein. 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 legen Sie `true` fest.
`schema`	`string`
	Das Schema (BigQuery-Dataset), in dem die entsprechende Ansicht für diese Assertion 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. Für einige Optionen, z. B. `partitionExpirationDays`, gibt es spezielle Felder, bei denen die Art/Gültigkeit geprüft wurde. Verwenden Sie für solche Optionen die entsprechenden Felder. Stringwerte müssen in doppelte Anführungszeichen gekapselt werden, z. B.: `additionalOptions: {numeric_option: "5"`, `string_option: '"string-value"'}`. Wenn der Optionsname Sonderzeichen enthält, setzen Sie den Namen in Anführungszeichen, z. B. `additionalOptions: { "option-name": "value" }`.
`clusterBy`	`string[]`
	Die Schlüssel, nach denen partitioniert werden soll.
`labels`
	Schlüssel/Wert-Paare für BigQuery-Labels. Wenn der Labelname Sonderzeichen (z. B. Bindestriche) enthält, setzen Sie den Namen in Anführungszeichen, z. B. `labels: { "label-name": "value" }.`.
`partitionBy`	`string`
	Der Schlüssel, nach dem die Tabelle partitioniert werden soll. In der Regel der Name eines Zeitstempels oder der Datumsspalte.
`partitionExpirationDays`	`number`
	Die Anzahl der Tage, an denen BigQuery Daten in jeder Partition speichert. Die Einstellung gilt für alle Partitionen in einer Tabelle, wird jedoch für jede Partition basierend auf der Partitionszeit unabhängig berechnet.
`requirePartitionFilter`	`boolean`
	Gibt an, ob für die partitionierte Tabelle ein Prädikatfilter der `WHERE`-Klausel erforderlich ist, mit dem die Partitionierungsspalte gefiltert wird.
`updatePartitionFilter`	`string`
	SQL-basierter Filter, der angibt, wann inkrementelle Updates angewendet werden.

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.
`description`	`string`
	Eine Beschreibung der Tabelle.
`schema`	`string`
	Das Schema (BigQuery-Dataset), in dem die Quelltabelle vorhanden ist.

IDependenciesConfig

Definiert Abhängigkeiten einer SQL-Workflow-Aktion.

`dependencies`	`Resolvable\| Resolvable[]`
	Eine oder mehrere explizite Abhängigkeiten für diese Aktion. Abhängigkeitsaktionen werden vor abhängigen Aktionen ausgeführt. In der Regel würde dies nicht konfiguriert werden, da die meisten Abhängigkeiten als Nebenprodukt bei 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. Wenn diese Aktion nur von Daten aus explizit deklarierten Abhängigkeiten abhängt, sollte sie auf `true` gesetzt werden.

IDocumentableConfig

Definiert Beschreibungen eines Datasets und seiner Spalten.

`columns`	`IColumnsDescriptor`
	Eine Beschreibung der Spalten im Dataset.
`description`	`string`
	Eine Beschreibung des Datasets.

INamedConfig

Definiert den Typ und den Namen einer SQL-Workflow-Aktion.

`type`	`string`
	Der Typ der Aktion.
`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 `true` festgelegt ist, wird diese Aktion nicht ausgeführt. Es ist immer noch möglich, von dieser Aktion abhängig zu sein. Nützlich, um fehlerhafte Aktionen vorübergehend zu deaktivieren.
`hasOutput`	`boolean`
	Deklariert, dass mit der Aktion `operations` eine Tabelle erstellt wird, die mithilfe der Funktion `ref` referenzierbar ist. Wenn `true` festgelegt ist, wird mit dieser Aktion unter Verwendung der Kontextfunktion `self()` eine Tabelle mit ihrem 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 legen Sie `true` fest.
`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 Standard-BigQuery-Speicherort. 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 Assertions.
`vars`	`map (key: string, value: string)`
	Optional. Benutzerdefinierte Variablen, die dem Projektcode während der Kompilierung 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 sollte.
`warehouse`	`string`
	Erforderlich. Muss auf `bigquery` festgelegt werden.

Sie können IProjectConfig-Attribute in dataform.json auf Repository-Ebene festlegen.

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

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

Das folgende Codebeispiel zeigt die benutzerdefinierte Kompilierungsvariable myVariableName, die in dataform.json mit dem Attribut projectConfig.vars festgelegt und in einer SELECT-Anweisung in einer SQLX-Datei aufgerufen 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 Dataform API in der REST-Ressource projects.locations.repositories.compilationResults#CodeCompilationConfig.

IRecordDescriptor

Beschreibt eine Struktur, ein Objekt oder einen Datensatz in einer Tabelle mit verschachtelten Spalten.

`bigqueryPolicyTags`	`string \| string[]`
	Vollständige Kennungen der BigQuery-Richtlinien-Tags, die auf diese Spalte angewendet werden. Die 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"` Derzeit unterstützt BigQuery ein Tag pro Spalte.
`columns`	`IColumnsDescriptor`
	Eine Beschreibung der Spalten innerhalb der Struktur, des Objekts oder des Datensatzes.
`description`	`string`
	Eine Beschreibung der Struktur, des Objekts oder des Datensatzes.

ITableAssertions

Optionen zum Erstellen von Assertions als Teil einer Tabellendefinition.

`nonNull`	`string \| string[]`
	Spalte(n), die nicht `NULL` sein darf. Wenn festgelegt, schlägt die entsprechende Assertion 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 zutreffen sollten. Wenn festgelegt, schlägt die entsprechende Assertion fehl, wenn eine Zeile gegen eine dieser Bedingungen verstößt.
`uniqueKey`	`string \| string[]`
	Spalte(n), die den eindeutigen Schlüsselindex der Tabelle bildet. Wenn festgelegt, schlägt die resultierende Assertion 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 festgelegt, schlägt die resultierende Assertion 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`
	Assertions, die für die Tabelle ausgeführt werden sollen Wenn konfiguriert, werden relevante Assertions 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 `true` festgelegt ist, wird diese Aktion nicht ausgeführt. Es ist immer noch möglich, von dieser Aktion abhängig zu sein. 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 legen Sie `true` fest.
`materialized`	`boolean`
	Nur gültig, wenn der Tabellentyp `view` ist. Wenn die Richtlinie auf „true“ gesetzt ist, wird eine materialisierte Ansicht erstellt.
`protected`	`boolean`
	Nur zulässig für den Tabellentyp `incremental` . Wenn die Richtlinie auf „true“ gesetzt ist, wird die Option `full-refresh` beim Ausführen dieser Aktion ignoriert. Dies ist nützlich für Tabellen, die aus transienten Daten erstellt werden, um sicherzustellen, dass historische Daten nie 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 konfiguriert, werden Datensätze mit übereinstimmenden eindeutigen Schlüsseln aktualisiert, anstatt neue Zeilen eingefügt zu werden.

ITableContext

Kontextmethoden sind für die Bewertung von kontextsensitivem SQL-Code verfügbar, z. B. in SQLX-Dateien oder bei Verwendung eines Contextable-Arguments mit Dataform Core.

`incremental`	`() => boolean`
	Gibt „true“ zurück, wenn der aktuelle Kontext anzeigt, 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 und fügt sie als Abhängigkeit hinzu. Dadurch wird eine gültige SQL-Anweisung zurückgegeben, die in einem "Von"-Ausdruck verwendet werden kann. Diese Funktion kann mit einem `Resolvable`-Objekt aufgerufen werden. Beispiel: `${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 sind, wird die Standarddatenbank verwendet und die Werte als `"schema"` und `"name"` interpretiert. Wenn nur ein Wert angegeben ist, wird das Standarddatenbankschema verwendet, wobei der bereitgestellte Wert als"Name" interpretiert wird. `${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 der angegebene Verweis aufgelöst, damit er 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 von dieser 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 standardmäßig ein leerer String.

ITarget

Ein Verweis auf eine Tabelle in BigQuery.

`database`	`string`
`name`	`string`
`schema`	`string`

ITargetableConfig

Definiert die Zieldatenbank und das Schema 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.

Operation()

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

Auflösbar

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

string | ITarget

TableType

Unterstützte Typen 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.