Einstellungen für Dataform-Workflow konfigurieren

Auf dieser Seite erfahren Sie, wie Sie die SQL-Workflowverarbeitung in Dataform bearbeiten für ein bestimmtes Repository.

Sie können die Einstellungsdatei bearbeiten, um die Schemas umzubenennen, oder benutzerdefinierte Kompilierungsvariablen in Ihr Repository.

Informationen zu Repository-Einstellungen

Jedes Dataform-Repository enthält einen eindeutigen Workflow Einstellungsdatei. Die Datei enthält die Google Cloud-Projekt-ID und das Schema in wie Dataform Assets in BigQuery veröffentlicht. Dataform verwendet Standardeinstellungen die Sie überschreiben können, indem Sie die Einstellungsdatei bearbeiten.

Seit Dataform Core 3.0.0 Workflow-Einstellungen werden standardmäßig in der Datei "workflow_settings.yaml" gespeichert. In früheren Versionen von Dataform Core Workflow-Einstellungen werden in der Datei dataform.json gespeichert. Die workflow_settings.yaml-Datei von Dataform Core 3.0 ist abwärtskompatibel mit dataform.json. Sie können weiterhin dataform.json zum Speichern der Workflow-Einstellungen. Als Best Practice sollten Sie Workflow-Einstellungen für Repositories migrieren für zukünftige Kompatibilität in das workflow_settings.yaml-Format geändert.

Über workflow_settings.yaml

Die Datei workflow_settings.yaml, die im Dataform Core 3.0 speichert Dataform-Workflow-Einstellungen im Format YAML.

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 wie folgt beschrieben:

  • defaultProject: Ihre Google Cloud-Projekt-ID für BigQuery.
  • defaultDataset: Das BigQuery-Dataset, in dem Dataform erstellt Assets, die standardmäßig als dataform bezeichnet werden.
  • defaultLocation: Ihre Standardregion des BigQuery-Datasets. Weitere Informationen zu BigQuery-Dataset-Standorten Siehe Dataset-Standorte Dort verarbeitet Dataform Ihren Code und speichert ausgeführte Daten. Diese Verarbeitungsregion muss mit dem Standort übereinstimmen Ihrer BigQuery-Datasets, muss aber nicht Dataform-Repository-Region.
  • defaultAssertionDataset: Das BigQuery-Dataset, in dem Dataform erstellt Ansichten mit Assertion-Ergebnissen, Standardmäßig dataform_assertions.

Weitere Informationen zu workflow_settings.yaml-Attributen findest du unter Konfigurationsreferenz für Workfloweinstellungen in GitHub.

Sie können auf die in workflow_settings.yaml definierten Properties zugreifen in Ihrem Dataform-Code als Attribute der dataform.projectConfig -Objekt enthält.

Die folgenden Zuordnungen von workflow_settings.yaml-Optionen zum zugänglichen Code Es gelten dataform.projectConfig Optionen:

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

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

  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 Einstellungen für Dataform-Workflows gespeichert im Format JSON.

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 wie folgt beschrieben:

  • warehouse: Zeiger auf BigQuery, wobei Dataform erstellt Assets.
  • defaultDatabase: Ihre Google Cloud-Projekt-ID für BigQuery.
  • defaultSchema: Das BigQuery-Dataset, in dem Dataform erstellt Assets.
  • defaultLocation: Ihre Standardregion des BigQuery-Datasets. Weitere Informationen zu BigQuery-Dataset-Standorten Siehe Dataset-Standorte. Dort verarbeitet Dataform Ihren Code und speichert ausgeführte Daten. Diese Verarbeitungsregion muss mit dem Standort übereinstimmen Ihrer BigQuery-Datasets, muss aber nicht Dataform-Repository-Region.
  • assertionSchema: Das BigQuery-Dataset, in dem Dataform erstellt Ansichten mit Assertion-Ergebnissen, Standardmäßig dataform_assertions.

Sie können folgendermaßen auf die in dataform.json definierten Attribute in Ihrem Projektcode zugreifen: Eigenschaften von dataform.projectConfig -Objekt enthält.

Hinweise

  1. Erstellen Sie ein Repository.

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

Erforderliche Rollen

Um die Berechtigungen zu erhalten, die Sie zum Konfigurieren der Dataform-Einstellungen benötigen, bitten Sie Ihren Administrator, Ihnen IAM-Rolle Dataform Admin (roles/dataform.admin) für Repositories. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

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

Schemanamen konfigurieren

Zum Konfigurieren von Schemanamen müssen Sie die defaultDataset und defaultAssertionSchema Unterkünfte in die Datei workflow_settings.yaml oder den defaultSchema und assertionSchema in der Datei dataform.json.

So konfigurieren Sie den Namen eines Schemas:

workflow_settings.yaml

  1. Klicken Sie im Entwicklungsarbeitsbereich im Bereich Dateien auf workflow_settings.yaml-Datei.

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

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

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. Klicken Sie im Entwicklungsarbeitsbereich im Bereich Dateien auf dataform.json-Datei.

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

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

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

Benutzerdefinierte Kompilierungsvariablen erstellen

Kompilierungsvariablen enthalten Werte, die Sie durch die Kompilierung ändern können Überschreibungen in einer Releasekonfiguration oder in einer Dataform API-Anfrage.

Nachdem Sie in workflow_settings.yaml eine Kompilierungsvariable definiert und zum ausgewählten Tabellen ausgewählt haben, können Sie deren Wert in einer Releasekonfiguration ändern oder Dataform API-Kompilierungsüberschreibungen Tabellen bedingt ausführen.

Weitere Informationen zum bedingten Ausführen von Tabellen mithilfe der Kompilierungsvariablen, siehe Einführung in den Codelebenszyklus in Dataform

Um eine Kompilierungsvariable zu erstellen, die Sie in einem Repository verwenden können, führen Sie folgende Schritte aus:

workflow_settings.yaml

  1. Rufen Sie den 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 Kompilierungsvariable.

Das folgende Codebeispiel zeigt den Kompilierungsvariablensatz myVariableName zu myVariableValue in der Datei workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

Das folgende Codebeispiel zeigt die Datei workflow_settings.yaml mit dem Die Kompilierungsvariable executionSetting wurde auf dev festgelegt:

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

dataform.json

  1. Rufen Sie den 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 Kompilierungsvariable.

Das folgende Codebeispiel zeigt den Kompilierungsvariablensatz myVariableName zu myVariableValue in der Datei dataform.json:

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

Das folgende Codebeispiel zeigt die Datei dataform.json mit dem Die Kompilierungsvariable executionSetting wurde auf dev festgelegt:

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

Kompilierungsvariable in eine Tabelle einfügen

Um einer SQLX-Tabellendefinitionsdatei eine Kompilierungsvariable hinzuzufügen, führen Sie folgende Schritte aus:

  1. Rufen Sie den Dataform-Entwicklungsarbeitsbereich auf.
  2. Wählen Sie im Bereich Dateien eine SQLX-Tabellendefinitionsdatei 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, Beispiel: executionSetting.
    • SET_VALUE durch einen Wert für die Variable z. B. staging.
    • CONDITION durch eine Bedingung zur Ausführung der Tabelle.

Das folgende Codebeispiel zeigt eine Tabellendefinitions-SQLX-Datei mit einem when und die Variable executionSetting, die 10% der Daten in der Einstellung für die Staging-Ausführung:

  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 Ansichtsdefinition mit einem when. und die Variable 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

Um sicherzustellen, dass Ihre Workflow-Einstellungsdatei mit zukünftigen Versionen kompatibel ist Dataform Core Framework-Versionen sollten Sie Ihren Workflow migrieren. Einstellungen aus der Datei dataform.json in die Datei workflow_settings.yaml.

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

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

In der folgenden Tabelle sehen Sie, wie Eigenschaften von Workflow-Einstellungen dataform.json in workflow_settings.yaml:

Immobilien in dataform.json Immobilien in workflow_settings.yaml Beschreibung
assertionSchema defaultAssertionDataset Erforderlich. Das Standard-Dataset für Assertions.
defaultDatabase defaultProject Erforderlich. Der Standardname des Google Cloud-Projekts.
defaultLocation defaultLocation Erforderlich. Der BigQuery-Standardspeicherort, an dem Dataform Tabellen erstellt. Weitere Informationen zu BigQuery-Standorten finden Sie unter Dataset-Standorte.
defaultSchema defaultDataset Erforderlich. Das 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 Aktions-Datasets angehängt werden soll.
tablePrefix namePrefix Optional. Das Präfix, das allen Aktionsnamen vorangestellt werden soll.
vars vars Optional. Benutzerdefinierte Variablen, die während der Kompilierung dem Projektcode 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. Nicht verfügbar in workflow_settings.yaml.
- dataformCoreVersion Nicht verfügbar in dataform.json. Ist für neue Repositories standardmäßig in workflow_settings.yaml enthalten. Weitere Informationen finden Sie unter Dataform-Kernpaket verwalten.

So migrieren Sie Workfloweinstellungen 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 addAdd, und klicken Sie dann auf Datei erstellen.

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

  5. Klicken Sie auf Datei erstellen.

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

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

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

Im folgenden Codebeispiel sehen Sie die Workfloweinstellungen, die in eine dataform.json-Datei:

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

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

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

Nächste Schritte