Code in einem Repository strukturieren

In diesem Dokument werden Best Practices für die Strukturierung und Benennung von SQL-Workflowdateien im Stammverzeichnis definitions eines Dataform-Repositories beschrieben. Die empfohlene Struktur des definitions-Verzeichnisses spiegelt die Phasen eines SQL-Workflows wider. Sie können eine Struktur wählen, die Ihren geschäftlichen Anforderungen entspricht.

Es gibt folgende Gründe, den SQL-Workflowcode im Verzeichnis definitions zu strukturieren:

  • Sie können die Zusammenarbeit an der Codebasis verbessern, indem Sie Teams für ausgewählte Teile Ihres Workflows festlegen.
  • Verbesserung der Wartbarkeit des SQL-Workflows bei organisatorischen Änderungen
  • Verbesserung der Navigation durch Ihre Codebasis.
  • Verbesserung der Skalierbarkeit der Codebasis.
  • Minimieren des Verwaltungsaufwands 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 die 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, um Ausgabetabellen zu erstellen, die Sie für Geschäfts- oder Analysezwecke verwenden können.

Es gibt drei wichtige Phasen eines SQL-Workflows:

  1. Erklärung zu Datenquellen
  2. Transformation der Quelldaten
  3. Definition von Ausgabetabellen aus den transformierten Quelldaten

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

sources
Datenquellendeklarationen und grundlegende Transformation von Quelldaten, z. B. Filterung.
intermediate
Tabellen und Aktionen, die Daten aus sources lesen und transformieren, bevor Sie die transformierten Daten zum Definieren von outputs-Tabellen verwenden. Tabellen, die nach der Ausführung in BigQuery durch Dataform in der Regel nicht mit zusätzlichen Prozessen oder Tools wie Business Intelligence-Tools (BI) verarbeitet werden.
outputs
Definitionen von Tabellen, die von Prozessen oder Tools wie BI verwendet werden, nachdem sie von Dataform in BigQuery ausgeführt wurden.
extra
Dateien außerhalb der Hauptpipeline Ihres SQL-Workflows, z. B. Dateien mit Workflowdaten, die für eine zusätzliche Verwendung vorbereitet wurden, z. B. für maschinelles Lernen. 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, gewandelt oder umbenannt werden.

Speichern Sie keine Tabellen, in denen Daten aus mehreren Quellen kombiniert werden.

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

Wenn Sie Datenquellen aus mehreren Pools deklarieren, z. B. aus Google Ads oder Google Analytics, weisen Sie jedem Pool ein eigenes 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 im selben Schema deklarieren, können Sie ihre Deklarationen in einer einzigen JavaScript-Datei zusammenführen. Weitere Informationen zum Erstellen von Datenquellendeklarationen mit JavaScript finden Sie unter Dataform-Workflows mit JavaScript erstellen.

Das folgende Codebeispiel zeigt mehrere Datenquellen in einem Schema, die in einer einzigen JavaScript-Datei deklariert sind:

[
  "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 eine grundlegende Filterung und Formatierung der Quelldaten enthalten. Speichern Sie die Ansichten im Unterverzeichnis sources.

Wenn Sie dann intermediate- oder outputs-Tabellen erstellen, verweisen Sie auf die Ansichten anstelle der Roh-Quelltabellen. Mit diesem Ansatz können Sie die Quelltabellen testen. Wenn sich eine Quelltabelle ändert, können Sie die Ansicht ändern, z. B. durch Hinzufügen von Filtern oder Umwandeln von Daten.

Best Practices für intermediate

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

Speichern Sie im Unterverzeichnis intermediate Dateien, die Quelldaten aus einer oder mehreren Quellen im Unterverzeichnis sources erheblich transformieren, z. B. Tabellen, die Daten zusammenführen. In Tabellen im Unterverzeichnis intermediate werden in der Regel Daten aus Quelltabellen oder anderen intermediate-Tabellen abgefragt.

Mit intermediate-Tabellen können Sie outputs-Tabellen erstellen. Normalerweise werden intermediate-Tabellen nicht für zusätzliche Zwecke wie Datenanalysen verwendet, nachdem sie von Dataform in BigQuery ausgeführt wurden. Sie können sich intermediate-Tabellen als die Logik der Datentransformation 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äftlichen Zwecke aus transformierten Daten.

Speichern Sie im Verzeichnis outputs Tabellen, die Sie in zusätzlichen Prozessen oder Tools verwenden möchten, nachdem sie von Dataform in BigQuery ausgeführt wurden, z. B. Berichte oder Dashboards. In Tabellen im Verzeichnis outputs werden in der Regel Daten aus intermediate-Tabellen abgefragt.

Gruppieren Sie outputs-Tabellen nach dem zugehörigen Geschäftsobjekt, z. B. Marketing, Bestellungen oder Analysen. Weisen Sie jedem Rechtssubjekt ein eigenes Unterverzeichnis zu.

Wenn Sie Ausgabetabellen separat in BigQuery speichern möchten, können Sie ein spezielles 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 den Geschäftsentitäten sales und marketing:

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.

Benennungsstrategie

Die Namen aller Dateien in Dataform müssen den Richtlinien für die Benennung von BigQuery-Tabellen entsprechen.

Wir empfehlen, dass die Namen der Dateien im Verzeichnis definitions in einem Dataform-Repository der Struktur der Unterverzeichnisse entsprechen.

Im Unterverzeichnis sources sollten die Dateinamen auf die Quelle verweisen, mit der die Datei verknüpft ist. 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 prägnant sein, 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