Einstellungen für Dataform-Workflow konfigurieren

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

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

Informationen zu Repository-Einstellungen

Jedes Dataform-Repository enthält eine eindeutige Datei mit den Workfloweinstellungen. 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, indem Sie die Einstellungsdatei bearbeiten.

Ab Dataform Core 3.0 werden Workfloweinstellungen standardmäßig in der Datei workflow_settings.yaml gespeichert. In früheren Versionen von Dataform Core werden Workfloweinstellungen 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 dataform.json weiterhin zum Konfigurieren von Dataform-Einstellungen verwenden.

Informationen zu workflow_settings.yaml

In der mit Dataform Core 3.0 eingeführten Datei workflow_settings.yaml werden Dataform-Workfloweinstellungen im Format YAML gespeichert.

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 Assets erstellt. Dieses Dataset wird standardmäßig als dataform bezeichnet.
  • defaultLocation: Ihre Standardregion des BigQuery-Datasets. Weitere Informationen zu BigQuery-Dataset-Standorten finden Sie unter Dataset-Standorte. An diesem Speicherort verarbeitet Dataform Ihren Code und speichert ausgeführte Daten. Diese Verarbeitungsregion muss mit dem Speicherort Ihrer BigQuery-Datasets übereinstimmen, jedoch nicht mit der Dataform-Repository-Region.
  • defaultAssertionDataset: Das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt und standardmäßig dataform_assertions genannt wird.

Weitere Informationen zu workflow_settings.yaml-Attributen finden Sie in der Konfigurationsreferenz für Workfloweinstellungen in GitHub.

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

Die folgenden Zuordnungen von workflow_settings.yaml-Optionen zu den für 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, das in einer SELECT-Anweisung in einer Ansicht aufgerufen wird:

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

Informationen zu dataform.json

In der Datei dataform.json werden Einstellungen für Dataform-Workflows im Format JSON 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 wie folgt beschrieben:

  • warehouse: Zeiger auf BigQuery, wo Dataform Assets erstellt.
  • defaultDatabase: Ihre Google Cloud-Projekt-ID für BigQuery.
  • defaultSchema: Das BigQuery-Dataset, in dem Dataform Assets erstellt. Dieses Dataset wird standardmäßig als dataform bezeichnet.
  • defaultLocation: Ihre Standardregion des BigQuery-Datasets. Weitere Informationen zu BigQuery-Dataset-Standorten finden Sie unter Dataset-Standorte. An diesem Speicherort verarbeitet Dataform Ihren Code und speichert ausgeführte Daten. Diese Verarbeitungsregion muss mit dem Speicherort Ihrer BigQuery-Datasets übereinstimmen, jedoch nicht mit der Dataform-Repository-Region.
  • assertionSchema: Das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt und standardmäßig dataform_assertions genannt wird.

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

Hinweise

  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 zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Dataform-Einstellungen benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

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

Schemanamen konfigurieren

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

So konfigurieren Sie den Namen eines Schemas:

workflow_settings.yaml

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

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

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

  ...
  defaultDataset: mytables
  ...

dataform.json

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

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

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 Releasekonfiguration 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 deren Wert in einer Releasekonfiguration oder Dataform API-Kompilierungsüberschreibungen verwenden, 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 in einem Repository verwenden können:

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, wie die Kompilierungsvariable myVariableName in der Datei workflow_settings.yaml auf myVariableValue gesetzt ist:

...
vars:
  myVariableName: myVariableValue
...

Das folgende Codebeispiel zeigt die Datei workflow_settings.yaml, in der die Kompilierungsvariable executionSetting auf dev festgelegt ist:

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, wie die Kompilierungsvariable myVariableName in der Datei dataform.json auf myVariableValue gesetzt ist:

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

Das folgende Codebeispiel zeigt die Datei dataform.json, in der die Kompilierungsvariable executionSetting auf dev festgelegt ist:

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

Kompilierungsvariable in eine Tabelle einfügen

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

  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, z. B. 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 einer when-Klausel und der Variablen executionSetting, die 10% der Daten in der Staging-Ausführungseinstellung ausführt:

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

Das folgende Codebeispiel zeigt eine SQLX-Ansichtsdefinitionsdatei 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!"
  )}

Nächste Schritte