Kompilierungsüberschreibungen mit der Dataform API konfigurieren

In diesem Dokument erfahren Sie, wie Sie mit der Dataform API Kompilierungsergebnisse mit Kompilierungsüberschreibungen erstellen und ausführen.

Kompilierungsüberschreibungen für die Dataform API

Zum Ausführen des SQL-Workflows kompiliert Dataform Ihren Code in SQL, um ein Compilationsergebnis zu erstellen. Während eines Workflowaufrufs führt Dataform dann das Kompilierungsergebnis in BigQuery aus.

Standardmäßig verwendet Dataform die Einstellungen in der Datei dataform.json, um das Kompilierungsergebnis zu erstellen. Wenn Sie Daten isolieren möchten, die in verschiedenen Phasen Ihres Entwicklungslebenszyklus ausgeführt werden, können Sie die Standardeinstellungen mit Kompilierungsüberschreibungen überschreiben.

Wenn Sie Dataform API-Anfragen im Terminal übergeben, können Sie ein einzelnes Kompilierungsergebnis mit Kompilierungsüberschreibungen erstellen und ausführen. Sie können ein Kompilierungsergebnis für einen Arbeitsbereich oder ein ausgewähltes Git-Commitish erstellen.

Zum Kompilieren eines Ergebnisses mit Kompilierungsüberschreibungen müssen Sie die Dataform API-Anfrage compilationResults.create erhöhen. In der Anfrage müssen Sie eine Quelle, einen Arbeitsbereich oder Git-Commits angeben, damit Dataform im Kompilierungsergebnis kompiliert werden kann. Im CodeCompilationConfig-Objekt der compilationResults.create-Anfrage können Sie Kompilierungsüberschreibungen konfigurieren.

Anschließend können Sie das kompilierte Ergebnis in einer Dataform API-workflowInvocations.create-Anfrage ausführen.

Mit der Dataform API können Sie die folgenden Kompilierungsüberschreibungen konfigurieren:

Google Cloud-Projekt
Ein Google Cloud-Projekt, in dem Dataform das Kompilierungsergebnis ausführt, in dataform.json als defaultDatabase festgelegt.
Tabellenpräfix
Ein benutzerdefiniertes Präfix, das allen Tabellennamen im Kompilierungsergebnis hinzugefügt wird.
Schema Suffix
Benutzerdefiniertes Suffix, das an das Schema der Tabellen angehängt ist, die in defaultSchema in dataform.json oder im Parameter schema im config-Block einer Tabelle definiert sind.
Wert einer Vergleichsvariable
Wert einer Compilation-Variable, die im Kompilierungsergebnis verwendet werden soll. Sie können Kompilierungsvariablen verwenden, um Tabellen bedingt auszuführen.

Als Alternative zur Kompilierung der Dataform API, die Sie nur für ein einziges Kompilierungsergebnis verwenden können, können Sie die Kompilierung von Arbeitsbereichen in der Google Cloud Console konfigurieren.

Hinweis

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

    Zu Dataform

  2. Wählen Sie ein Repository aus oder erstellen Sie ein Repository.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus oder erstellen Sie einen.

Kompilierungsergebnisquelle festlegen

Wenn Sie die Dataform API-Anfrage compilationResults.create auslösen möchten, müssen Sie eine Quelle für das Kompilierungsergebnis angeben.

Sie können einen Dataform-Arbeitsbereich oder einen Git-Zweig, ein Git-Tag oder ein Git-Commit-SHA als Quelle in der compilationResults.create-Anfrage festlegen.

Arbeitsbereich als Zusammenstellung von Ergebnisergebnissen festlegen

  • Geben Sie in der Anfrage compilationResults.create das Attribut workspace mit dem Pfad eines ausgewählten Dataform-Arbeitsbereichs im folgenden Format an:
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

Dabei gilt:

  • PROJECT_NAME durch den Namen Ihres Google Cloud-Projekts.
  • LOCATION durch den Speicherort Ihres Dataform-Repositorys, festgelegt in dataform.json.
  • REPOSITORY_NAME durch den Namen Ihres Dataform-Repositorys.
  • WORKSPACE_NAME durch den Namen Ihres Dataform-Arbeitsbereichs.

Im folgenden Codebeispiel sehen Sie das Attribut workspace in der Anfrage compilationResults.create, das auf einen Arbeitsbereich mit dem Namen "sales-test" festgelegt ist:

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Git-Commit als Kompilationsergebnisquelle festlegen

  • Geben Sie in der Anfrage compilationResults.create das Attribut gitCommitish mit dem gewünschten Git-Zweig, Tag oder Commit-SHA im folgenden Format ein:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Ersetzen Sie GIT_COMMITISH durch den gewünschten Git-Zweig, das Git-Tag oder ein Git-Commit-SHA für das Kompilierungsergebnis.

Im folgenden Codebeispiel sehen Sie das Attribut gitCommitish in der compilationResults.create-Anfrage, für die "staging" festgelegt wurde:

{
  "gitCommitish": "staging"
}

Google Cloud-Standardprojekt überschreiben

Wenn Sie in einem Google Cloud-Projekt Staging- oder Produktionstabellen erstellen möchten, die vom Entwicklungsprojekt getrennt sind, können Sie im Objekt CodeCompilationConfig der compilationResults.create-Anfrage der Dataform API eine andere Google Cloud-Projekt-ID übergeben.

Durch das Übergeben einer separaten Standardprojekt-ID in der compilationResults.create-Anfrage wird die in der Datei dataform.json konfigurierte Projekt-ID von Google Cloud überschrieben. Die in einzelnen Tabellen konfigurierten Google Cloud-Projekt-IDs werden jedoch nicht überschrieben.

  • Wenn Sie die standardmäßige Google Cloud-Projekt-ID überschreiben möchten, legen Sie die Property defaultDatabase auf die gewünschte Google Cloud-Projekt-ID im Objekt CodeCompilationConfig im folgenden Format fest:

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

Ersetzen Sie PROJECT_NAME durch die Google Cloud-Projekt-ID, die Sie für das Kompilierungsergebnis festlegen möchten.

Tabellenpräfix hinzufügen

Wenn Sie Tabellen aus dem Kompilierungsergebnis ganz einfach ermitteln möchten, können Sie allen Tabellennamen im Kompilierungsergebnis ein Präfix hinzufügen. Dazu übergeben Sie das Tabellenpräfix im CodeCompilationConfig-Objekt in der Dataform API-compilationResults.create-Anfrage.

  • Wenn Sie ein Tabellenpräfix hinzufügen möchten, legen Sie die Property tablePrefix im Objekt CodeCompilationConfig im folgenden Format fest:
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Ersetzen Sie PREFIX durch das Suffix, das Sie anhängen möchten, z. B. _staging. Wenn Ihre defaultSchema in dataform.json beispielsweise auf dataform festgelegt ist, erstellt Dataform Tabellen im Schema dataform_staging.

Schema-Suffix anhängen

Wenn Sie Entwicklungs-, Staging- und Produktionsdaten trennen möchten, können Sie einem Schema in einem Kompilierungsergebnis ein Suffix anhängen. Dazu übergeben Sie das Schema-Suffix in dem CodeCompilationConfig-Objekt in der Dataform API-Anfrage compilationResults.create.

  • Wenn Sie ein Schema-Suffix anhängen möchten, legen Sie die Property schemaSuffix im Objekt CodeCompilationConfig im folgenden Format fest:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Ersetzen Sie SUFFIX durch das Suffix, das Sie anhängen möchten, z. B. _staging. Wenn Ihre defaultSchema in dataform.json beispielsweise auf dataform festgelegt ist, erstellt Dataform Tabellen im Schema dataform_staging.

Hinweis:Der Parameter CodeCompilationConfig schemaSuffix überschreibt Schemas, die im config-Block einzelner Dateien konfiguriert sind.

Ausgewählte Dateien bedingt mit Kompilierungsvariablen ausführen

Wenn Sie eine ausgewählte Tabelle nur in einer bestimmten Ausführungseinstellung ausführen möchten, können Sie eine Compilation-Variable für die Ausführungseinstellung erstellen und dann ihren Wert im CodeCompilationConfig-Objekt in der Dataform API-Anfrage compilationResults.create übergeben.

So führen Sie mit der Dataform API eine Tabelle bedingt in einer bestimmten Ausführungseinstellung aus:

  1. Erstellen Sie eine Vergleichsvariable und fügen Sie sie ausgewählten Tabellen hinzu.

  2. Legen Sie das Schlüssel/Wert-Paar YOUR_VARIABLE und VALUE im codeCompilationConfig-Block einer Dataform API-Kompilierungsanfrage im folgenden Format fest:

    {
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}

  3. Ersetzen Sie YOUR_VARIABLE durch den Namen Ihrer Variablen, z. B. executionSetting.

  4. Ersetzen Sie VALUE durch den Wert der Variablen für dieses Kompilierungsergebnis, das die in den ausgewählten Tabellen festgelegten when-Bedingung erfüllt.

Im folgenden Codebeispiel sehen Sie die Variable executionSetting, die an eine Dataform API-Compilation-Anfrage übergeben wird:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Kompilierungsergebnis mit Kompilierungsüberschreibungen ausführen

  • Wenn Sie das Kompilationsergebnis ausführen möchten, das von einer compilationResults.create-Anfrage erstellt wurde, übergeben Sie die von der compilationResults.create-Anfrage zurückgegebene Kompilationsergebnis-ID in einer workflowInvocations.create-Anfrage.

Das folgende Codebeispiel zeigt eine Kompilationsergebnis-ID, die in einer workflowInvocations.create-Anfrage übergeben wird:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Nächste Schritte