Tabellen erstellen

In Dataform ist eine Tabelle einer der Objekttypen, aus denen ein Workflow besteht. Sie können Tabellen erstellen, die auf Daten aus den für Ihren Workflow deklarierten Datenquellen oder aus anderen Tabellen in Ihrem Workflow verweisen. Dataform kompiliert Ihre Tabellendefinitionen in Echtzeit in SQL. Wenn Sie die Ausführung auslösen, führt Dataform den SQL-Code aus und erstellt die definierten Tabellen in BigQuery.

Sie können die folgenden Tabellentypen in einer type: "table"-SQLX-Datei erstellen:

Sie können auch Partitionen und Cluster für Tabellen definieren.

Wenn Sie den Zweck einer Tabelle oder ihre Beziehung zu anderen Tabellen in Ihrem Workflow festhalten möchten, können Sie der Tabelle oder den ausgewählten Spalten Dokumentation hinzufügen.

Wenn Sie die Daten in einer Tabelle auf bestimmte Bedingungen prüfen möchten, können Sie Abfragen für Datenqualitätstests erstellen, die als Assertions bezeichnet werden. Dataform führt jedes Mal, wenn Ihr Workflow aktualisiert wird, Assertions aus und benachrichtigt Sie, wenn Assertions fehlschlagen.

Wenn Sie das Standardschema, die Standarddatenbank und den Standardnamen einer ausgewählten Tabelle überschreiben möchten, können Sie die Tabelleneinstellungen überschreiben.

Wenn Sie die Tabellenerstellung deaktivieren oder eine SQL-Anweisung vor oder nach der Tabellenerstellung ausführen möchten, können Sie zusätzliche Aktionen konfigurieren.

Wenn Sie Ihre Tabellen in BigQuery nach dem Ausführen organisieren möchten, können Sie BigQuery-Labels hinzufügen. Weitere Informationen finden Sie unter Einführung in Labels.

Wenn Sie den Datenzugriff auf Tabellenspaltenebene einschränken möchten, können Sie BigQuery-Richtlinien-Tags hinzufügen. Weitere Informationen finden Sie unter Einführung in die Zugriffssteuerung auf Spaltenebene.

Wenn Sie BigQuery-Datenrichtlinien und Data Governance-Tags (Vorabversion), die von externen Systemen angewendet werden, über Tabellenausführungen hinweg beibehalten möchten, können Sie Metadaten für die Zugriffssteuerung beibehalten.

Zusätzlich zum Definieren von Tabellen in einer type: "table"-SQLX-Datei können Sie leere Tabellen erstellen, indem Sie eine benutzerdefinierte SQL-Abfrage in einer type: "operations"-SQLX-Datei definieren. Sie können eine leere Tabelle erstellen, damit ein anderer Dienst sie mit Daten füllen kann.

Hinweis

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

  2. Entwicklungsarbeitsbereich in Ihrem Repository erstellen und initialisieren

  3. Optional: Datenquelle deklarieren.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen:

  • Dataform-Bearbeiter (roles/dataform.editor) für den Arbeitsbereich
  • Zum Synchronisieren von Metadaten mit Knowledge Catalog: Dataplex Catalog Editor (roles/dataplex.catalogEditor) für das Projekt oder die Eintragsgruppe @bigquery

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Wenn Sie Metadaten für die Zugriffssteuerung beibehalten möchten, muss das Dienstkonto, das Ihre Dataform-Workflows ausführt, je nach Aufgabe bestimmte IAM-Berechtigungen haben:

  • Metadaten extrahieren: Zum Lesen der Ansicht INFORMATION_SCHEMA.COLUMNS muss das Dienstkonto Leseberechtigungen für das Dataset oder Tabellenschema haben. Diese Berechtigungen sind in den folgenden IAM-Rollen enthalten:

  • Data-Governance-Tags anwenden: Zum Anhängen und Verwalten von Data-Governance-Tags für Tabellen und Ansichten benötigt das Dienstkonto die Berechtigungen bigquery.tables.createTagBinding und bigquery.tables.deleteTagBinding. Diese Berechtigungen sind in den folgenden vordefinierten IAM-Rollen enthalten:

  • Datenrichtlinien anwenden: Zum Erstellen und Aktualisieren von Datenrichtlinien (einschließlich tagloser Richtlinien) benötigt das Dienstkonto die Berechtigungen bigquery.dataPolicies.create und bigquery.dataPolicies.update. Diese Berechtigungen sind in den folgenden vordefinierten IAM-Rollen enthalten:

Tabelle erstellen

In diesem Abschnitt erfahren Sie, wie Sie Tabellen mit Dataform Core in Dataform erstellen.

Tabellendefinitionen

Wenn Sie eine Tabelle definieren möchten, legen Sie den Tabellentyp fest und schreiben eine SELECT-Anweisung in eine type: "table"-SQLX-Datei. Dataform kompiliert dann Ihren Dataform Core-Code in SQL, führt den SQL-Code aus und erstellt die definierten Tabellen in BigQuery.

In einer Dataform Core-SELECT-Anweisung definieren Sie die Tabellenstruktur und verweisen auf andere Objekte Ihres Workflows.

Zusätzlich zum Definieren von Tabellen in einer type: "table"-SQLX-Datei können Sie leere Tabellen erstellen, indem Sie eine benutzerdefinierte SQL-Abfrage in einer type: "operations"-SQLX-Datei definieren. Weitere Informationen finden Sie unter Leere Tabelle erstellen.

Abhängigkeiten mit ref referenzieren

Wenn Sie in einer SELECT-Anweisung auf eine Workflowaktion verweisen und sie automatisch als Abhängigkeit hinzufügen möchten, verwenden Sie die Funktion ref. Dataform führt Abhängigkeiten vor Tabellen aus, die von ihnen abhängen, um die korrekte Pipeline-Reihenfolge zu prüfen.

Die Funktion ref ist eine integrierte Dataform-Kernfunktion, die für die Abhängigkeitsverwaltung in Dataform entscheidend ist. Mit der Funktion ref können Sie die folgenden in Ihrem Dataform-Workflow definierten Objekte referenzieren und automatisch davon abhängig machen, anstatt die Schema- und Tabellennamen hartzucodieren:

Dataform verwendet die Funktion ref, um einen Abhängigkeitsbaum aller zu erstellenden oder zu aktualisierenden Tabellen zu erstellen.

Nach der Kompilierung fügt Dataform der SQL-Anweisung Boilerplate-Anweisungen wie CREATE, REPLACE, INSERT oder MERGE hinzu.

Das folgende Codebeispiel zeigt eine Tabellendefinition mit der Funktion ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

In der Funktion ref geben Sie den Namen der Tabelle oder Datenquellendeklaration an, von der Sie abhängig sein möchten. Dies ist in der Regel der Dateiname der SQLX-Datei, in der die Tabelle oder Datenquellendeklaration definiert ist.

Wenn ein Tabellenname überschrieben wird, verwenden Sie den überschriebenen Namen in der Funktion ref. Verweisen Sie beispielsweise auf eine Tabelle mit config { name: "overridden_name" } als ref("overridden_name"). Weitere Informationen finden Sie unter Tabelleneinstellungen überschreiben und Auf eine Tabelle mit einem überschriebenen Tabellennamen verweisen.

Wenn Sie mehrere Tabellen mit demselben Namen in verschiedenen Schemas haben, können Sie auf eine bestimmte Tabelle verweisen, indem Sie der Funktion ref zwei Argumente übergeben: Schemaname und Tabellenname.

Das folgende Codebeispiel zeigt die Funktion ref mit zwei Argumenten, um eine Tabelle innerhalb eines bestimmten Schemas anzugeben:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Sie können dem config-Block auch manuell Tabellenabhängigkeiten für Tabellen, Assertions, Datenquellendeklarationen oder benutzerdefinierte SQL-Vorgänge hinzufügen, die nicht in einer ref-Funktion in der SELECT-Anweisung referenziert werden. Dataform führt diese Abhängigkeiten vor abhängigen Tabellen aus.

Das folgende Codebeispiel zeigt eine Tabellenabhängigkeit im config-Block:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Weitere Informationen zur Abhängigkeitsverwaltung in Ihrem Workflow finden Sie unter Abhängigkeiten festlegen.

Mit resolve auf andere Tabellen verweisen

Mit der Funktion resolve können Sie wie mit der Funktion ref in einer SELECT-Anweisung auf eine Tabellen- oder Datenquellendeklaration verweisen, aber der Verweis wird nicht als Abhängigkeit hinzugefügt. Das bedeutet, dass das mit der Funktion resolve referenzierte Objekt die Ausführung der Tabelle, die die Funktion resolve verwendet, nicht beeinflusst.

Weitere Informationen zu integrierten Dataform-Kernfunktionen finden Sie in der Dataform-Kernreferenz.

SQLX-Datei für eine Tabellendefinition erstellen

Speichern Sie SQLX-Dateien mit Tabellendefinitionen im Verzeichnis definitions/. So erstellen Sie eine neue SQLX-Datei im Verzeichnis definitions/:

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

  2. Klicken Sie auf den Namen eines Repositorys, um es zu öffnen.

  3. Klicken Sie auf den Namen des Entwicklungsarbeitsbereichs, um ihn zu öffnen.

  4. Klicken Sie im Bereich Dateien neben definitions/ auf Mehr.

  5. Klicken Sie auf Datei erstellen.

  6. Geben Sie im Feld Dateipfad hinzufügen den Namen der Datei gefolgt von .sqlx nach definitions/ ein. Beispiel: definitions/my-table.sqlx

    Dateinamen dürfen nur Ziffern, Buchstaben, Bindestriche und Unterstriche enthalten.

  7. Klicken Sie auf Datei erstellen.

Tabellentyp definieren

So erstellen Sie eine neue Tabellentypdefinition:

  1. Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien das Verzeichnis definitions/.
  2. Wählen Sie die SQLX-Datei mit der Tabellendefinition aus, die Sie bearbeiten möchten.

  3. Geben Sie in die Datei das folgende Code-Snippet ein:

    config { type: "TABLE_TYPE" }

    Ersetzen Sie TABLE_TYPE durch einen der folgenden Tabellentypen:

    • table
    • incremental
    • view

  4. Optional: Wenn Sie eine materialisierte Ansicht definieren möchten, geben Sie das Attribut materialized unter type: "view" im folgenden Format ein:

    config {
  type: "view",
  materialized: true
}

    Weitere Informationen finden Sie unter ITableConfig.

  5. Optional: Klicken Sie auf Format.

Tabellenstruktur und -abhängigkeiten definieren

So schreiben Sie eine SELECT-Anweisung für die Tabellendefinition und definieren die Tabellenstruktur und die Abhängigkeiten:

  1. Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien das Verzeichnis definitions/.
  2. Wählen Sie die SQLX-Datei mit der Tabellendefinition aus, die Sie bearbeiten möchten.
  3. Schreiben Sie unter dem config-Block eine SELECT-Anweisung.
  4. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine Tabellendefinition mit einer SELECT-Anweisung und der Funktion ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Einschränkungen des Spaltenschemas minimieren

Wenn Sie eine Tabelle in einer SQLX-Datei vom Typ type: "table" oder type: "incremental" definieren, kompiliert Dataform die SELECT-Abfrage in eine CREATE OR REPLACE TABLE ... AS SELECT-Anweisung in BigQuery ohne explizite Liste mit Spaltenschemadefinitionen. Daher erstellt BigQuery Spalten standardmäßig im NULLABLE-Modus.

In Dataform-Tabellendefinitionen wird das Festlegen des Modus einer Spalte auf REQUIRED (NOT NULL) im Block config oder im Attribut columns nicht unterstützt. In BigQuery können Sie den Modus einer vorhandenen Spalte auch nicht von NULLABLE in REQUIRED ändern, ohne die Tabelle mit einer expliziten Schemadefinition neu zu erstellen. Weitere Informationen zum Ändern von Spaltenmodi in BigQuery finden Sie unter Modus einer Spalte ändern.

Verwenden Sie einen der folgenden Ansätze, um Werte ungleich null zu validieren oder Tabellen mit REQUIRED-Spalten zu erstellen:

Nicht-Nullwerte mit Assertions validieren
Fügen Sie im config-Block der Tabelle eine integrierte nonNull- oder rowConditions-Assertion hinzu, z. B. assertions: { nonNull: ["column_name"] } oder assertions: { rowConditions: ["column_name IS NOT NULL"] }. Sie können eine manuelle Assertion auch in einer separaten type: "assertion"-SQLX-Datei definieren. Mit Assertions wird während der Workflowausführung geprüft, ob Zeilen NULL-Werte enthalten, ohne den zugrunde liegenden BigQuery-Spaltenmodus von NULLABLE in REQUIRED zu ändern. Weitere Informationen zu Assertions finden Sie unter Daten mit Assertions testen.
NOT NULL Spalten mit benutzerdefinierten SQL-Vorgängen oder in BigQuery definieren
Wenn Sie eine Tabelle erstellen möchten, deren BigQuery-Schema Spalten auf den Modus REQUIRED setzt, schreiben Sie eine CREATE OR REPLACE TABLE-DDL-Anweisung mit expliziten NOT NULL-Spalteneinschränkungen in eine benutzerdefinierte SQL-Vorgangsdatei mit config { type: "operations", hasOutput: true } oder erstellen und verwalten Sie das Tabellenschema direkt in BigQuery. Weitere Informationen zum Definieren von REQUIRED-Spalten in DDL-Anweisungen finden Sie unter Tabelle mit REQUIRED-Spalten erstellen.

Manuelle Tabellenabhängigkeiten hinzufügen

So fügen Sie Tabellenabhängigkeiten hinzu, die nicht in der SELECT-Anweisung referenziert werden, aber vor der aktuellen Tabelle ausgeführt werden müssen:

  1. Maximieren Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien das Verzeichnis definitions/.
  2. Wählen Sie die SQLX-Datei mit der Tabellendefinition aus, die Sie bearbeiten möchten.

  3. Geben Sie im Block config der Tabelle das folgende Code-Snippet ein:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Ersetzen Sie DEPENDENCY_TABLE durch den Dateinamen der Tabelle, die Sie als Abhängigkeit hinzufügen möchten. Sie können mehrere Dateinamen eingeben.

  4. Optional: Klicken Sie auf Format.

Im folgenden Codebeispiel werden zwei Tabellen als manuelle Tabellenabhängigkeiten zum config-Block einer Tabellendefinitionsdatei hinzugefügt:

config { dependencies: [ "some_table", "some_other_table" ] }

Tabelleneinstellungen überschreiben

Sie können das Standardschema, die Standarddatenbank und den Standardnamen einer ausgewählten Tabelle überschreiben.

Standardmäßig folgt eine Tabelle der Schema- und Datenbankkonfiguration, die Sie in workflow_settings.yaml festgelegt haben. Der Name einer Tabelle ist mit dem Namen der SQLX-Datei für die Tabellendefinition identisch.

So überschreiben Sie das Schema und den Namen einer ausgewählten Tabelle:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.

  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.

  3. Öffnen Sie eine SQLX-Tabellendefinitionsdatei.

  4. Geben Sie im Block config das folgende Code-Snippet ein:

     {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }

    Ersetzen Sie Folgendes:

    • OVERRIDDEN_SCHEMA: das BigQuery-Dataset, in dem Sie die Tabelle erstellen möchten.

    • OVERRIDDEN_DATABASE: die ID des BigQuery-Projekts, in dem Sie die Tabelle erstellen möchten.

    • OVERRIDDEN_NAME: der Name der Tabelle, der sich vom Dateinamen der SQLX-Tabellendefinition unterscheidet.

  5. Optional: Klicken Sie auf Format.

Weitere Informationen finden Sie unter Tabelle mit überschriebenem Tabellennamen referenzieren.

Verwaltete Apache Iceberg-Tabellen erstellen

Mit Dataform BigQuery-Tabellen im Iceberg-Tabellenformat erstellen. Diese Tabellen werden als verwaltete Iceberg-Tabellen bezeichnet. Weitere Informationen zu erforderlichen Rollen und anderen Einrichtungsaufgaben finden Sie in den Schritten unter Vorbereitung für Workflows mit verwalteten Iceberg-Tabellen.

Iceberg-Tabellendefinition erstellen

Definieren Sie zum Erstellen der Tabellen die Iceberg-Konfiguration im Block bigquery einer Tabellendefinitionsdatei.

So definieren Sie die Tabellen:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Tabellendefinition.

  4. Fügen Sie im Block config einen Block bigquery hinzu, der einen Block iceberg im folgenden Format enthält:

    config {
  type: "table",
  name: "my_table",
  uniqueKey: ["uniquekey"],
  bigquery: {
    iceberg: {
      bucket_name: "BUCKET_NAME"
    }
  }
}

    Ersetzen Sie BUCKET_NAME durch den Namen des Cloud Storage-Bucket, in dem die Tabellendaten gespeichert sind.

    Andere Attribute sind optional und haben Standardwerte, wenn sie nicht angegeben werden. Weitere Informationen finden Sie unter iceberg-Attribute.

    Sie können die Werte für jede Tabelle angeben oder in workflow_settings.yaml Standardwerte auf Workflow-Ebene festlegen. Sie können die Standardeinstellungen auf Workflowebene überschreiben, indem Sie die Attribute im Block iceberg explizit festlegen.

Tabellenpartitionen und -cluster erstellen

In diesem Abschnitt erfahren Sie, wie Sie mit Dataform Core Tabellenpartitionen und Cluster erstellen. BigQuery unterstützt partitionierte Tabellen und Tabellen-Clustering. Weitere Informationen finden Sie unter Einführung in partitionierte Tabellen und Geclusterte Tabellen erstellen und verwenden.

Tabellenpartition erstellen

So erstellen Sie eine Tabellenpartition:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Tabellendefinition.

  4. Fügen Sie im Block config den Block bigquery unter der Deklaration des Tabellentyps im folgenden Format hinzu:

    config {
  type: "table",
  bigquery: {
  }
}

  5. Geben Sie im Block bigquery das folgende Code-Snippet ein:

        partitionBy: "PARTITION_EXPRESSION"

    Ersetzen Sie PARTITION_EXPRESSION durch einen Ausdruck zum Partitionieren der Tabelle.

  6. Optional: Klicken Sie auf Format.

Im folgenden Codebeispiel wird gezeigt, wie eine Tabelle in einer SQLX-Datei mit einer Tabellendefinition nach Stunde partitioniert wird:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

Im folgenden Codebeispiel wird gezeigt, wie eine Tabelle in einer SQLX-Datei mit Tabellendefinition nach einem Ganzzahlwert partitioniert wird:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Partitionsfilter festlegen

So legen Sie einen Partitionsfilter fest:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Definition für eine partitionierte Tabelle.

  4. Geben Sie im Block bigquery das folgende Code-Snippet ein:

    requirePartitionFilter : true

  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt einen Partitionsfilter, der im bigquery-Block einer SQLX-Datei für eine partitionierte Tabelle festgelegt ist:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Weitere Informationen zum Partitionsfilter in BigQuery finden Sie unter Attribut „Partitionsfilter anfordern“ für eine partitionierte Tabelle festlegen.

Aufbewahrungsdauer für Partitionen festlegen

So steuern Sie die Aufbewahrung aller Partitionen in einer partitionierten Tabelle:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Definition für eine partitionierte Tabelle.

  4. Geben Sie im Block bigquery das folgende Code-Snippet ein:

    partitionExpirationDays: NUMBER_OF_DAYS

    Ersetzen Sie NUMBER_OF_DAYS durch die Anzahl der Tage, für die Sie die Partitionen aufbewahren möchten.

  5. Optional: Klicken Sie auf Format.

Im folgenden Codebeispiel wird eine Aufbewahrungsdauer für Partitionen von 14 Tagen im bigquery-Block einer SQLX-Datei für eine partitionierte Tabelle festgelegt:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Tabellencluster erstellen

So erstellen Sie einen Tabellencluster:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Tabellendefinition.

  4. Geben Sie im Block bigquery das folgende Code-Snippet ein:

        clusterBy: ["CLUSTER_COLUMN"]

    Ersetzen Sie CLUSTER_COLUMN durch den Namen der Spalte, nach der Sie die Tabelle clustern möchten. Weitere Informationen finden Sie unter clustering_column_list.

  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine partitionierte Tabelle, die nach den Spalten name und revenue geclustert ist:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Inkrementelle Tabelle konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie mit Dataform Core eine inkrementelle Tabelle konfigurieren.

Inkrementelle Tabellen

Dataform aktualisiert Tabellen je nach Tabellentyp unterschiedlich. Bei jeder Ausführung einer Tabelle oder Ansicht erstellt Dataform die gesamte Tabelle oder Ansicht von Grund auf neu.

Wenn Sie eine inkrementelle Tabelle definieren, erstellt Dataform die inkrementelle Tabelle nur beim ersten Mal von Grund auf neu. Bei nachfolgenden Ausführungen fügt Dataform nur neue Zeilen gemäß den von Ihnen konfigurierten Bedingungen in die inkrementelle Tabelle ein oder führt sie zusammen.

Dataform fügt neue Zeilen nur in Spalten ein, die bereits in der inkrementellen Tabelle vorhanden sind. Wenn Sie Änderungen an der Abfrage für die Definition der inkrementellen Tabelle vornehmen, z. B. durch Hinzufügen einer neuen Spalte, müssen Sie entscheiden, ob Sie die Tabelle von Grund auf neu erstellen möchten. Wenn Sie die Tabelle neu erstellen möchten, wählen Sie beim nächsten Ausführen der Tabelle die Option Mit vollständiger Aktualisierung ausführen aus. Weitere Optionen finden Sie unter Schema einer inkrementellen Tabelle ohne vollständige Aktualisierung ändern.

Hier sind einige gängige Anwendungsfälle für inkrementelle Tabellen:

Leistungsoptimierung
Bei einigen Datentypen, z. B. Webprotokollen oder Analysedaten, möchten Sie möglicherweise nur neue Datensätze verarbeiten, anstatt die gesamte Tabelle neu zu verarbeiten.
Reduzierung der Latenz
Mit inkrementellen Tabellen können Sie Workflows schnell, aber häufig ausführen und so die Downstream-Latenz der Ausgabetabellen reduzieren.
Tägliche Snapshots
Sie können eine inkrementelle Tabelle so konfigurieren, dass tägliche Snapshots der Tabellendaten erstellt werden, z. B. für eine Längsschnittanalyse von Nutzereinstellungen, die in einer Produktionsdatenbank gespeichert sind.

Teilmenge von Zeilen in einer inkrementellen Tabelle verarbeiten

Wenn Sie eine Teilmenge von Zeilen festlegen möchten, die Dataform bei jeder Ausführung verarbeiten soll, fügen Sie der SQLX-Definitionsdatei der inkrementellen Tabelle eine bedingte WHERE-Klausel hinzu. In der WHERE-Klausel können Sie eine inkrementelle und eine nicht inkrementelle Bedingung angeben. Dataform wendet die inkrementelle Bedingung während der Tabellenausführung ohne vollständige Aktualisierung und die nicht inkrementelle Bedingung während der Ausführung mit einer vollständigen Aktualisierung an.

So konfigurieren Sie eine inkrementelle Tabelle:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Öffnen Sie eine SQLX-Datei mit einer Definition für eine inkrementelle Tabelle.

  4. Geben Sie eine WHERE-Klausel im folgenden Format ein:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Ersetzen Sie Folgendes:

    • SELECT_STATEMENT: die SELECT-Anweisung, die Ihre Tabelle definiert.
    • INCREMENTAL_CONDITION: die Bedingung, die Sie in der WHERE-Klausel angeben, um Zeilen auszuwählen, die Dataform während der Tabellenausführung ohne vollständige Aktualisierung verarbeiten soll.
    • NON_INCREMENTAL_CONDITION: Die Bedingung, die Sie in der WHERE-Klausel angeben, um Zeilen auszuwählen, die Dataform während der Tabellenausführung mit einer vollständigen Aktualisierung verarbeiten soll.

  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, in der Zeilen der Tabelle productiondb.logs inkrementell verarbeitet werden:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, die einen Snapshot der Tabelle productiondb.customers erstellt:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Zeilen in einer inkrementellen Tabelle zusammenführen

Wenn Sie prüfen möchten, ob eine inkrementelle Tabelle nur eine Zeile enthält, die einer ausgewählten Kombination von Spalten entspricht, legen Sie die ausgewählten Spalten als uniqueKey fest, um Zeilen mit demselben uniqueKey-Wert zusammenzuführen. Beim Aktualisieren der Tabelle führt Dataform Zeilen mit demselben uniqueKey-Wert zusammen, anstatt sie anzuhängen.

So konfigurieren Sie das Zusammenführen in einer inkrementellen Tabelle:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. SQLX-Datei für die Definition einer inkrementellen Tabelle auswählen

  4. Legen Sie im Block config die ausgewählten Spalten im folgenden Format als uniqueKey fest:

    uniqueKey: ["COLUMN_NAME"]

    Ersetzen Sie COLUMN_NAME durch den Namen einer ausgewählten Spalte.

  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, bei der die Spalte transaction_id auf uniqueKey gesetzt ist, um zu prüfen, ob sie immer eine Zeile enthält:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Zeilen in einer inkrementellen Tabelle filtern

Wenn Sie in einer inkrementellen partitionierten Tabelle verhindern möchten, dass Dataform die gesamte Tabelle nach übereinstimmenden Zeilen durchsucht, legen Sie updatePartitionFilter so fest, dass nur eine Teilmenge von Datensätzen berücksichtigt wird.

Das folgende Codebeispiel zeigt eine inkrementell partitionierte Tabelle mit Zusammenführung, die über die Attribute updatePartitionFilter und uniqueKey konfiguriert wird. Dabei werden zwei verschiedene Arten von Filtern verwendet:

  • Zielbereinigung mit dem Attribut updatePartitionFilter: Begrenzt die Partitionen, die während eines MERGE-Vorgangs in der Zieltabelle gescannt werden, um Zeilen zu finden, die mit der uniqueKey übereinstimmen.
  • Quellbereinigung mit einer WHERE-Klausel: Begrenzt, welche Zeilen während einer inkrementellen Ausführung aus der Quelltabelle abgerufen werden. Dies wird mit der Funktion ${when(incremental(), ...)} erreicht.
config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Vollständige Tabellenscans beim Aufnehmen aus einer partitionierten Tabelle vermeiden

Wenn Sie eine inkrementelle Tabelle erstellen, die auf eine partitionierte Tabelle verweist, empfehlen wir, die Tabellenabfrage so zu erstellen, dass bei jeder inkrementellen Aktualisierung keine vollständigen Tabellenscans der partitionierten Tabelle durchgeführt werden.

Sie können die Anzahl der Partitionen, die BigQuery zum Aktualisieren der inkrementellen Tabelle scannt, begrenzen, indem Sie in Ihrer Tabellenabfrage einen konstanten Ausdruck verwenden. Wenn Sie einen Wert aus der partitionierten Tabelle in einen konstanten Ausdruck umwandeln möchten, verwenden Sie BigQuery-Scripting, um den Wert im pre_operations-Block als Variable zu deklarieren. Verwenden Sie die Variable dann als konstanten Ausdruck in einer WHERE-Klausel in der SELECT-Abfrage.

Mit dieser Konfiguration aktualisiert Dataform die inkrementelle Tabelle basierend auf den neuesten Partitionen der referenzierten partitionierten Tabelle, ohne die gesamte Tabelle zu scannen.

So konfigurieren Sie eine inkrementelle Tabelle, die auf eine partitionierte Tabelle verweist und vollständige Tabellenscans vermeidet:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. SQLX-Datei für die Definition einer inkrementellen Tabelle auswählen
  4. Deklarieren Sie im pre_operations-Block eine Variable mit BigQuery-Scripting.
  5. Filtern Sie die SELECT-Anweisung, die die Tabelle definiert, mit einer WHERE-Klausel, die auf die deklarierte Variable verweist.
  6. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, in der die referenzierte raw_events-Tabelle nach event_timestamp partitioniert ist:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

Im vorherigen Codebeispiel wird die Variable event_timestamp_checkpoint im Block pre_operations definiert. Die Variable event_timestamp_checkpoint wird dann als konstanter Ausdruck in der WHERE-Klausel verwendet.

Inkrementelle Tabelle mit vollständiger Aktualisierung neu erstellen

Sie können die Neuerstellung einer inkrementellen Tabelle erzwingen, indem Sie entweder die Befehlszeile mit der Option --full-refresh oder die Option Mit vollständiger Aktualisierung ausführen verwenden, wenn Sie eine Workflowausführung auslösen.

Wenn Sie die Option für die vollständige Aktualisierung in Ihrem Entwicklungsarbeitsbereich oder über die Dataform-Befehlszeile auswählen, ignoriert Dataform den Parameter ${when(incremental(), ... } während der Ausführung und erstellt die Tabelle mit einer CREATE OR REPLACE-Anweisung neu.

Inkrementelle Tabelle vor vollständiger Aktualisierung schützen

Um zu verhindern, dass eine inkrementelle Tabelle von Grund auf neu erstellt wird, und um potenziellen Datenverlust zu vermeiden, können Sie die inkrementelle Tabelle als protected festlegen. Wenn Ihre Datenquelle temporär ist, sollten Sie verhindern, dass eine inkrementelle Tabelle neu erstellt wird.

So markieren Sie eine inkrementelle Tabelle als protected:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Wählen Sie eine SQLX-Datei für die Definition einer inkrementellen Tabelle aus.
  4. Geben Sie im Block config den Wert protected: true ein.
  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, die als protected gekennzeichnet ist:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Schema einer inkrementellen Tabelle ohne vollständige Aktualisierung ändern

Sie können ein inkrementelles Tabellenschema in der SELECT-Abfrage ohne vollständige Aktualisierung der Tabelle ändern, indem Sie das Konfigurationsattribut onSchemaChange verwenden. Mit diesem Attribut können Sie einer Tabelle neue Spalten hinzufügen oder vorhandene Spalten entfernen, während Verlaufsdaten erhalten bleiben. So können Sie Datenverluste und manuelle Aktualisierungen in BigQuery vermeiden.

Wenn Sie diese Funktion verwenden möchten, müssen Sie Dataform Core 3.0.11 oder höher installieren.

Nachdem Sie das Attribut onSchemaChange festgelegt haben, prüft Dataform die Abfrage SELECT, um festzustellen, ob Spalten hinzugefügt oder entfernt wurden. Dataform führt dann die Aktion aus, die durch den Wert des Attributs onSchemaChange angegeben wird.

So legen Sie das Attribut onSchemaChange fest:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Wählen Sie eine SQLX-Datei für die Definition einer inkrementellen Tabelle aus.

  4. Geben Sie im Block config das folgende Code-Snippet ein:

    onSchemaChange: "ON_CHANGE_ACTION"

    Ersetzen Sie ON_CHANGE_ACTION durch eine der folgenden Aktionen:

    • IGNORE (Standard): Ignoriert hinzugefügte Spalten und zeigt einen Fehler für fehlende Spalten an. Wenn onSchemaChange nicht festgelegt ist, ist dies das Standardverhalten, wenn sich das Schema ändert.
    • FAIL: Beendet die Aktion, wenn Dataform eine Schemaänderung erkennt. Dadurch bleibt das Schema konsistent.
    • EXTEND: Fügt der inkrementellen Tabelle neue Spalten aus der Abfrage hinzu und fügt NULL-Werte für vorherige Datensätze hinzu. Zeigt einen Fehler an, wenn eine Spalte aus dem ursprünglichen Schema in der Abfrage entfernt wurde oder fehlt. Mit dieser Einstellung können Sie Ihren inkrementellen Tabellen während der Laufzeit neue Spalten hinzufügen.

    • SYNCHRONIZE: Fügt der inkrementellen Tabelle neue Spalten aus der Abfrage hinzu und fügt NULL-Werte für vorherige Datensätze hinzu. Entfernt Spalten, die im ursprünglichen Schema vorhanden waren, aber jetzt in der aktuellen Abfrage fehlen.

  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine inkrementelle Tabelle, bei der die Aktion EXTEND für das Attribut onSchemaChange festgelegt ist:

config {
    type: "incremental",
    onSchemaChange: "EXTEND",
}
SELECT ...

Tabellendokumentation hinzufügen

In diesem Abschnitt erfahren Sie, wie Sie Beschreibungen einer Tabelle und ihrer Spalten und Datensätze zu einer Dataform Core-SQLX-Datei hinzufügen.

Sie können allen Tabellentypen in Dataform (Tabellen, inkrementelle Tabellen und Ansichten) Beschreibungen für Tabellen, Spalten und Datensätze hinzufügen.

Sie sollten Folgendes dokumentieren:

  • Der Zweck der Tabelle.
  • Der Inhalt oder die Rolle von Spalten oder Datensätzen in der Tabelle.
  • Die Beziehung der Tabelle zu anderen Aktionen Ihres Workflows, z. B. die Tabellen oder Ansichten, die von der aktuellen Tabelle abhängen.
  • Die auf die Tabelle angewendeten Assertions.
  • Die Vor- oder Nachvorgänge, die auf die Tabelle angewendet werden.
  • Der Inhaber der Tabelle, d. h. der Nutzer, der sie erstellt hat. Diese Informationen können nützlich sein, wenn mehrere Teammitglieder an einem Workflow arbeiten.

Metadaten für Knowledge Catalog hinzufügen

Standardmetadaten aus BigQuery, z. B. Datasets, Tabellen und Ansichten, sind automatisch in Knowledge Catalog verfügbar.

Sie können auch benutzerdefinierte Metadaten für Ihre Tabellen und Ansichten direkt im Konfigurationsblock Ihrer .sqlx-Dateien definieren. Nach erfolgreichem Abschluss einer Aktion initiiert Dataform automatisch eine Metadatensynchronisierung mit Knowledge Catalog. Bei diesem Anreicherungsprozess wird Knowledge Catalog mit den semantischen Metadaten aktualisiert, die in Ihrer SQLX-Konfiguration definiert sind.

Verwenden Sie den Metadatenschlüssel, um Informationen für den Knowledge Catalog anzugeben. Der Anreicherungsprozess unterstützt die folgenden Metadatenkonstrukte:

  • Übersicht: Dokumentation und Zusammenfassungstext für den Eintrag. Erfordert Dataform Core-Version 3.0.37 oder höher.
  • Generische Aspekte: semantische Details wie Tabellensystem- und Typinformationen. Erfordert Dataform Core-Version 3.0.52 oder höher.

Die folgende Beispielkonfiguration zeigt, wie Sie einer Tabellenkonfiguration für Knowledge Catalog eine Übersicht und generische Metadatenaspekte hinzufügen:

config {
  type: "table",
  metadata: {
    overview: "This table provides standardized trip data.",
    extraProperties: {
        generic: {
              system: "BigQuery",
              type: "table"
        }
      }
  }
}

Informationen zum Prüfen des Status einer Metadatenaktualisierung finden Sie unter Arbeitsbereichsausführungsprotokolle prüfen für Dataform-Workflows oder unter Frühere manuelle Ausführungen ansehen für BigQuery-Pipelines.

Sie können die synchronisierten Metadaten prüfen, indem Sie im Knowledge Catalog nach dem Asset suchen. Weitere Informationen finden Sie unter Nach Ressourcen suchen.

Tabellenbeschreibung hinzufügen

So fügen Sie einer Tabelle in einer SQLX-Datei eine Beschreibung hinzu:

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Klicken Sie im Bereich Dateien auf die SQLX-Datei mit der Tabellendefinition, die Sie bearbeiten möchten.

  5. Geben Sie im Block config der Datei die Tabellenbeschreibung im folgenden Format ein:

    description: "Description of the table",

  6. Optional: Klicken Sie auf Format.

Im folgenden Codebeispiel wird eine Tabellenbeschreibung gezeigt, die dem config-Block einer SQLX-Tabellendefinitionsdatei hinzugefügt wurde:

config {
  type: "table",
  description: "Description of the table",
 }

Spalten- und Datensatzbeschreibungen hinzufügen

So fügen Sie einer SQLX-Datei Beschreibungen einzelner Spalten und Datensätze hinzu:

  1. Geben Sie im Block config der Tabellendefinitionsdatei columns: {} ein.

  2. Geben Sie in columns: {} Spaltenbeschreibungen im folgenden Format ein:

    column_name: "Description of the column",

  3. Geben Sie in columns: {} Datensatzbeschreibungen im folgenden Format ein:

      record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

  4. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt Tabellen-, Spalten- und Eintragsbeschreibungen im config-Block einer SQLX-Tabellendefinitionsdatei:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Spaltendokumentation mit Includes wiederverwenden

Sie können Beschreibungen von Spalten in Dataform in Ihrem SQL-Workflow mit JavaScript-Includes wiederverwenden. Sie können die Spaltendokumentation wiederverwenden, wenn Sie in Ihrem SQL-Workflow mehrere Spalten mit demselben Namen und derselben Beschreibung haben.

Sie können eine Konstante mit einer Beschreibung einer einzelnen Spalte oder eine Konstante mit einer Reihe von Spaltenbeschreibungen definieren, um die Beschreibungen aller Spalten in einer Tabelle wiederzuverwenden. Weitere Informationen zum Erstellen und Verwenden von Includes in Dataform finden Sie unter Code in einem einzelnen Repository mit Includes wiederverwenden.

Das folgende Codebeispiel zeigt mehrere Konstanten mit Beschreibungen einzelner Spalten, die in der JavaScript-Datei includes/docs.js definiert sind:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

Das folgende Codebeispiel zeigt die in includes/docs.js definierten Konstanten user_id und age, die in der SQLX-Tabellendefinitionsdatei definitions/my_table.sqlx verwendet werden, um Dokumentation für ausgewählte Spalten in der Tabelle zu generieren:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

Das folgende Codebeispiel zeigt eine Konstante mit einer Reihe von Spaltenbeschreibungen, die in der JavaScript-Datei includes/docs.js definiert sind:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

Das folgende Codebeispiel zeigt die Konstante columns, die in includes/table_docs.js definiert ist und in der SQLX-Tabellendefinitionsdatei definitions/my_table.sqlx verwendet wird, um Dokumentation für alle Spalten in der Tabelle zu generieren:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

BigQuery-Labels hinzufügen

In diesem Abschnitt erfahren Sie, wie Sie Tabellen in Dataform Labels hinzufügen.

BigQuery unterstützt das Hinzufügen von Labels zu Ressourcen. Weitere Informationen zu Labels in BigQuery finden Sie unter Einführung in Labels.

Wenn Sie einer Tabelle in Dataform ein BigQuery-Label hinzufügen möchten, fügen Sie das Label dem Block bigquery im Block config der SQLX-Datei für die Tabellendefinition hinzu.

So fügen Sie einer Tabellendefinitionsdatei ein BigQuery-Label hinzu:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Wählen Sie eine SQLX-Tabellendefinitionsdatei aus.

  4. Fügen Sie im Block config ein Label im folgenden Format hinzu:

    bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }

    Ersetzen Sie Folgendes:

    • LABEL1: der Name Ihres Labels
    • VALUE_OF_LABEL1: der Wert Ihres Labels

  5. Optional: Wenn Sie ein Label mit einem Namen hinzufügen möchten, der Sonderzeichen enthält, geben Sie den Labelnamen in Anführungszeichen ("") ein.

  6. Optional: Klicken Sie auf Format.

Im folgenden Codebeispiel werden die Labels department:shipping und cost-center:logistics dem Block bigquery in einer SQLX-Datei mit einer partitionierten Tabellendefinition hinzugefügt:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

Metadaten zur Zugriffssteuerung beibehalten

Wenn Dataform Workflowaktionen ausführt, die Objekte neu erstellen, z. B. Standardtabellen, Ansichten oder inkrementelle Tabellen während einer vollständigen Aktualisierung, werden in BigQuery normalerweise CREATE OR REPLACE-Anweisungen generiert, um das Objektschema und die Daten zu aktualisieren. In BigQuery werden bei Vorgängen zum Ersetzen von Tabellen standardmäßig vorhandene Metadaten für die Zugriffssteuerung auf Spaltenebene automatisch gelöscht, z. B. Datenrichtlinien und Data Governance-Tags (Vorabversion), die von externen Data Governance-Systemen angewendet werden.

Sie können Dataform so konfigurieren, dass vorhandene BigQuery-Datenrichtlinien, einschließlich tagloser Datenrichtlinien, und Data Governance-Tags über Workflowausführungen hinweg automatisch beibehalten werden. Aktivieren Sie dazu die Option preserveGovernanceControls. Wenn diese Option aktiviert ist, führt Dataform während der Ausführung die folgende Sequenz aus:

  1. Sichert vorhandene Spaltenmetadaten aus der Ansicht INFORMATION_SCHEMA.COLUMNS.
  2. Erstellt eine leere Zwischen-Staging-Tabelle.
  3. Wendet die Sicherheitsrichtlinien wieder auf die Zwischentabelle an.
  4. Füllt die Tabelle mit Daten.
  5. Führt einen atomaren Tabellenaustausch durch, um die ursprüngliche Tabelle zu ersetzen.

Automatisierte Governance-Aufbewahrung für eine Tabelle aktivieren

Wenn Sie die automatische Beibehaltung von Datenrichtlinien und Data-Governance-Tags für eine einzelne Tabelle, eine inkrementelle Tabelle oder eine Ansicht aktivieren möchten, setzen Sie den Parameter preserveGovernanceControls im Block config der SQLX-Definitionsdatei des Objekts auf true.

So konfigurieren Sie die Governance-Aufbewahrung für eine einzelne Tabelle:

  1. Rufen Sie Ihren Entwicklungsarbeitsbereich auf.
  2. Maximieren Sie im Bereich Dateien den Ordner definitions/.
  3. Wählen Sie eine SQLX-Tabellendefinitionsdatei aus.
  4. Geben Sie im Block config den Wert preserveGovernanceControls: true ein.
  5. Optional: Klicken Sie auf Format.

Das folgende Codebeispiel zeigt eine Tabellendefinition mit aktivierter Governance-Aufbewahrung:

config {
  type: "table",
  preserveGovernanceControls: true
}

SELECT
  customer_id,
  email,
  phone_number
FROM
  ${ref("raw_customers")}

Automatisierte Governance-Aufbewahrung für alle Tabellen aktivieren

Sie können die automatisierte Governance-Aufbewahrung als projektweites Standardverhalten für alle Tabellen, inkrementellen Tabellen und Ansichten in Ihrem Repository aktivieren. Setzen Sie dazu den Parameter preserveGovernanceControls in der Datei workflow_settings.yaml Ihres Repositorys auf true.

Wenn Sie den projektweiten Standardwert festlegen möchten, fügen Sie den Parameter preserveGovernanceControls Ihrer workflow_settings.yaml-Datei hinzu, wie im folgenden Beispiel gezeigt:

defaultProject: my-gcp-project-id
defaultDataset: my_dataform_dataset
defaultLocation: US
defaultAssertionDataset: my_dataform_assertions
dataformCoreVersion: 3.0.62
preserveGovernanceControls: true

Wenn Sie die Governance-Aufbewahrung global in der Datei workflow_settings.yaml aktivieren, können Sie dieses Verhalten überschreiben und die Aufbewahrung für eine bestimmte Tabelle deaktivieren. Setzen Sie dazu den Parameter preserveGovernanceControls im Block config der jeweiligen Tabelle auf false.

Zeilenzugriffsrichtlinien mit Post-Vorgängen neu anwenden

Wenn Sie die Governance-Erhaltung aktivieren, werden Metadaten auf Spaltenebene wie BigQuery-Datenrichtlinien und Data-Governance-Tags automatisch geschützt. Zeilenzugriffsrichtlinien werden jedoch nicht automatisch wiederhergestellt. Da beim Ersetzen von Objekten vorhandene Sicherheitsregeln auf Zeilenebene gelöscht werden, können Sie Zugriffsrichtlinien auf Zeilenebene nach dem Erstellen der Tabelle neu anwenden. Definieren Sie dazu SQL-DDL-Anweisungen im Block post_operations Ihrer SQLX-Tabellendefinitionsdatei.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine Zeilenzugriffsrichtlinie im post_operations-Block einer Tabelle noch einmal anwenden:

config {
  type: "table",
}

SELECT
  bike_id,
  start_time,
  duration
FROM
  ${ref("raw_trips")}

post_operations {
  CREATE ROW ACCESS POLICY my_policy
  ON ${self()}
  GRANT TO ('serviceAccount:sa-name@example-gcp-project.')
  FILTER USING (bike_id LIKE 'US-%');
}

Beschränkungen

Beachten Sie bei der Verwendung der Governance-Aufbewahrungsfunktion die folgenden Einschränkungen:

  • Entfernen von Schemaspalten. Wenn eine Spalte aus Ihrer SQLX-Tabellendefinition entfernt wird, ignoriert Dataform während der Wiederherstellungsphase alle gesicherten Datenrichtlinien und Tags, die mit der gelöschten Spalte verknüpft sind.
  • Umbenennung von Schemaspalten. Wenn Sie eine vorhandene Spalte in Ihrer SQLX-Tabellendefinition umbenennen, kann Dataform die alten Tag- oder Richtlinienzuordnungen nicht dem neuen Spaltennamen zuordnen. Infolgedessen gehen vorhandene Tags und Richtlinien für diese Spalten verloren oder werden vertauscht. Sie müssen die Tags und Richtlinien manuell wieder auf die umbenannten Spalten anwenden.
  • Änderungen an Partitionierung und Clustering Das Ändern der Partitionierung oder des Clusterings einer vorhandenen Tabelle, die preserveGovernanceControls verwendet, wird nicht direkt unterstützt. BigQuery lehnt die Ersetzung ab. Löschen Sie die Tabelle und führen Sie den Workflow noch einmal aus, um das Problem zu beheben. Sie müssen Datenrichtlinien auf Spaltenebene und Data-Governance-Tags manuell auf die neu erstellte Tabelle anwenden.
  • Entfernen von abgelaufenen Partitionen. Wenn Sie das Attribut partitionExpirationDays aus der Konfiguration entfernen, wird der Ablauf der Partition nicht aus einer vorhandenen Tabelle entfernt. Wenn Sie den Ablauf der Partition aus einer vorhandenen Tabelle entfernen möchten, müssen Sie die Option explizit auf den ausgewählten Wert festlegen oder die Tabelle manuell ändern.
  • Tabellentypen Nach einer erfolgreichen Ausführung wird die Tabelle als Tabellenklon (table_type = 'CLONE' in INFORMATION_SCHEMA.TABLES) gemeldet. Sie verhält sich wie eine Standardtabelle und die in den Klonmetadaten angezeigte Basistabelle ist nicht mehr vorhanden.
  • Metadaten auf Tabellenebene und Zugriffsrichtlinien auf Zeilenebene Tags auf Tabellenebene und Zugriffsrichtlinien auf Zeilenebene werden nicht über Ausführungen hinweg beibehalten. Sie können Zeilenzugriffsrichtlinien nach dem Erstellen der Tabelle wieder anwenden, indem Sie SQL-DDL-Anweisungen im Block post_operations Ihrer SQLX-Tabellendefinitionsdatei definieren.
  • Nicht transaktionale Tabellenaustausche. BigQuery-DDL-Vorgänge sind nicht transaktional. Wenn eine Workflowausführung während der atomaren Umbenennungssequenz fehlschlägt, ist möglicherweise ein manueller Eingriff erforderlich, wenn die Zieltabelle in einem Zwischenzustand verbleibt, z. B. wenn die Tabelle dauerhaft in TABLE_NAME_old umbenannt oder als df_tmp_intermediate belassen wird.
  • Richtlinien-Tags. Die automatisierte Governance-Aufbewahrung unterstützt keine BigQuery-Richtlinien-Tags. Fügen Sie stattdessen BigQuery-Daten-Governance-Tags (Vorabversion) und Datenrichtlinien zu Ihren Spalten hinzu, um die integrierte SQL-Einbindung zu verwenden.

Hinweise zu Speicherkosten

Wenn preserveGovernanceControls aktiviert ist, erstellt Dataform die Tabelle bei jeder Ausführung (oder bei jeder vollständigen Aktualisierung für inkrementelle Tabellen) über eine temporäre Staging-Tabelle neu. Wie bei jeder Neuerstellung einer Tabelle in BigQuery wird die vorherige Version der Tabellendaten im Zeitreisefenster des Datasets aufbewahrt. Dieses Fenster ist standardmäßig auf sieben Tage festgelegt, gefolgt von einem siebentägigen Ausfallsicherungszeitraum.

Die Abrechnung für logischen Speicher ist das Standardabrechnungsmodell in BigQuery, während die Abrechnung für physischen Speicher eine optionale Einstellung ist, die pro Dataset konfiguriert wird. Wenn Ihr Dataset die Abrechnung für physischen Speicher verwendet, werden diese aufbewahrten Zeitreise- und Fail-Safe-Daten zusätzlich zur aktiven Tabelle abgerechnet. Daher können große Tabellen, die häufig neu erstellt werden, Ihre Speicherkosten merklich erhöhen.

So reduzieren Sie diese Kosten:

Nächste Schritte