Code in einem Repository strukturieren

In diesem Dokument werden Best Practices zum Strukturieren und Benennen von SQL-Workflowdateien im Stammverzeichnis definitions eines Dataform-Repositorys beschrieben. Die empfohlene Struktur des Verzeichnisses definitions spiegelt die Phasen eines SQL-Workflows wider. Sie können jede Struktur verwenden, die Ihren Geschäftsanforderungen entspricht.

Sie können den SQL-Workflowcode im Verzeichnis definitions aus folgenden Gründen strukturieren:

  • Verbessern Sie die Zusammenarbeit auf der Codebasis, indem Sie Teams bestimmten Teilen Ihres Workflows zuweisen.
  • Verwaltbarkeit des SQL-Workflows bei organisatorischen Änderungen verbessern.
  • Die Navigation durch Ihre Codebasis verbessern.
  • Skalierbarkeit der Codebasis verbessern
  • Minimieren Sie den Verwaltungsaufwand für Ihr Team.

Das Stammverzeichnis definitions in einem Dataform-Repository enthält Code, mit dem Elemente Ihres SQL-Workflows erstellt werden. Sie können Dateien im Verzeichnis definitions in einer Verzeichnisstruktur organisieren, die der Struktur des Workflows entspricht.

Wenn Sie einen SQL-Workflow entwickeln, deklarieren Sie Quelltabellen und transformieren Sie sie, um Ausgabetabellen zu erstellen, die Sie für Geschäfts- oder Analysezwecke verwenden können.

Sie können drei wichtige Phasen eines SQL-Workflows unterscheiden:

  1. Angabe von Datenquellen
  2. Quelldaten umwandeln
  3. Definition von Ausgabetabellen aus den transformierten Quelldaten

Die folgende Struktur von Unterverzeichnissen im Verzeichnis definitions spiegelt die wichtigsten Phasen eines SQL-Workflows wider:

sources
Datenquellendeklarationen und grundlegende Transformation von Quelldaten, z. B. Filtern
intermediate
Tabellen und Aktionen, die aus sources lesen und Daten transformieren, bevor Sie die transformierten Daten zum Definieren von outputs-Tabellen verwenden. Tabellen, die normalerweise keinen zusätzlichen Prozessen oder Tools wie BI-Tools (Business Intelligence) ausgesetzt sind, nachdem Dataform sie in BigQuery ausgeführt hat.
outputs
Definitionen von Tabellen, die von Prozessen oder Tools wie BI verwendet werden, nachdem Dataform sie in BigQuery ausgeführt hat.
extra
Dateien außerhalb der Hauptpipeline Ihres SQL-Workflows, z. B. Dateien, die Workflowdaten enthalten, die für eine zusätzliche Verwendung wie maschinelles Lernen vorbereitet wurden Ein optionales und benutzerdefiniertes Unterverzeichnis.

Best Practices für sources

Das Unterverzeichnis sources enthält die erste Phase Ihres SQL-Workflows: die Deklaration und grundlegende Transformation der Quelldaten.

Speichern Sie im Unterverzeichnis sources Datenquellendeklarationen und Tabellen, mit denen Spalten gefiltert, kategorisiert, umgewandelt oder umbenannt werden.

Vermeiden Sie das Speichern von Tabellen, die Daten aus mehreren Quellen kombinieren.

Transformieren Sie sources-Daten in Tabellen, die im Unterverzeichnis intermediate gespeichert sind.

Wenn Sie Datenquellen aus mehreren Pools deklarieren (z. B. Google Ads oder Google Analytics), weisen Sie jedem Pool ein Unterverzeichnis zu.

Das folgende Beispiel zeigt eine Unterverzeichnisstruktur von sources mit zwei Quellpools:

definitions/
    sources/
        google_ads/
            google_ads_filtered.sqlx
            google_ads_criteria_metrics.sqlx
            google_ads_criteria_metrics_filtered.sqlx
            google_ads_labels.sqlx
            google_ads_labels_filtered.sqlx
        google_analytics/
            google_analytics_users.sqlx
            google_analytics_users_filtered.sqlx
            google_analytics_sessions.sqlx

Wenn Sie mehrere Datenquellentabellen innerhalb desselben Schemas deklarieren, können Sie deren Deklarationen in einer einzigen JavaScript-Datei konsolidieren. In einer JavaScript-Datei können Sie mehrere Datenquellendeklarationen speichern. Weitere Informationen zum Erstellen von Datenquellendeklarationen mit JavaScript finden Sie unter Dataform-SQL-Workflows mit JavaScript erstellen.

Das folgende Codebeispiel zeigt mehrere Datenquellen innerhalb eines Schemas, die in einer einzigen JavaScript-Datei deklariert wurden:

[
  "source_table_1",
  "source_table_2",
  "source_table_3"
].forEach((name) =>
  declare({
    database: "gcp_project",
    schema: "source_dataset",
    name,
  })
);

Um Ihren SQL-Workflow vor Änderungen an der Datenquelle zu schützen, können Sie für jede Datenquellendeklaration eine Ansicht erstellen, z. B. analytics_users_filtered.sqlx. Die Ansicht kann grundlegende Filter und Formatierungen von Quelldaten enthalten. Speichern Sie die Ansichten im Unterverzeichnis sources.

Wenn Sie dann intermediate- oder outputs-Tabellen erstellen, verweisen Sie auf die Ansichten anstelle von unformatierten Quelltabellen. Mit diesem Ansatz können Sie die Quelltabellen testen. Wenn sich eine Quelltabelle ändert, können Sie ihre Ansicht ändern, indem Sie beispielsweise Filter hinzufügen oder Daten neu umwandeln.

Best Practices für intermediate

Das Unterverzeichnis intermediate enthält die zweite Phase Ihres SQL-Workflows: Transformation und Aggregation von Quelldaten aus einer oder mehreren Quellen.

Speichern Sie im Unterverzeichnis intermediate Dateien, die Quelldaten aus einer oder mehreren Quellen erheblich transformieren, im Unterverzeichnis sources, z. B. Tabellen, die Daten zusammenführen. Tabellen im Unterverzeichnis intermediate fragen normalerweise Daten aus Quelltabellen oder anderen intermediate-Tabellen ab.

Verwenden Sie intermediate-Tabellen, um outputs-Tabellen zu erstellen. In der Regel werden intermediate-Tabellen nicht für zusätzliche Zwecke wie z. B. Datenanalysen verwendet, nachdem Dataform sie in BigQuery ausgeführt hat. Sie können sich intermediate-Tabellen als Datentransformationslogik vorstellen, die das Erstellen von Ausgabetabellen ermöglicht.

Wir empfehlen, alle intermediate-Tabellen zu dokumentieren und zu testen.

Best Practices für outputs

Das Unterverzeichnis outputs enthält die letzte Phase Ihres SQL-Workflows: das Erstellen von Ausgabetabellen für Ihre Geschäftszwecke aus transformierten Daten.

Speichern Sie im Verzeichnis outputs Tabellen, die Sie in zusätzlichen Prozessen oder Tools verwenden möchten, nachdem Dataform sie in BigQuery ausgeführt hat, z. B. Berichte oder Dashboards. Tabellen im Verzeichnis outputs fragen normalerweise Daten aus intermediate-Tabellen ab.

Gruppieren Sie outputs-Tabellen nach der Geschäftseinheit, zu der sie gehören, z. B. Marketing, Bestellungen oder Analysen. Weisen Sie jeder Geschäftseinheit ein Unterverzeichnis zu.

Wenn Sie Ausgabetabellen separat in BigQuery speichern möchten, können Sie ein dediziertes Schema für Ausgabetabellen konfigurieren. Eine Anleitung zum Konfigurieren des Tabellenschemas finden Sie unter Zusätzliche Tabelleneinstellungen konfigurieren.

Das folgende Beispiel zeigt eine Unterverzeichnisstruktur von outputs mit zwei Geschäftseinheiten:

definitions/
    outputs/
        orders/
            orders.sqlx
            returns.sqlx
        sales/
            sales.sqlx
            revenue.sqlx
        marketing/
            campaigns.sqlx

Wir empfehlen, alle outputs-Tabellen zu dokumentieren und zu testen.

Namensstrategie

Die Namen aller Dateien in Dataform müssen den Benennungsrichtlinien für BigQuery-Tabellen entsprechen.

Wir empfehlen, dass die Namen der Dateien im Verzeichnis definitions in einem Dataform-Repository die Unterverzeichnisstruktur widerspiegeln.

Die Dateinamen im Unterverzeichnis sources sollten auf die Quelldatei verweisen, auf die sich die Datei bezieht. Fügen Sie den Namen der Quelle als Präfix zu Dateinamen hinzu, z. B. analytics_filtered.sqlx.

Im Unterverzeichnis intermediate sollten die Dateinamen das Unterverzeichnis identifizieren, damit Mitbearbeiter intermediate-Dateien klar unterscheiden können. Wählen Sie ein eindeutiges Präfix aus und wenden Sie es nur auf Dateien im Verzeichnis intermediate an. Beispiel: stg_ads_concept.sqlx

Die Dateinamen im Unterverzeichnis outputs sollten kurz gehalten werden, z. B. orders.sqlx. Wenn Sie outputs-Tabellen mit denselben Namen in verschiedenen Entitätsunterverzeichnissen haben, fügen Sie ein Präfix hinzu, das die Entität identifiziert, z. B. sales_revenue.sqlx und ads_revenue.sqlx.

Das folgende Beispiel zeigt eine Unterverzeichnisstruktur im Verzeichnis definitions mit Dateinamen, die der empfohlenen Benennungsstrategie entsprechen:

definitions/
    sources/
        google_analytics.sqlx
        google_analytics_filtered.sqlx
    intermediate/
        stg_analytics_concept.sqlx
    outputs/
        customers.sqlx
        sales/
            sales.sqlx
            sales_revenue.sqlx
        ads/
            campaigns.sqlx
            ads_revenue.sqlx

Nächste Schritte