Dataform-Workfloweinstellungen konfigurieren

Auf dieser Seite erfahren Sie, wie Sie die Verarbeitungseinstellungen für den Dataform-SQL-Workflow für ein bestimmtes Repository bearbeiten.

Sie können die Einstellungsdatei bearbeiten, um die Schemas umzubenennen oder Ihrem Repository benutzerdefinierte Kompilierungsvariablen hinzuzufügen.

Repository-Einstellungen

Jedes Dataform-Repository enthält eine eindeutige Datei mit Workflow-Einstellungen. Die Datei enthält die Google Cloud-Projekt-ID und das Schema, in dem Dataform Assets in BigQuery veröffentlicht. Dataform verwendet Standardeinstellungen, die Sie überschreiben können, um sie an Ihre Anforderungen anzupassen. Bearbeiten Sie dazu die Einstellungsdatei.

Ab Dataform Core 3.0.0 werden Workflow-Einstellungen standardmäßig in der Datei „workflow_settings.yaml“ gespeichert. In früheren Versionen von Dataform Core werden Workflow-Einstellungen in der Datei dataform.json gespeichert. Die Dataform Core 3.0-workflow_settings.yaml-Datei ist abwärtskompatibel mit dataform.json. Sie können dataform.json weiterhin zum Speichern von Workflow-Einstellungen verwenden. Aus Gründen der zukünftigen Kompatibilität sollten Sie Ihre Repository-Workflow-Einstellungen in das workflow_settings.yaml-Format migrieren.

Über workflow_settings.yaml

Die Datei workflow_settings.yaml, die in Dataform Core 3.0 eingeführt wurde, speichert Dataform-Workflow-Einstellungen im YAML-Format.

Das folgende Codebeispiel zeigt eine workflow_settings.yaml-Beispieldatei:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

Im vorherigen Codebeispiel werden die Schlüssel/Wert-Paare so beschrieben:

  • defaultProject: Die Google Cloud-Projekt-ID Ihres BigQuery-Projekts.
  • defaultDataset: Das BigQuery-Dataset, in dem Dataform Assets erstellt. Standardmäßig heißt es dataform.
  • defaultLocation: Die Standardregion Ihres BigQuery-Datasets. Weitere Informationen zu BigQuery-Datensatzstandorten finden Sie unter Datensatzstandorte. An diesem Standort verarbeitet Dataform Ihren Code und speichert die ausgeführten Daten. Diese Verarbeitungsregion muss mit dem Speicherort Ihrer BigQuery-Datasets übereinstimmen, aber nicht mit der Region des Dataform-Repositories.
  • defaultAssertionDataset: Das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt. Standardmäßig heißt es dataform_assertions.

Weitere Informationen zu workflow_settings.yaml-Properties findest du in der Referenz für Konfigurationen für Workflow-Einstellungen auf GitHub.

Sie können im Dataform-Code auf die in workflow_settings.yaml definierten Eigenschaften als Eigenschaften des Objekts dataform.projectConfig zugreifen.

Die folgenden Zuordnungen von workflow_settings.yaml-Optionen zu den im Code zugänglichen dataform.projectConfig-Optionen gelten:

  • defaultProject => defaultDatabase.
  • defaultDataset => defaultSchema.
  • defaultAssertionDataset => assertionSchema.
  • projectSuffix => databaseSuffix.
  • datasetSuffix => schemaSuffix.
  • namePrefix => tablePrefix.

Das folgende Codebeispiel zeigt das dataform.projectConfig-Objekt, auf das in einer SELECT-Anweisung in einer Ansicht verwiesen wird:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

Über dataform.json

In der Datei dataform.json werden die Dataform-Workflow-Einstellungen im JSON-Format gespeichert.

Das folgende Codebeispiel zeigt eine dataform.json-Beispieldatei:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

Im vorherigen Codebeispiel werden die Schlüssel/Wert-Paare so beschrieben:

  • warehouse: Verweis auf BigQuery, in dem Dataform Assets erstellt.
  • defaultDatabase: Die Google Cloud-Projekt-ID Ihres BigQuery-Projekts.
  • defaultSchema: Das BigQuery-Dataset, in dem Dataform Assets erstellt.
  • defaultLocation: Die Standardregion Ihres BigQuery-Datasets. Weitere Informationen zu BigQuery-Datensatzstandorten finden Sie unter Dataset-Standorte. An diesem Speicherort verarbeitet Dataform Ihren Code und speichert die ausgeführten Daten. Diese Verarbeitungsregion muss mit dem Speicherort Ihrer BigQuery-Datasets übereinstimmen, aber nicht mit der Region des Dataform-Repositories.
  • assertionSchema: Das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt. Standardmäßig heißt es dataform_assertions.

Sie können in Ihrem Projektcode auf die in dataform.json definierten Eigenschaften als Eigenschaften des Objekts dataform.projectConfig zugreifen.

Hinweis

  1. Erstellen Sie ein Repository.

  2. Erstellen und initialisieren Sie einen Entwicklungsarbeitsbereich in Ihrem Repository.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dataform Admin (roles/dataform.admin) für Repositories zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Konfigurieren von Dataform-Einstellungen benötigen. 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.

Schemanamen konfigurieren

Wenn Sie Schemanamen konfigurieren möchten, müssen Sie die Eigenschaften defaultDataset und defaultAssertionSchema in der Datei workflow_settings.yaml oder die Eigenschaften defaultSchema und assertionSchema in der Datei dataform.json bearbeiten.

So konfigurieren Sie den Namen eines Schemas:

workflow_settings.yaml

  1. Klicken Sie in Ihrem Entwicklungsbereich im Bereich Dateien auf die Datei workflow_settings.yaml.

  2. Bearbeiten Sie den Wert von defaultDataset, defaultAssertionSchema oder beiden.

Das folgende Codebeispiel zeigt einen benutzerdefinierten defaultDataset-Namen, der in der Datei workflow_settings.yaml definiert ist:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. Klicken Sie in Ihrem Entwicklungsbereich im Bereich Dateien auf die Datei dataform.json.

  2. Bearbeiten Sie den Wert von defaultSchema, assertionSchema oder beiden.

Das folgende Codebeispiel zeigt einen benutzerdefinierten defaultSchema-Namen, der in der Datei dataform.json definiert ist:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Benutzerdefinierte Kompilierungsvariablen erstellen

Kompilierungsvariablen enthalten Werte, die Sie mit Kompilierungsüberschreibungen in einer Release-Konfiguration oder in einer Dataform API-Anfrage ändern können.

Nachdem Sie eine Kompilierungsvariable in workflow_settings.yaml definiert und ausgewählten Tabellen hinzugefügt haben, können Sie ihren Wert in einer Release-Konfiguration oder in Überschreibungen für die Dataform API-Kompilierung ändern, um Tabellen bedingt auszuführen.

Weitere Informationen zum bedingten Ausführen von Tabellen mithilfe von Kompilierungsvariablen finden Sie unter Einführung in den Codelebenszyklus in Dataform.

So erstellen Sie eine Kompilierungsvariable, die Sie für ein gesamtes Repository verwenden können:

workflow_settings.yaml

  1. Rufen Sie Ihren Dataform-Entwicklungsarbeitsbereich auf.
  2. Wählen Sie im Bereich Dateien die Datei workflow_settings.yaml aus.

  3. Geben Sie das folgende Code-Snippet ein:

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

    Ersetzen Sie Folgendes:

    • YOUR_VARIABLE durch einen Namen für die Variable.
    • VALUE durch den Standardwert der Kompilierungsvariablen.

Im folgenden Codebeispiel ist die myVariableName-Kompilierungsvariable in der Datei workflow_settings.yaml auf myVariableValue festgelegt:

...
vars:
  myVariableName: myVariableValue
...

Das folgende Codebeispiel zeigt die workflow_settings.yaml-Datei mit der executionSetting-Kompilierungsvariablen, die auf dev festgelegt ist:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Rufen Sie Ihren Dataform-Entwicklungsarbeitsbereich auf.
  2. Wählen Sie im Bereich Dateien die Datei dataform.json aus.

  3. Geben Sie das folgende Code-Snippet ein:

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

    Ersetzen Sie Folgendes:

    • YOUR_VARIABLE durch einen Namen für die Variable.
    • VALUE durch den Standardwert der Kompilierungsvariablen.

Im folgenden Codebeispiel ist die myVariableName-Kompilierungsvariable in der Datei dataform.json auf myVariableValue festgelegt:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

Das folgende Codebeispiel zeigt die dataform.json-Datei mit der executionSetting-Kompilierungsvariablen, die auf dev festgelegt ist:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Tabelle eine Kompilierungsvariable hinzufügen

So fügen Sie einer SQLX-Tabellendefinition eine Kompilierungsvariable hinzu:

  1. Rufen Sie Ihren Dataform-Entwicklungsarbeitsbereich auf.
  2. Wählen Sie im Bereich Dateien eine SQLX-Tabellendefinitiondatei aus.

  3. Geben Sie in der Datei eine when-Klausel im folgenden Format ein:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Ersetzen Sie Folgendes:

    • YOUR_VARIABLE durch den Namen Ihrer Variablen, z. B. executionSetting.
    • SET_VALUE durch einen Wert für die Variable, z. B. staging.
    • CONDITION mit einer Bedingung für die Ausführung der Tabelle.

Im folgenden Codebeispiel wird eine SQLX-Datei mit einer when-Klausel und der Variablen executionSetting gezeigt, mit der 10% der Daten in der Einstellung für die Stagingausführung ausgeführt werden:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

Das folgende Codebeispiel zeigt eine SQLX-Datei mit einer when-Klausel und der Variablen myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Workfloweinstellungen zu workflow_settings.yaml migrieren

Damit Ihre Workflow-Einstellungen mit zukünftigen Versionen des Dataform Core-Frameworks kompatibel sind, sollten Sie Ihre Workflow-Einstellungen aus der Datei dataform.json in die Datei workflow_settings.yaml migrieren.

Die Datei workflow_settings.yaml ersetzt die Datei dataform.json.

Wenn Dataform Core das einzige Abhängigkeitspaket in Ihrem Repository ist, ersetzt die Datei workflow_settings.yaml auch die Datei package.json. Weitere Informationen zum Ersetzen von package.json durch workflow_settings.yaml finden Sie unter Dataform-Kernpaket verwalten.

In der folgenden Tabelle ist die Zuordnung der Eigenschaften der Workfloweinstellungen von dataform.json zu workflow_settings.yaml zu sehen:

Unterkunft in dataform.json Unterkunft in workflow_settings.yaml Beschreibung
assertionSchema defaultAssertionDataset Erforderlich. Der Standarddatensatz für Behauptungen.
defaultDatabase defaultProject Erforderlich. Der Standardprojektname Google Cloud .
defaultLocation defaultLocation Erforderlich. Der Standardspeicherort in BigQuery, an dem Dataform Tabellen erstellt. Weitere Informationen zu BigQuery-Standorten finden Sie unter Dataset-Standorte.
defaultSchema defaultDataset Erforderlich. Der Standard-Dataset.
databaseSuffix projectSuffix Optional. Das Suffix, das an alle Google Cloud -Projektverweise angehängt werden soll.
schemaSuffix datasetSuffix Optional. Das Suffix, das an alle Aktionsdatensätze angehängt werden soll.
tablePrefix namePrefix Optional. Das Präfix, das allen Aktionsnamen vorangestellt werden soll.
vars vars 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.
warehouse - Erforderlich in dataform.json. Dieses Feld muss auf bigquery festgelegt sein. In workflow_settings.yaml nicht verfügbar.
- dataformCoreVersion In dataform.json nicht verfügbar. Wird standardmäßig in workflow_settings.yaml für neue Repositories installiert. Weitere Informationen finden Sie unter Dataform-Kernpaket verwalten.

So migrieren Sie Workflow-Einstellungen zu workflow_settings.yaml:

  1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

    Zur Seite „Dataform“

  2. Wählen Sie ein Repository und dann einen Arbeitsbereich aus.

  3. Klicken Sie im Bereich Dateien auf HinzufügenHinzufügen und dann auf Datei erstellen.

  4. Geben Sie im Feld Dateipfad hinzufügen workflow_settings.yaml ein.

  5. Klicken Sie auf Datei erstellen.

  6. Fügen Sie in der workflow_settings.yaml-Datei die Einstellungen aus der dataform.json-Datei hinzu, die dem YAML-Format zugeordnet sind.

  7. Klicken Sie im Bereich Dateien neben dataform.json auf das Dreipunkt-Menü Mehr und dann auf Löschen.

  8. Klicken Sie auf Löschen, um das Löschen von dataform.json zu bestätigen.

Das folgende Codebeispiel zeigt Workfloweinstellungen, die in einer dataform.json-Datei definiert sind:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

Das folgende Codebeispiel zeigt die vorherige dataform.json-Datei, die in workflow_settings.yaml konvertiert wurde:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

Nächste Schritte