Repository verwalten

In diesem Dokument wird beschrieben, wie Sie in Dataform Folgendes tun können:

• Dataform-Workflow-Einstellungen konfigurieren
• Dataform Core-Paket verwalten
• Versionsverwaltung für Code

Hinweis

1. Wählen Sie ein Repository aus oder erstellen Sie eines.

   Hinweis: Die Liste der Dataform-Repositories enthält nur Repositories, die für die Entwicklung von Dataform-Workflows erstellt wurden. Repositories für BigQuery Studio-Assets wie Notebooks oder gespeicherte Abfragen werden separat verwaltet und nicht in dieser Liste aufgeführt.

2. Optional: Repository mit einem Git-Repository eines Drittanbieters verbinden

3. Entwicklungsarbeitsbereich in Ihrem Repository erstellen und initialisieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen:

• Dataform-Einstellungen konfigurieren und den Speicherort des Dataform Core-Pakets verwalten: Dataform Admin (roles/dataform.admin) für Repositories.
• Dataform Core-Paket aktualisieren und Versionsverwaltung in Dataform verwenden: Dataform-Bearbeiter (roles/dataform.editor) für Arbeitsbereiche.

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.

Dataform-Workfloweinstellungen konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie die Einstellungen für die Verarbeitung von Dataform-Workflows für ein bestimmtes Repository bearbeiten.

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

Informationen zu Repository-Einstellungen

Für alle Repositories ist ein benutzerdefiniertes Dienstkonto für die Workflowausführung erforderlich und der strikte Act-as-Modus wird erzwungen. Sie können den Dataform-Standarddienst-Agent nicht zum Ausführen von Workflows verwenden.

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 durch Bearbeiten der Einstellungsdatei überschreiben können, um sie optimal an Ihre Anforderungen anzupassen.

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. Beide Konfigurationsdateien müssen sich im Stammverzeichnis Ihres Repositorys befinden. Die Dataform Core 3.0-Datei workflow_settings.yaml ist abwärtskompatibel mit der Datei dataform.json. Sie können die Datei dataform.json weiterhin zum Speichern von Workflow-Einstellungen verwenden. Als Best Practice sollten Sie Ihre Repository-Workflow-Einstellungen in das workflow_settings.yaml-Format migrieren, um die zukünftige Kompatibilität zu gewährleisten.

Über workflow_settings.yaml

In der Datei workflow_settings.yaml, die in Dataform Core 3.0 eingeführt wurde, werden Dataform-Workflow-Einstellungen im Format YAML gespeichert.

Das folgende Codebeispiel zeigt eine Beispiel-workflow_settings.yaml-Datei:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions
  dataformCoreVersion: 3.0.62
  preserveGovernanceControls: true

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

• defaultProject: Ihre BigQuery- Google Cloud -Projekt-ID.
• defaultDataset: das BigQuery-Dataset, in dem Dataform Assets erstellt, standardmäßig dataform genannt.

• defaultLocation (optional): Standardspeicherort des BigQuery-Datasets. Dataform verwendet diesen Speicherort, um Ihren Code zu verarbeiten und die Ergebnisse zu speichern. Dieser Verarbeitungsstandort muss mit dem Standort Ihrer BigQuery-Datasets übereinstimmen. Er muss jedoch nicht mit dem Standort des Dataform-Repositorys übereinstimmen.

  Wenn Sie den Parameter defaultLocation nicht festlegen, bestimmt Dataform den Standort anhand der Datasets, auf die Ihre SQL-Abfrage verweist. Das funktioniert so:

  • Wenn Ihre Abfrage auf Datasets am selben Standort verweist, verwendet Dataform diesen Standort.
  • Wenn in Ihrer Abfrage auf Datasets aus zwei oder mehr verschiedenen Standorten verwiesen wird, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
  • Wenn Ihre Abfrage nicht auf Datasets verweist, ist der Standardstandort für Dataform die Multiregion US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den standardmäßigen Standort fest. Alternativ können Sie die Systemvariable @@location in Ihrer Abfrage verwenden. Weitere Informationen finden Sie unter Standorte angeben.

• defaultAssertionDataset: das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt, standardmäßig dataform_assertions genannt.

• dataformCoreVersion: die Version des Dataform Core-Pakets, das in Ihrem Repository installiert ist. Weitere Informationen finden Sie unter Dataform-Kernpaket verwalten.

• preserveGovernanceControls (optional): Ein boolescher Wert, der angibt, ob Dataform vorhandene BigQuery-Datenrichtlinien und Data-Governance-Tags (Vorabversion) automatisch beibehält, wenn Tabellen bei Workflow-Ausführungen neu erstellt werden. Weitere Informationen finden Sie unter Metadaten für die Zugriffssteuerung beibehalten.

Weitere Informationen zu workflow_settings.yaml-Attributen finden Sie unter WorkflowSettings auf GitHub.

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

Es gelten die folgenden Zuordnungen von den workflow_settings.yaml-Optionen zu den über Code zugänglichen dataform.projectConfig-Optionen:

• 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 Dataform-Workflow-Einstellungen im Format JSON gespeichert.

Das folgende Codebeispiel zeigt eine Beispiel-dataform.json-Datei:

  {
    "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: Ein Zeiger auf BigQuery, wo Dataform Assets erstellt.
• defaultDatabase: Ihre BigQuery Google Cloud Projekt-ID.
• defaultSchema: Das BigQuery-Dataset, in dem Dataform Assets erstellt.

• defaultLocation (optional): Ihr Standardspeicherort für BigQuery-Datasets. Dataform verwendet diesen Standort, um Ihren Code zu verarbeiten und die Ergebnisse zu speichern. Dieser Verarbeitungsstandort muss mit dem Standort Ihrer BigQuery-Datasets übereinstimmen. Sie muss jedoch nicht mit dem Speicherort des Dataform-Repositorys übereinstimmen.

  Wenn Sie den Parameter defaultLocation nicht festlegen, bestimmt Dataform den Standort anhand der Datasets, auf die Ihre SQL-Abfrage verweist. Das funktioniert so:

  • Wenn Ihre Abfrage auf Datasets am selben Standort verweist, verwendet Dataform diesen Standort.
  • Wenn in Ihrer Abfrage auf Datasets aus zwei oder mehr verschiedenen Standorten verwiesen wird, tritt ein Fehler auf. Weitere Informationen zu dieser Einschränkung finden Sie unter Regionenübergreifende Dataset-Replikation.
  • Wenn Ihre Abfrage nicht auf Datasets verweist, ist der Standardspeicherort für Dataform die Multi-Region US. Wenn Sie einen anderen Standort auswählen möchten, legen Sie den standardmäßigen Standort fest. Alternativ können Sie die Systemvariable @@location in Ihrer Abfrage verwenden. Weitere Informationen finden Sie unter Standorte angeben.

• assertionSchema: das BigQuery-Dataset, in dem Dataform Ansichten mit Assertion-Ergebnissen erstellt, standardmäßig dataform_assertions genannt.

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

Schemanamen konfigurieren

Wenn Sie Schemanamen konfigurieren möchten, 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 in Ihrem 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 in Ihrem 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 Release-Konfiguration oder in einer Dataform API-Anfrage ändern können.

Nachdem Sie eine Kompilierungsvariable in workflow_settings.yaml definiert und zu ausgewählten Tabellen hinzugefügt haben, können Sie ihren Wert in einer Release-Konfiguration oder in Dataform API-Kompilierungsüberschreibungen ä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 in einem 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": {
     "VARIABLE":"VALUE"
   }
   

   Ersetzen Sie Folgendes:

   • VARIABLE: ein Name für die Variable
   • VALUE: der Standardwert der Kompilierungsvariable

Das folgende Codebeispiel zeigt die Kompilierungsvariable myVariableName, die in der Datei workflow_settings.yaml auf myVariableValue gesetzt ist:

...
vars:
  myVariableName: myVariableValue
...

Das folgende Codebeispiel zeigt die Datei workflow_settings.yaml mit der Kompilierungsvariable executionSetting, 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": {
     "VARIABLE":"VALUE"
   }
   

   Ersetzen Sie Folgendes:

   • VARIABLE: ein Name für die Variable
   • VALUE: der Standardwert der Kompilierungsvariable

Das folgende Codebeispiel zeigt die Kompilierungsvariable myVariableName, die in der Datei dataform.json auf myVariableValue gesetzt ist:

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

Das folgende Codebeispiel zeigt die Datei dataform.json, wobei die Kompilierungsvariable executionSetting auf dev gesetzt ist:

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

Zusammenfassungsvariable einer Tabelle hinzufügen

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

1. Rufen Sie Ihren Dataform-Entwicklungsarbeitsbereich auf.
2. Wählen Sie im Bereich Dateien eine SQLX-Datei mit der Tabellendefinition aus.

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

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

   Ersetzen Sie Folgendes:

   • VARIABLE: der Name Ihrer Variablen, z. B. executionSetting
   • SET_VALUE: ein Wert für die Variable, z. B. staging
   • CONDITION: eine Bedingung für die Ausführung der Tabelle

Das folgende Codebeispiel zeigt eine SQLX-Datei mit einer Tabellendefinition mit einer when-Klausel und der Variable 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-Datei mit einer Ansichtsdefinition mit einer when-Klausel und der Variable myVariableName:

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

Standardeinstellungen auf Workflowebene für Iceberg-Tabellen konfigurieren

Sie können Standardwerte auf Workflowebene für von Apache Iceberg verwaltete Tabellen in der Datei workflow_settings.yaml angeben. Sie können Standardwerte für den Bucket-Namen, den Stammordner der Tabelle und den Unterpfad des Tabellenordners festlegen.

Dataform verwendet diese Standardwerte, um den Speicher-URI für eine verwaltete Iceberg-Tabelle zu erstellen, wenn Sie diese Werte nicht im config-Block der Tabellendefinitionsdatei festlegen.

Wenn Sie Standardeinstellungen auf Workflow-Ebene für die Tabellen konfigurieren möchten, fügen Sie der Datei workflow_settings.yaml den Block defaultIcebergConfig mit den folgenden Feldern hinzu:

• bucketName: Optional. Der Standardname für den Cloud Storage-Bucket.
• tableFolderRoot: Optional. Der Standardname für den Ordner der ersten Ebene im Cloud Storage-Bucket.
• tableFolderSubpath: Optional. Der Standardname für einen Unterordner in tableFolderRoot.

Das folgende Codebeispiel zeigt eine workflow_settings.yaml-Datei mit Standardeinstellungen auf Workflowebene für verwaltete Iceberg-Tabellen:

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

Sie können in Ihrem Dataform-Code als Attribute des ProjectConfig-Objekts auf diese Felder zugreifen:

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

Weitere Informationen finden Sie unter Verwaltete Apache Iceberg-Tabellen erstellen und iceberg-Blockeigenschaften.

Workflow-Einstellungen zu workflow_settings.yaml migrieren

Damit Ihre Datei mit den Workflow-Einstellungen mit zukünftigen Dataform Core-Framework-Versionen kompatibel ist, 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 der Datei package.json durch die Datei workflow_settings.yaml finden Sie unter Dataform Core-Paket verwalten.

In der folgenden Tabelle ist die Zuordnung der Attribute für Workfloweinstellungen aus der Datei dataform.json zur Datei workflow_settings.yaml aufgeführt:

Property in dataform.json	Unterkunft 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	Optional. Der Standard-BigQuery-Standort, an dem Dataform Tabellen erstellt. Wenn nicht festgelegt, bestimmt Dataform den Speicherort anhand der Datasets, auf die sich Ihre SQL-Abfrage bezieht. Weitere Informationen finden Sie unter Standorte angeben.
defaultSchema	defaultDataset	Erforderlich. Das Standard-Dataset.
databaseSuffix	projectSuffix	Optional. Das Suffix, das an alle Google Cloud -Projektreferenzen 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 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. Nicht verfügbar in workflow_settings.yaml.
-	dataformCoreVersion	Nicht verfügbar in dataform.json. 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. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

   Zu Dataform

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

3. Klicken Sie im Bereich Dateien auf addHinzufü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 Datei workflow_settings.yaml die Einstellungen aus der Datei dataform.json hinzu, die dem YAML-Format zugeordnet sind.

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

8. Klicken Sie zum Bestätigen des Löschens von dataform.json auf Löschen.

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 oben genannte dataform.json-Datei, die in workflow_settings.yaml konvertiert wurde:

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

Dataform Core-Paket verwalten

In diesem Abschnitt erfahren Sie, wie Sie das Abhängigkeitspaket für das Dataform Core-Framework verwalten und auf die aktuelle Version aktualisieren.

Dataform-Core ist das Open-Source-Dataform-Framework für die Entwicklung von Workflows mit SQL, SQLX und JavaScript. Als Best Practice sollten Sie immer die aktuelle verfügbare Version des Dataform Core-Frameworks verwenden. Informationen zu Releases des Dataform-Kernframeworks finden Sie unter Dataform-Releases auf GitHub.

Speicherort des Dataform Core-Pakets verwalten

Wenn Sie den ersten Arbeitsbereich in einem Repository initialisieren, legt Dataform automatisch Dataform Core als Abhängigkeitspaket fest. Ab Dataform Core 3.0.0 wird das Dataform Core-Paket standardmäßig in der Datei workflow_settings.yaml installiert. In früheren Versionen von Dataform Core wurde Dataform Core in der Datei package.json festgelegt.

Wenn Dataform Core das einzige Paket in Ihrem Repository ist, sollten Sie es in Dataform Core 3.0.0 und höher in der Datei workflow_settings.yaml festlegen. Bei Repositories, die mit früheren Versionen von Dataform Core erstellt wurden, verschieben Sie das Dataform Core-Paket nach workflow_settings.yaml.

Die Datei package.json ist erforderlich, um zusätzliche Pakete in Dataform zu installieren. Wenn in Ihrem Repository zusätzliche Pakete verwendet werden, legen Sie das Dataform Core-Paket in package.json fest, damit alle Pakete an einem Ort festgelegt werden. Wenn Ihr Repository die Datei package.json nicht enthält, erstellen Sie die Datei package.json und verschieben Sie das Dataform-Kernpaket, um zusätzliche Pakete zu installieren. Die Datei package.json muss sich im Stammverzeichnis Ihres Repositorys befinden.

Dataform Core nach workflow_settings.yaml verschieben

Bei Repositorys, die mit Versionen von Dataform Core vor 3.0.0 erstellt wurden, sollten Sie das Dataform Core-Paket aus der Datei package.json in die Datei workflow_settings.yaml verschieben und die redundante Datei package.json löschen, wenn Sie keine anderen Abhängigkeitspakete als Dataform Core haben.

So migrieren Sie das Dataform-Kernpaket von der Datei package.json zur Datei workflow_settings.yaml:

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

   Zu Dataform

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

3. Wählen Sie im Bereich Dateien die Datei workflow_settings.yaml aus.

4. Fügen Sie in der Datei workflow_settings.yaml das Dataform Core-Paket im folgenden Format hinzu:

   dataformCoreVersion: "VERSION"
   
   

   Ersetzen Sie VERSION durch die aktuelle Version von Dataform, z. B. 3.0.0.

5. Klicken Sie im Bereich Dateien neben der Datei package.json auf das Menü Mehr und dann auf Löschen.

6. Klicken Sie auf Löschen, um das Löschen der Datei dataform.json zu bestätigen.

7. Klicken Sie auf Pakete installieren.

Dataform Core nach package.json verschieben

Die Datei package.json ist erforderlich, um zusätzliche Pakete in einem Repository zu installieren. Wenn Ihr Repository zusätzliche Pakete verwendet, sollten Sie alle Pakete, einschließlich des Dataform Core-Pakets, in der Datei package.json speichern.

Wenn Ihr Repository die Datei package.json nicht enthält, weil das Dataform Core-Paket in der Datei workflow_settings.yaml festgelegt ist, müssen Sie die Datei package.json erstellen, um zusätzliche Pakete zu installieren. Verschieben Sie dann das Dataform Core-Paket aus der Datei workflow_settings.yaml in die neu erstellte Datei package.json.

So erstellen Sie die Datei package.json und verschieben das Dataform-Kernpaket:

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

   Zu Dataform

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

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

4. Geben Sie im Feld Dateipfad hinzufügen package.json ein.

5. Klicken Sie auf Datei erstellen.

6. Fügen Sie in der Datei package.json das Dataform Core-Paket im folgenden Format hinzu:

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Ersetzen Sie VERSION durch die aktuelle Version von Dataform, z. B. 3.0.0.

7. Klicken Sie auf Pakete installieren.

8. Wählen Sie im Bereich Dateien die Option workflow_settings.yaml aus.

9. Löschen Sie in der Datei workflow_settings.yaml das Attribut dataformCoreVersion.

Dataform Core aktualisieren

Testen Sie neue Paketversionen immer in einer Nicht-Produktionsumgebung, bevor Sie sie in Ihrer Produktionsumgebung bereitstellen.

So aktualisieren Sie das Dataform Core-Abhängigkeitspaket:

1. Die aktuelle Version von @dataform/core finden Sie auf der Seite mit den Dataform-Releases auf GitHub.

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

   Zu Dataform

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

4. Wählen Sie im Bereich Dateien die Datei package.json oder workflow_settings.yaml aus.

   Der Speicherort des Dataform Core-Abhängigkeitspakets hängt von Ihrer Dataform Core-Version und der Verwendung von Paketen ab. Weitere Informationen finden Sie unter Speicherort des Dataform Core-Pakets verwalten.

5. Aktualisieren Sie das Dataform Core-Abhängigkeitspaket auf die neueste Version:

   package.json

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Ersetzen Sie VERSION durch die aktuelle Version von Dataform, z. B. 3.0.0. Um Probleme bei der Paketinstallation zu vermeiden, geben Sie die Dataform Core-Paketversion explizit an. Verwenden Sie keine anderen dependencies-Optionen der package.json-Datei, z. B. >version.

   workflow_settings.yaml

   dataformCoreVersion: "VERSION"
   

   Ersetzen Sie VERSION durch die aktuelle Version von Dataform, z. B. 3.0.0.

6. Klicken Sie auf Pakete installieren.

7. Führen Sie zum Übernehmen der Änderungen ein Commit durch.

8. Änderungen per Push in das Repository übertragen

Im folgenden Codebeispiel wird die @dataform/core-Abhängigkeit in der Datei package.json auf die Version 3.0.0 aktualisiert:

{
    "dependencies": {
        "@dataform/core": "3.0.0"
    }
}

Versionsverwaltung für Code

In diesem Abschnitt erfahren Sie, wie Sie mit der Versionsverwaltung in Dataform die Entwicklung verfolgen.

Dataform verwendet Git, um jede Änderung an den Dateien in einem Repository zu verfolgen.

In einem Dataform-Repository interagieren Sie direkt mit dem Git-Repository.

In einem verbundenen Repository interagieren Sie mit dem Tracking-Branch des Remote-Repositorys, das Sie beim Verbinden des Repositorys konfiguriert haben.

In Dataform werden Optionen für die Versionsverwaltung basierend auf dem Status der Änderungen in Ihrem Entwicklungsarbeitsbereich angezeigt. Dataform zeigt die Commit-Option beispielsweise nur an, wenn in Ihrem Arbeitsbereich nicht übernommene lokale Änderungen vorhanden sind. Wenn die Dateien in Ihrem Arbeitsbereich eine exakte Kopie Ihres Standard- oder Tracking-Zweigs sind, zeigt Dataform den Status Arbeitsbereich ist auf dem neuesten Stand an.

In Dataform werden die folgenden Optionen für die Versionsverwaltung angezeigt:

Commit für X-Änderung(en) durchführen

Übernehmen Sie die X Anzahl der lokalen Änderungen in Ihrem Arbeitsbereich oder in den ausgewählten geänderten Dateien. In Dataform werden die nicht per Commit übernommenen Änderungen angezeigt.

An Standardzweig übertragen

Übertragen Sie die per Commit übernommenen Änderungen per Push in Ihren Standardzweig. Diese Option ist in einem Dataform-Repository verfügbar, wenn Sie in Ihrem Arbeitsbereich keine Änderungen haben, die noch nicht committet wurden.

Zu your-branch-name übertragen

Übertragen Sie die Änderungen per Push in your-branch-name. Diese Option ist in einem Repository verfügbar, das mit einem Git-Repository eines Drittanbieters verbunden ist, wenn Sie keine nicht übergebenen Änderungen in Ihrem Arbeitsbereich haben.

Aus Standardzweig abrufen

Aktualisieren Sie Ihre Arbeitsbereiche mit den letzten Änderungen aus Ihrem Standardzweig. Diese Option ist in einem Dataform-Repository verfügbar, wenn Sie in Ihrem Arbeitsbereich keine nicht übertragenen oder nicht gepushten Änderungen haben.

Aus your-branch-name abrufen

Aktualisieren Sie Ihren Arbeitsbereich mit den letzten Änderungen aus your-branch-name. Diese Option ist in einem Repository verfügbar, das mit einem Git-Repository eines Drittanbieters verbunden ist, wenn Sie keine nicht übergebenen oder nicht übertragenen Änderungen in Ihrem Arbeitsbereich haben.

Letzten Commit wiederherstellen

Stellen Sie die Dateien in Ihrem Arbeitsbereich auf den Status Ihres letzten Commits zurück.

Änderungen abrufen

Wenn Ihr Entwicklungsarbeitsbereich nicht mit Ihrem Repository synchronisiert ist, zeigt Dataform die Option Pull an. So übertragen Sie Änderungen aus Ihrem Repository in Ihren Entwicklungsarbeitsbereich:

1. Wählen Sie auf der Seite Dataform ein Repository aus.
2. Wählen Sie auf dem Tab Entwicklungsarbeitsbereiche einen Entwicklungsarbeitsbereich aus.
3. Führen Sie auf der Seite des Entwicklungsarbeitsbereichs die folgenden Schritte aus:
   1. Wenn Sie sich in einem Dataform-Repository befinden, klicken Sie auf Aus Standardzweig abrufen.
   2. Wenn Sie sich in einem Repository befinden, das mit einem Git-Repository eines Drittanbieters verbunden ist, klicken Sie auf Aus your-branch-name abrufen.

Commit für Änderungen durchführen

Nachdem Sie eine Änderung in einem Entwicklungsarbeitsbereich vorgenommen haben, wird in Dataform die Option Commit angezeigt. Sie können alle lokalen Änderungen oder ausgewählte Dateien committen.

Hinweis: Dataform verwendet standardmäßig die E-Mail-Adresse des authentifiziertenGoogle Cloud -Nutzers für den Commit-Autor. Mit der Dataform API kann jedoch eine benutzerdefinierte E-Mail-Adresse für den Commit-Autor festgelegt werden. Dieses Verhalten ähnelt dem Befehl git commit --author und wirkt sich nur auf den Git-Commit-Verlauf aus. Die Identität des Commit-Autors wird nicht kryptografisch überprüft.

Im Dialogfeld Neuer Commit werden in Dataform die nicht per Commit übernommenen Änderungen angezeigt.

So übernehmen Sie Änderungen aus Ihrem Entwicklungsarbeitsbereich in Ihr Repository:

1. Wählen Sie auf der Seite Dataform ein Repository aus.
2. Wählen Sie auf der Repository-Seite einen Entwicklungsarbeitsbereich aus.
3. Klicken Sie auf der Seite des Entwicklungsarbeitsbereichs auf Commit.

4. Führen Sie im Bereich Neuer Commit die folgenden Schritte aus:

   1. Geben Sie im Feld Commit-Nachricht hinzufügen eine Beschreibung für Ihren Commit ein.

   2. Wählen Sie die geänderten Dateien aus, für die ein Commit durchgeführt werden soll.

      Wenn Sie keine Dateien auswählen, führt Dataform für alle lokalen Änderungen einen Commit durch. Sie können geänderte Dateien nach Dateistatus, Dateiname und Pfad filtern.

   3. Klicken Sie auf Alle Änderungen übernehmen oder X Änderungen übernehmen.

      Der Name der Schaltfläche hängt von der Auswahl der Dateien ab, die Sie übernehmen möchten.

Änderungen übertragen

In Dataform wird die Option Push angezeigt, nachdem Sie Änderungen per Commit übernommen haben. So übertragen Sie Änderungen aus Ihrem Entwicklerarbeitsbereich in Ihr Repository:

1. Wählen Sie auf der Seite Dataform ein Repository aus.
2. Wählen Sie auf der Repository-Seite einen Entwicklungsarbeitsbereich aus.
3. Commit für Änderungen durchführen
4. Führen Sie auf der Seite für den Entwicklungsarbeitsbereich die folgenden Schritte aus:
   1. Wenn Sie sich in einem Dataform-Repository befinden, klicken Sie auf An Standardzweig übertragen.
   2. Wenn Sie sich in einem Repository befinden, das mit einem Git-Repository eines Drittanbieters verbunden ist, klicken Sie auf In your-branch-name übertragen.

Änderungen ohne durchgeführten Commit zurücksetzen

So machen Sie Änderungen ohne Commit rückgängig:

1. Wählen Sie auf der Seite Dataform ein Repository aus.
2. Wählen Sie auf der Repository-Seite einen Entwicklungsarbeitsbereich aus.
3. Klicken Sie über dem Bereich Dateien auf das Menü Mehr und wählen Sie dann Auf letzten Commit zurücksetzen aus.

Konflikte beim Zusammenführen beheben

Ein Zusammenführungskonflikt kann auftreten, wenn eine lokale Änderung in Ihrem Entwicklungsarbeitsbereich nicht mit einer Änderung kompatibel ist, die am Standard-Tracking-Zweig Ihres Repositorys vorgenommen wurde. Merge-Konflikte treten normalerweise auf, wenn mehrere Nutzer gleichzeitig dieselbe Datei bearbeiten.

Ein Merge-Konflikt tritt in der Regel auf, wenn Sie Änderungen aus einem Branch abrufen, nachdem ein anderer Nutzer einen Änderungskonflikt in denselben Branch übertragen hat. Sie müssen einen Zusammenführungskonflikt manuell beheben, indem Sie die betroffene Datei bearbeiten.

Das folgende Codebeispiel zeigt einen Zusammenführungskonflikt in einer SQLX-Datei:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

So beheben Sie einen Zusammenführungskonflikt:

1. Wählen Sie in Ihrem Entwicklungsarbeitsbereich im Bereich Dateien eine betroffene Datei aus.
2. Bearbeiten Sie die Datei mit den gewünschten Änderungen.
3. Commit für Änderungen durchführen
4. Optional: Änderungen übertragen.

Repositories für BigQuery-Assets identifizieren

Dataform-Repositories, die automatisch von einem anderen BigQuery-Feature wie Notebooks oder gespeicherten Abfragen erstellt und verwaltet werden, werden in Dataform in der Google Cloud Console ausgeblendet, um die Übersichtlichkeit zu verbessern und versehentliche Änderungen an der Feature-spezifischen Logik zu verhindern. Diese Repositories werden möglicherweise in Cloud Asset Inventory-Suchvorgängen oder IAM-Berechtigungsprüfungen angezeigt, aber nicht in Dataform in der Google Cloud Console.

Sie können den Ursprung eines Dataform-Repositorys anhand seiner Ressourcenlabels ermitteln. In der folgenden Tabelle werden die Labels beschrieben, die von verschiedenen BigQuery-Funktionen verwendet werden:

Funktion	Labelschlüssel	Labelwert
BigQuery-Repositories	origin	bigquery-studio
BigQuery Studio-Git-Repositories	origin	bigquery-studio-git-folder
Data Canvases	single-file-asset-type	data_canvas
Datenvorbereitung	single-file-asset-type	data_preparation oder data_preparation_sqlx
Notebooks	single-file-asset-type	notebook
Pipelines	bigquery-workflow	(Beliebiger Wert)
Gespeicherte Abfragen	single-file-asset-type	sql

Wählen Sie eine der folgenden Optionen aus, um die Labels aus einem Repository abzurufen, das nicht in Dataform angezeigt wird:

Console

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

   Zu Asset Inventory

2. Klicken Sie auf den Tab Ressource.

3. Klicken Sie im Bereich Ergebnisse filtern neben Ressourcentyp auf Mehr ansehen und geben Sie dataform.googleapis.com/Repository ein.

4. Wählen Sie dataform.Repository aus und klicken Sie dann auf Anwenden.

5. Suchen Sie in der Ergebnistabelle nach Ihrem Repository und sehen Sie sich die Spalte Labels an. Vergleichen Sie die gefundenen Labels mit der Tabelle, in der die von verschiedenen BigQuery-Funktionen verwendeten Labels zur Identifizierung der Quellfunktion beschrieben werden.

API

Verwenden Sie die Methode projects.locations.repositories.get, um Labels abzurufen. Führen Sie die API-Anfrage mit den folgenden Informationen aus:

• Endpunkt: GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID

Alternativ können Sie im Terminal den folgenden curl-Befehl ausführen:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID"

Ersetzen Sie Folgendes:

• PROJECT_ID: Projekt-ID in Google Cloud .
• LOCATION: die Region, in der sich die Dataform-Ressourcen befinden.
• REPOSITORY_ID: Die eindeutige Kennung für das Dataform-Repository, das Sie abfragen.

Die in der Antwort zurückgegebene projects.locations.repositories-Ressource enthält eine Labelzuordnung mit den Metadaten, die zur Identifizierung des ursprünglichen Features verwendet werden.

gcloud

Führen Sie den folgenden Befehl in der Google Cloud CLI aus, um die Labels für ein bestimmtes Repository abzurufen:

gcloud asset search-all-resources \
    --asset-types=dataform.googleapis.com/Repository \
    --query="name:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID" \
    --format="yaml(labels)"

Ersetzen Sie Folgendes:

• PROJECT_ID: die eindeutige Kennung IhresGoogle Cloud -Projekts.
• LOCATION: die Google Cloud Region, in der sich Ihr Repository befindet.
• REPOSITORY_ID: die eindeutige Kennung für Ihr neues Dataform-Repository.

Um die Ressource zu finden, die dem Ausgabelabel entspricht, rufen Sie die entsprechende Featureseite in der Google Cloud Console auf, z. B. die Ordner Notebooks oder Daten-Canvas auf dem Tab Explorer im linken Bereich von BigQuery Studio.

Nächste Schritte

• Weitere Informationen zu den Projekteinstellungen für Dataform finden Sie in der Referenz zu IProjectConfig.
• Informationen zum Installieren zusätzlicher Pakete finden Sie unter Paket in Dataform installieren.
• Informationen zum Erstellen einer Tabelle finden Sie unter Tabelle erstellen.