EXECUTE DCM PROJECT¶

:doc:`DCMプロジェクト</user-guide/dcm-projects/dcm-projects-overview>`に対して、次のアクションのいずれかを実行します。

:code:`EXECUTE DCM PROJECT <name> PLAN`は、|dcm-object|のドライランを実行してデプロイ中にターゲットに適用される変更を分析しますが、変更は適用しません。
:code:`EXECUTE DCM PROJECT <name> DEPLOY`は、プロジェクトの定義ファイルで定義された変更をアカウントにデプロイします。
:code:`EXECUTE DCM PROJECT <name> REFRESH ALL`は、|dcm-object|が管理する動的テーブルをリフレッシュします。
:code:`EXECUTE DCM PROJECT <name> TEST ALL`は、|dcm-object|によって管理される、アタッチされたデータメトリック関数からのすべての期待値をテストします。
:code:`EXECUTE DCM PROJECT <name> PREVIEW`は、指定されたテーブル、ビュー、または動的テーブルのソースパスで設定されている現在の定義のデータサンプルを返します。

こちらもご参照ください。: CREATE DCM PROJECT、 ALTER DCM PROJECT、 DESCRIBE DCM PROJECT、 DROP DCM PROJECT、 SHOW DCM PROJECTS、 SHOW DEPLOYMENTS IN DCM PROJECT

構文¶

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>'

必須パラメーター¶

name

実行するDCMプロジェクトの識別子を指定します。

識別子にスペースまたは特殊文字が含まれる場合は、文字列全体を二重引用符で囲む必要があります。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、識別子の要件をご参照ください。

PLAN

Snowflakeに、|dcm-object|のドライランを実行するよう指示します。ドライランの場合、Snowflakeはデプロイ中にターゲットに適用される変更を分析しますが、変更は適用しません。

DEPLOY [ AS 'deployment_name_alias' ]

プロジェクトの定義ファイルで定義された変更をアカウントにデプロイします。オプションでデプロイのエイリアスを指定することもできます。

FROM 'source_files_path'

|dcm-object|のソースファイルを含むディレクトリを指定します。ディレクトリには、マニフェストファイルと:file:`/sources/definitions/`内の少なくとも1つの定義ファイルが含まれている必要があります。マニフェストファイルは、構成が指定されている場合に、テンプレート化の値を提供します。

REFRESH ALL

|dcm-object|によって現在管理されているすべての動的テーブルをリフレッシュします。

TEST ALL

|dcm-object|によって現在管理されているテーブル、動的テーブル、またはビューにアタッチされた、すべてのデータ品質期待値をテストします。

PREVIEW fully_qualified_table_object_name

デプロイ済みの状態とは無関係に、指定されたテーブル、ビュー、または動的テーブルのソースパスに記述されている現在の定義のデータサンプルを返します。

オプションのパラメーター¶

USING CONFIGURATION config_name

使用する構成を指定します。これにより、異なるプロジェクト定義ファイルを使用することなく、開発、ステージング、本番などの異なる環境のデプロイをカスタマイズできます。

構成名がすべて大文字でない場合は、二重引用符で囲みます。

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

オプションでテンプレート変数の値を指定します。このオプションを使用すると、この特定の変数のデフォルト値または構成値が上書きされます。単一式は次の形式である必要があります。<variable_name> => <variable_value>。リストの場合は、次の形式を使用します。<variable_name> => [<value1>, <value2>, ...]。例: wh_size => 'MEDIUM'、または:codenowrap:teams => ['TEAM_A', 'TEAM_B']。

これにより、異なるプロジェクト定義ファイルを使用することなく、開発、ステージング、本番などの異なる環境のデプロイをカスタマイズできます。

アクセス制御の要件¶

この操作の実行に使用されるロールには、少なくとも次の権限が必要です。


権限	オブジェクト	メモ
OWNERSHIP	DCMプロジェクト	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).

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、カスタムロールの作成をご参照ください。

セキュリティ保護可能なオブジェクトに対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、アクセス制御の概要をご参照ください。

出力¶

|dcm-object|の実行後、このコマンドはバリエーションに応じて次の出力を返します。

PLANとDEPLOY：変更ログを持つJSONオブジェクトを含む単一行。
PREVIEW：結果セット。
REFRESH ALL:完全な応答を持つJSONオブジェクトを含む単一行。
TEST ALL:完全な応答を持つJSONオブジェクトを含む単一行。

PLANおよびDEPLOY出力¶

注釈

プレビュー段階では、正確な出力形式が変更される可能性があります。

標準計画の出力には、計画の実行に関する次の情報がJSON形式で含まれます。

{
  "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>
            }
          ]
        }
      ]
    }
  ]
}


プロパティ	説明
`version`	出力形式のスキーマバージョン。バージョン2は最新で、唯一サポートされているバージョンです。
`metadata`	実行に関するコンテキスト情報。
`metadata.timestamp`	コマンドが実行されたときのISO 8601タイムスタンプ。
`metadata.query_id`	このプランを生成したクエリの一意の識別子。
`metadata.project_name`	DCMプロジェクトオブジェクトの完全修飾名。
`metadata.user`	コマンドを実行したユーザーの名前。
`metadata.role_name`	コマンドの実行に使用されたアクティブなロール。
`metadata.command`	実行されたコマンド。PLAN``または``DEPLOY。
`changeset`	変更エントリの配列。各エントリは、作成、変更、またはドロップされる（あるいはされた）1つのオブジェクトを表します。空の配列は、プロジェクト定義がすでにアカウントと同期していることを示します。
`changeset[].type`	オブジェクトに対して計画されたアクション。可能な値: `CREATE`、 `ALTER`、 `DROP`。
`changeset[].object_id`	ターゲットオブジェクトを識別します。
`changeset[].object_id.domain`	Snowflakeのオブジェクトタイプ。
`changeset[].object_id.name`	オブジェクトの名前です。
`changeset[].object_id.fqn`	オブジェクトの完全修飾名。
`changeset[].object_id.database`	オブジェクトを含むデータベース。アカウントレベルのオブジェクトでは省略されます。
`changeset[].object_id.schema`	オブジェクトを含むスキーマ。データベースレベルおよびアカウントレベルのオブジェクトでは省略されます。
`changeset[].changes`	特定の属性の変更を詳細に示す変更記述子の配列。
`changeset[].changes[].kind`	変更のタイプ。可能な値: `set`、 `changed`、 `unset`、 `nested`、 `collection`。``kind``の値により、オブジェクトの残りのキーが決定されます。
`changeset[].changes[].attribute_name`	設定または変更される属性の名前。kind``が``set、`changed`、または``unset``の場合に存在します。
`changeset[].changes[].value`	属性の新しい値。``kind``が``set``または``changed``の場合に存在します。
`changeset[].changes[].prev_value`	変更前における属性の以前の値。``kind``が``changed``の場合にのみ存在します。
`changeset[].changes[].collection_name`	変更されるコレクションの名前（`columns`、`constraints`、`privileges`、``expectations``など）。``kind``が``collection``の場合にのみ存在します。
`changeset[].changes[].id_label`	コレクション内のアイテムを識別するために使用されるラベル（``name``など）。特定のコレクションにのみ存在します。
`changeset[].changes[].changes`	コレクションアイテム記述子のネストされた配列。``kind``が``collection``の場合にのみ存在します。
`changeset[].changes[].changes[].kind`	コレクションアイテムへの変更タイプ。可能な値: `added`、 `removed`、 `modified`。
`changeset[].changes[].changes[].item_id`	コレクション内のアイテムを識別します。コレクションタイプに応じて、文字列またはオブジェクトになります。
`changeset[].changes[].changes[].changes`	このアイテムに関する追加の変更記述子の配列。``added``および``modified``アイテムに存在します。``removed``アイテムには常に存在しません。

プラン出力の例を次に示します。

{
  "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出力¶

JSON出力には、次の形式で動的テーブルのリフレッシュ操作の結果が格納されます。

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


プロパティ	説明
`dts_refresh_result`	動的テーブルリフレッシュ操作の結果が含まれます。
`refreshed_tables[]`	リフレッシュされた動的テーブルごとのエントリの配列。
`table_name`	リフレッシュされた動的テーブルの完全修飾名。
`statistics`	テーブルのリフレッシュ統計。
`inserted_rows`	リフレッシュ中に挿入された行数。
`deleted_rows`	リフレッシュ中に削除された行数。
`data_timestamp`	リフレッシュ後のデータの鮮度を表すISO 8601タイムスタンプ。

動的テーブルリフレッシュのJSON出力の例：

{
  "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出力¶

TESTの出力には、全体的なステータスと期待値が次の形式で含まれます。

注釈

プレビュー段階では、正確な出力形式が変更される可能性があります。

{
  "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>
    }
  ]
}


プロパティ	説明
`status`	テスト実行の全体的な結果。指定可能な値：``SUCCESSFUL``（すべての期待値が満たされた）、``FAILED``（1つ以上の期待値に違反があった）。
`expectations[]`	評価されたデータ品質期待値ごとの、期待値テスト結果の配列。
`table_name`	期待値が評価されたテーブルまたはビューの完全修飾名。
`metric_database`	データメトリック関数を含むデータベース。
`metric_schema`	データメトリック関数を含むスキーマ。
`metric_name`	データメトリック関数の名前（例：`NULL_COUNT`、`MIN`、`UNIQUE_COUNT`）。
`expectation_name`	プロジェクトで定義されている期待値の名前。
`expectation_expression`	メトリック値の評価基準となるブール式（例：`value = 0`、`value >= 0`）。
`value`	データメトリック関数の評価結果。``expectation_violated``が``false``の場合にのみ存在します。
`expectation_violated`	期待値に対する違反があったかどうか。メトリックの値が期待値の式を満たさなかった場合は``true``、それ以外の場合は``false``になります。
`column_names`	データメトリック関数が評価された列名の配列。

データ品質テストのJSON出力の例

{
  "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"]
    }
  ]
}

使用上の注意¶

EXECUTE DCM PROJECT PLANを使用して|dcm-object|を実行する場合、コマンドの出力は実際のデプロイと同じになります。違いは、影響を受けるアカウントへの変更が適用されないことです。この機能により、レンダリングされた定義ファイルに有効な構文があるかどうか、アカウントにどのような変更が適用されるか、プロジェクトの所有者ロールにこれらの変更を適用するために必要な権限があるかどうかを確認できます。

意図しない変更を回避し、エラーを検出するために、|dcm-object|をデプロイする前に必ずEXECUTE DCM PROJECT PLANを実行してください。

テンプレート変数のサポート¶

テンプレート変数を使用すると、|dcm-object|の実行中にパラメーター化された定義ファイルの内容を動的に選択できます。テンプレート変数は、次の方法で使用できます。

例については、:ref:`テンプレート変数の例<label-dcm_projects_template_variable_execute_examples>`セクションを参照してください。

例¶

基本的な例¶

|dcm-object|をPLANモードで実行して、プロジェクトへの変更を適用せずに検証します。

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

DCMプロジェクトをDEPLOYモードで実行（変更を適用）して、デプロイエイリアスと、PRODという名前の構成を指定します。

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

テンプレート変数の例¶

以下の例では、EXECUTE DCM PROJECTステートメントでテンプレート変数の値を指定する方法を説明します。

DCMプロジェクトのマニフェストファイルで定義されているテンプレート変数を上書きする

マニフェストファイル内で``desc``という名前のテンプレート変数を定義します。
```
manifest_version: 2
type: DCM_PROJECT
default_target: DCM_DEV
targets:
  DCM_DEV:
    desc: "created by hello world project"
```
テンプレート変数を使用する定義ファイルを作成します。
```
DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc}}';
```
EXECUTE DCM PROJECTコマンドをDEPLOYモードで呼び出し、``desc``変数の値を指定して、マニフェスト内のデフォルト値を上書きします。
```
EXECUTE DCM PROJECT MY_PROJECT DEPLOY
  USING CONFIGURATION FIRST_CONFIG (desc => 'This object is mine')
  FROM '/my/project/source';
```

マニフェストファイルで定義されていないテンプレート変数の値を指定する

必要なコマンドを使用して定義ファイルを作成します。
```
DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc_new}}';
```
EXECUTE DCM PROJECTコマンドを呼び出し、``desc_new``変数の値を指定します。
```
EXECUTE DCM PROJECT MY_PROJECT (desc_new => 'This object is mine');
```