EXECUTE DCM PROJECT¶

Führt eine der folgenden Aktionen für ein DCM-Projekt aus:

EXECUTE DCM PROJECT <name> PLAN führt einen Testlauf für das DCM project aus, um die Änderungen zu analysieren, die während einer Bereitstellung auf das Ziel angewendet werden, nimmt aber keine Änderungen vor.
EXECUTE DCM PROJECT <name> DEPLOY stellt die in den Definitionsdateien des Projekts definierten Änderungen für das Konto bereit.
EXECUTE DCM PROJECT <name> REFRESH ALL aktualisiert dynamische Tabellen, die vom DCM project verwaltet werden.
EXECUTE DCM PROJECT <name> TEST ALL testet alle Erwartungen an die angehängten Datenmetrikfunktionen, die vom DCM project verwaltet werden.
EXECUTE DCM PROJECT <name> PREVIEW gibt eine Datenprobe der aktuellen Definitionen zurück, die im Quellpfad für die angegebene Tabelle, Ansicht oder dynamische Tabelle angegeben sind.

Siehe auch:: CREATE DCM PROJECT, ALTER DCM PROJECT, DESCRIBE DCM PROJECT, DROP DCM PROJECT, SHOW DCM PROJECTS, SHOW DEPLOYMENTS IN DCM PROJECT

Syntax¶

EXECUTE DCM PROJECT <name>
  PLAN
  [ USING [ CONFIGURATION <config_name> ] [ (<expr>, [, <expr>, ...]) ] ]
  FROM '<source-files_path>'

EXECUTE DCM PROJECT <name>
  DEPLOY [ AS '<deployment_name_alias>' ]
  [ USING [ CONFIGURATION <name> ] [ (<expr>, [, <expr>, ...]) ] ]
  FROM '<source-files_path>'

EXECUTE DCM PROJECT <name>
  REFRESH ALL

EXECUTE DCM PROJECT <name>
  TEST ALL

EXECUTE DCM PROJECT <name>
  PREVIEW <fully_qualified_table_object_name>
  USING CONFIGURATION <config_name>
  FROM '<source_files_path>'

Erforderliche Parameter¶

name

Gibt den Bezeichner für das auszuführende DCM-Projekt an.

Wenn der Bezeichner Leerzeichen oder Sonderzeichen enthält, muss die gesamte Zeichenfolge in doppelte Anführungszeichen gesetzt werden. Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß- und Kleinschreibung zu beachten.

Weitere Informationen dazu finden Sie unter Anforderungen an Bezeichner.

PLAN

Weist Snowflake an, einen Leerlauf für das DCM project durchzuführen. Bei einem Testlauf analysiert Snowflake die Änderungen, die während einer Bereitstellung auf das Ziel angewendet werden, nimmt aber keine Änderungen vor.

DEPLOY [ AS 'deployment_name_alias' ]

Stellt die in den Definitionsdateien des Projekts definierten Änderungen für das Konto bereit; gibt optional einen Alias für die Bereitstellung an.

FROM 'source_files_path'

Gibt das Verzeichnis an, das die Quelldateien für das DCM project enthält. Das Verzeichnis muss eine Manifest-Datei und mindestens eine Definitionsdatei in /sources/definitions/ enthalten. Die Manifest-Datei enthält die Vorlagenwerte, falls eine Konfiguration angegeben wurde.

REFRESH ALL

Aktualisiert alle dynamischen Tabellen, die derzeit vom DCM project verwaltet werden.

TEST ALL

Testet alle Datenqualitätserwartungen, die mit Tabellen, dynamischen Tabellen oder Ansichten verbunden sind, die derzeit vom DCM project verwaltet werden.

PREVIEW fully_qualified_table_object_name

Gibt eine Datenprobe der aktuellen Definitionen zurück, die im Quellpfad für die angegebene Tabelle, Ansicht oder dynamische Tabelle angegeben sind – unabhängig vom bereitgestellten Status.

Optionale Parameter¶

USING CONFIGURATION config_name

Gibt die zu verwendende Konfiguration an. So können Sie Bereitstellungen für verschiedene Umgebungen anpassen, z. B. für Entwicklung, Staging oder Produktion, ohne verschiedene Projektdefinitionsdateien zu verwenden.

Wenn der Konfigurationsname nicht komplett in Großbuchstaben geschrieben ist, schließen Sie ihn in doppelte Anführungszeichen ein.

USING ( expr [, expr , ... ] )

Gibt optional Werte für Vorlagenvariablen an. Wenn Sie diese Option verwenden, werden alle Standard- oder Konfigurationswerte für diese spezielle Variable überschrieben. Der einzelne Ausdruck muss die folgende Form haben: <variable_name> => <variable_value>. Für Listen verwenden Sie die folgende Form: <variable_name> => [<value1>, <value2>, ...]. Beispiel: wh_size => 'MEDIUM' oder teams => ['TEAM_A', 'TEAM_B'].

So können Sie Bereitstellungen für verschiedene Umgebungen anpassen, z. B. für Entwicklung, Staging oder Produktion, ohne verschiedene Projektdefinitionsdateien zu verwenden.

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:


Berechtigung	Objekt	Anmerkungen
OWNERSHIP	DCM-Projekt	OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Für das Ausführen von Operationen für ein Objekt in einem Schema ist mindestens eine Berechtigung für die übergeordnete Datenbank und mindestens eine Berechtigung für das übergeordnete Schema erforderlich.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Ausgabe¶

Nachdem der Befehl DCM project ausgeführt wurde, gibt dieser Befehl je nach Variante die folgende Ausgabe zurück:

PLAN und DEPLOY: Eine einzelne Zeile, die ein JSON-Objekt mit dem Änderungsprotokoll enthält.
PREVIEW: Ein Resultset.
REFRESH ALL: Eine einzelne Zeile, die ein JSON-Objekt mit der vollständigen Antwort enthält
TEST ALL: Eine einzelne Zeile, die ein JSON-Objekt mit der vollständigen Antwort enthält

PLAN- und DEPLOY-Ausgabe¶

Bemerkung

Während der Vorschauphase kann sich das genaue Ausgabeformat ändern.

Die Standardausgabe des Plans enthält die folgenden Informationen zur Ausführung des Plans im JSON-Format:

{
  "version": 2,
  "metadata": {
    "timestamp": <timestamp>,
    "query_id": <query_id>,
    "project_name": <project_name>,
    "user": <user>,
    "role_name": <role_name>,
    "command": <command>
  },
  "changeset": [
    {
      "type": <type>,
      "object_id": {
        "domain": <domain>,
        "name": <name>,
        "fqn": <fqn>,
        "database": <database>,
        "schema": <schema>
      },
      "changes": [
        {
          "kind": <kind>,
          "attribute_name": <attribute_name>,
          "value": <value>,
          "changes": [
            {
              "kind": <kind>,
              "attribute_name": <attribute_name>,
              "value": <value>
            }
          ]
        }
      ]
    }
  ]
}


Eigenschaft	Beschreibung
`version`	Schemaversion des Ausgabeformats. Version 2 ist die neueste und einzige unterstützte Version.
`metadata`	Kontextinformationen zur Ausführung.
`metadata.timestamp`	ISO 8601-Zeitstempel, wann der Befehl ausgeführt wurde.
`metadata.query_id`	Eindeutiger Bezeichner der Abfrage, die diesen Plan erzeugt hat.
`metadata.project_name`	Vollqualifizierter Name des DCM-Projektobjekts.
`metadata.user`	Name des Benutzers, der den Befehl ausgeführt hat.
`metadata.role_name`	Aktive Rolle, die zur Ausführung des Befehls verwendet wird.
`metadata.command`	Der ausgeführte Befehl: `PLAN` oder `DEPLOY`.
`changeset`	Ein Array von Änderungseinträgen. Jeder Eintrag steht für ein Objekt, das erstellt, geändert oder gelöscht werden würde oder wurde. Ein leeres Array bedeutet, dass die Projektdefinitionen bereits mit dem Konto synchronisiert sind.
`changeset[].type`	Die geplante Aktion für das Objekt. Mögliche Werte: `CREATE`, `ALTER`, `DROP`.
`changeset[].object_id`	Identifiziert das Zielobjekt.
`changeset[].object_id.domain`	Der Snowflake-Objekttyp.
`changeset[].object_id.name`	Name des Objekts.
`changeset[].object_id.fqn`	Vollqualifizierter Name des Objekts.
`changeset[].object_id.database`	Datenbank, die das Objekt enthält. Wird bei Objekten auf Kontoebene weggelassen.
`changeset[].object_id.schema`	Schema, welches das Objekt enthält. Wird bei Objekten auf Datenbank- und Kontoebene weggelassen.
`changeset[].changes`	Ein Array von Änderungsdeskriptoren, die die spezifischen Attributänderungen genau angeben.
`changeset[].changes[].kind`	Der Typ der Änderung. Mögliche Werte: `set`, `changed`, `unset`, `nested`, `collection`. Der Wert von `kind` bestimmt die verbleibenden Schlüssel des Objekts.
`changeset[].changes[].attribute_name`	Name des Attributs, das festgelegt oder geändert wird. Vorhanden, wenn `kind` gleich `set`, `changed` oder `unset`.
`changeset[].changes[].value`	Der neue Wert für das Attribut. Vorhanden, wenn `kind` gleich `set` oder `changed`.
`changeset[].changes[].prev_value`	Der vorherige Wert des Attributs vor der Änderung. Nur vorhanden, wenn `kind` `changed` ist.
`changeset[].changes[].collection_name`	Name der Sammlung, die geändert wird (zum Beispiel `columns`, `constraints`, `privileges`, `expectations`). Nur vorhanden, wenn `kind` `collection` ist.
`changeset[].changes[].id_label`	Label, das zur Identifizierung von Elementen innerhalb der Sammlung verwendet wird (z. B.``name``). Nur für bestimmte Sammlungen vorhanden.
`changeset[].changes[].changes`	Ein verschachteltes Array von Deskriptoren für Sammlungselemente. Nur vorhanden, wenn `kind` `collection` ist.
`changeset[].changes[].changes[].kind`	Der Typ der Änderung des Sammlungselements. Mögliche Werte: `added`, `removed`, `modified`.
`changeset[].changes[].changes[].item_id`	Identifiziert das Element innerhalb der Sammlung. Kann je nach Sammlungstyp eine Zeichenfolge oder ein Objekt sein.
`changeset[].changes[].changes[].changes`	Ein Array weiterer Änderungsdeskriptoren für dieses Element. Vorhanden für `added`- und `modified`-Elemente. Nie vorhanden bei `removed`-Elementen.

Ein Beispiel für eine Planausgabe:

{
  "version": 2,
  "metadata": {
    "timestamp": <timestamp>,
    "query_id": <query_id>,
    "project_name": <project_name>,
    "user": <user>,
    "role_name": <role_name>,
    "command": <command>
  },
  "changeset": [
    {
      "type": "CREATE",
      "object_id": {
        "domain": "TABLE",
        "name": "CUSTOMER_SUMMARY",
        "fqn": "MY_DB.ANALYTICS.CUSTOMER_SUMMARY",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": [
        {
          "kind": "set",
          "attribute_name": "warehouse_size",
          "value": "XSMALL"
        },
        {
          "kind": "set",
          "attribute_name": "query",
          "value": "SELECT customer_id, SUM(amount) AS total FROM orders GROUP BY customer_id"
        }
      ]
    },
    {
      "type": "ALTER",
      "object_id": {
        "domain": "DYNAMIC_TABLE",
        "name": "ORDER_DETAILS",
        "fqn": "MY_DB.ANALYTICS.ORDER_DETAILS",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": [
        {
          "kind": "changed",
          "attribute_name": "warehouse_size",
          "value": "SMALL",
          "prev_value": "XSMALL"
        },
        {
          "kind": "collection",
          "collection_name": "columns",
          "id_label": "name",
          "changes": [
            {
              "kind": "added",
              "item_id": "DISCOUNT_AMOUNT",
              "changes": [
                {
                  "kind": "set",
                  "attribute_name": "data_type",
                  "value": "NUMBER(10,2)"
                }
              ]
            },
            {
              "kind": "modified",
              "item_id": "ORDER_STATUS",
              "changes": [
                {
                  "kind": "changed",
                  "attribute_name": "data_type",
                  "value": "VARCHAR(50)",
                  "prev_value": "VARCHAR(20)"
                }
              ]
            },
            {
              "kind": "removed",
              "item_id": "LEGACY_FLAG"
            }
          ]
        }
      ]
    },
    {
      "type": "DROP",
      "object_id": {
        "domain": "VIEW",
        "name": "OLD_REPORT_VIEW",
        "fqn": "MY_DB.ANALYTICS.OLD_REPORT_VIEW",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": []
    }
  ]
}

REFRESH ALL-Ausgabe¶

Die JSON-Ausgabe enthält die Ergebnisse der Aktualisierungsoperation der dynamischen Tabelle im folgenden Format:

{
  "dts_refresh_result": {
    "refreshed_tables": [
      {
        "table_name": <table_name>,
        "statistics": {
          "inserted_rows": <inserted_rows>,
          "deleted_rows": <deleted_rows>
        },
        "data_timestamp": <data_timestamp>
      }
    ]
  }
}


Eigenschaft	Beschreibung
`dts_refresh_result`	Enthält die Ergebnisse der Aktualisierungsoperation der dynamischen Tabelle.
`refreshed_tables[]`	Ein Array von Einträgen, einer für jede dynamische Tabelle, die aktualisiert wurde.
`table_name`	Vollqualifizierter Name der dynamischen Tabelle, die aktualisiert wurde.
`statistics`	Aktualisierungsstatistiken für die Tabelle.
`inserted_rows`	Anzahl der Zeilen, die bei der Aktualisierung eingefügt wurden.
`deleted_rows`	Anzahl der Zeilen, die bei der Aktualisierung gelöscht wurden.
`data_timestamp`	ISO 8601-Zeitstempel, der die Aktualität der Daten nach der Aktualisierung angibt.

Ein Beispiel für die JSON-Ausgabe für die Aktualisierung einer dynamischen Tabelle:

{
  "dts_refresh_result": {
    "refreshed_tables": [
      {
        "table_name": "db.schema.my_dynamic_table",
        "statistics": {
          "inserted_rows": 150,
          "deleted_rows": 30
        },
        "data_timestamp": "2026-03-16T12:00:00.000Z"
      }
    ]
  }
}

TEST ALL-Ausgabe¶

Die TEST-Ausgabe enthält den Gesamtstatus und die Erwartungen mit ihren Werten im folgenden Format:

Bemerkung

Während der Vorschauphase kann sich das genaue Ausgabeformat ändern.

{
  "status": <status>,
  "expectations": [
    {
      "table_name": <table_name>,
      "metric_database": <metric_database>,
      "metric_schema": <metric_schema>,
      "metric_name": <metric_name>,
      "expectation_name": <expectation_name>,
      "expectation_expression": <expectation_expression>,
      "value": <value>,
      "expectation_violated": <expectation_violated>,
      "column_names": <column_names>
    }
  ]
}


Eigenschaft	Beschreibung
`status`	Gesamtergebnis des Testlaufs. Mögliche Werte: `SUCCESSFUL` (alle Erwartungen erfüllt), `FAILED` (eine oder mehrere Erwartungen nicht erfüllt).
`expectations[]`	Ein Array von Erwartungsergebnissen, eines für jede ausgewertete Datenqualitätserwartung.
`table_name`	Vollqualifizierter Name der Tabelle oder Ansicht, für die die Erwartung ausgewertet wurde.
`metric_database`	Datenbank, die die Datenmetrikfunktion enthält.
`metric_schema`	Schema, das die Datenmetrikfunktion enthält.
`metric_name`	Name der Datenmetrikfunktion (zum Beispiel `NULL_COUNT`, `MIN`, `UNIQUE_COUNT`).
`expectation_name`	Name der Erwartung, wie im Projekt definiert.
`expectation_expression`	Boolescher Ausdruck, mit dem der Kennzahlwert ausgewertet wird (zum Beispiel `value = 0`, `value >= 0`).
`value`	Das Ergebnis der Evaluierung der Datenmetrikfunktion. Nur vorhanden, wenn `expectation_violated` `false` ist.
`expectation_violated`	Ob die Erwartung erfüllt wurde. `true`, wenn der Wert der Kennzahl den Erwartungsausdruck nicht erfüllt hat; andernfalls `false`.
`column_names`	Ein Array mit den Namen der Spalten, für die die Datenmetrikfunktion ausgewertet wurde.

Ein Beispiel für die JSON-Ausgabe für einen Datenqualitätstest:

{
  "status": "FAILED",
  "expectations": [
    {
      "table_name": "db.schema.my_table",
      "metric_database": "SNOWFLAKE",
      "metric_schema": "CORE",
      "metric_name": "NULL_COUNT",
      "expectation_name": "no_nulls_in_id",
      "expectation_expression": "value = 0",
      "value": 0,
      "expectation_violated": false,
      "column_names": ["ID"]
    },
    {
      "table_name": "db.schema.my_table",
      "metric_database": "SNOWFLAKE",
      "metric_schema": "CORE",
      "metric_name": "UNIQUE_COUNT",
      "expectation_name": "unique_id_check",
      "expectation_expression": "value >= 100",
      "value": null,
      "expectation_violated": true,
      "column_names": ["ID"]
    }
  ]
}

Nutzungshinweise¶

Beim Ausführen eines DCM project mit EXECUTE DCM PROJECT PLAN ist die Ausgabe des Befehls dieselbe wie für die eigentliche Bereitstellung. Der Unterschied besteht darin, dass keine Änderungen an dem betroffenen Konto vorgenommen werden. Mit diesem Feature können Sie überprüfen, ob die gerenderten Definitionsdateien eine gültige Syntax haben, welche Änderungen auf das Konto angewendet werden und ob die Eigentümerrolle des Projekts über die erforderlichen Berechtigungen zur Anwendung dieser Änderungen verfügt.

Um unbeabsichtigte Änderungen zu vermeiden und Fehler zu erkennen, führen Sie EXECUTE DCM PROJECT PLAN immer vor der Bereitstellung eines DCM project aus.

Unterstützung für Vorlagenvariablen¶

Mit Vorlagenvariablen können Sie den Inhalt der parametrisierten Definitionsdateien während der DCM project-Ausführung dynamisch auswählen. Sie können Vorlagenvariablen auf folgende Weise verwenden:

Im Abschnitt mit den Beispielen für Vorlagenvariablen finden Sie entsprechende Beispiele.

Beispiele¶

Grundlegende Beispiele¶

Führen Sie ein DCM project imPLAN-Modus aus, um Änderungen an einem Projekt zu validieren, ohne sie anzuwenden:

EXECUTE DCM PROJECT my_project
  PLAN
  FROM '@my_database.my_schema.my_stage/my_project';

Führen Sie ein DCM-Projekt imDEPLOY-Modus (zum Anwenden von Änderungen) aus, um einen Bereitstellungsalias und eine Konfiguration namens PROD anzugeben:

EXECUTE DCM PROJECT my_project
  DEPLOY AS "my_update"
  USING CONFIGURATION PROD
  FROM '@my_database.my_schema.my_stage/my_project';

Beispiele für Vorlagenvariablen¶

Die folgenden Beispiele zeigen, wie Sie den Wert für Vorlagenvariablen in einer EXECUTE DCM PROJECT-Anweisung angeben können.

Überschreiben der in der Manifest-Datei des DCM-Projekts definierten Vorlagenvariablen

Definieren einer Vorlagenvariable namens desc in der Manifest-Datei:

manifest_version: 2
type: DCM_PROJECT
default_target: DCM_DEV
targets:
  DCM_DEV:
    desc: "created by hello world project"

Erstellen Sie eine Definitionsdatei, die die Vorlagenvariable verwendet:
```
DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc}}';
```
Rufen Sie den Befehl EXECUTE DCM PROJECT im DEPLOY-Modus auf und geben Sie einen Wert für die desc-Variable an, um ihren Standardwert im Manifest zu überschreiben:
```
EXECUTE DCM PROJECT MY_PROJECT DEPLOY
  USING CONFIGURATION FIRST_CONFIG (desc => 'This object is mine')
  FROM '/my/project/source';
```

Angeben eines Werts für eine Vorlagenvariable, die nicht in der Manifest-Datei definiert ist

Erstellen einer Definitionsdatei mit den gewünschten Befehlen:
```
DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc_new}}';
```
Rufen Sie den Befehl EXECUTE DCM PROJECT auf und geben Sie einen Wert für die desc_new-Variable an:
```
EXECUTE DCM PROJECT MY_PROJECT (desc_new => 'This object is mine');
```