EXECUTE DCM PROJECT

对 DCM 项目 执行以下操作之一：

  • EXECUTE DCM PROJECT <name> PLAN 对 DCM project 进行试运行，以分析在部署期间将应用到目标上的变更，但不会实际应用任何变更。

  • EXECUTE DCM PROJECT <name> DEPLOY 将项目定义文件中定义的变更部署到账户中。

  • EXECUTE DCM PROJECT <name> REFRESH ALL 刷新由 DCM project 管理的动态表。

  • EXECUTE DCM PROJECT <name> TEST ALL 测试由 DCM project 管理的、来自关联数据度量函数的所有预期。

  • 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 project 进行试运行。在试运行中，Snowflake 会分析在部署期间将应用到目标上的变更，但不会实际应用任何变更。

DEPLOY [ AS 'deployment_name_alias' ]

将项目定义文件中定义的变更部署到账户中；可选择为部署指定别名。

FROM 'source_files_path'

指定包含 DCM project 源文件的目录。该目录必须包含一个清单文件以及 /sources/definitions/ 中的至少一个定义文件。如果指定了配置，清单文件将提供模板值。

REFRESH ALL

刷新当前由 DCM project 管理的所有动态表。

TEST ALL

测试附加到当前由 DCM project 管理的表、动态表或视图上的所有数据质量预期。

PREVIEW fully_qualified_table_object_name

返回为指定表、视图或动态表在源路径中定义的当前定义的数据样本 – 与任何已部署状态无关。

可选参数

USING CONFIGURATION config_name

指定要使用的配置。 这使您能够为不同环境（如开发、预发布或生产环境）自定义部署，而无需使用不同的项目定义文件。

如果配置名称不是全大写，请将其用双引号引起来。

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

可选择指定模板变量的值。使用此选项将覆盖该特定变量的任何默认值或配置值。单个表达式必须使用以下形式：<variable_name> => <variable_value>。对于列表，请使用以下形式：<variable_name> => [<value1>, <value2>, ...]。例如：wh_size => 'MEDIUM' 或 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).

对架构中的对象进行操作至少需要父数据库的一项权限和父架构的一项权限。

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

输出

DCM project 执行后，此命令根据不同的变体返回以下输出：

  • 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

变更条目数组。每个条目代表一个将要创建、更改或删除的对象。空数组表示项目定义已与账户同步。

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``（违反了一个或多个期望）。

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 project 时，该命令的输出与实际部署的输出相同。区别在于不会对受影响的账户应用任何更改。此功能使您能够验证渲染后的定义文件是否具有有效的语法、将对账户应用哪些更改，以及项目所有者角色是否具有应用这些更改所需的权限。

为避免意外更改并捕获错误，在部署 DCM project 之前，请始终先运行 EXECUTE DCM PROJECT PLAN。

对模板变量的支持

模板变量允许您在 DCM project 执行期间动态选择参数化定义文件的内容。您可以通过以下方式使用模板变量：

有关示例，请参阅 模板变量示例 部分。

示例

基本示例

以 PLAN 模式执行 DCM project，以验证对项目的更改而不应用这些更改：

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

以 DEPLOY 模式执行 DCM（以应用更改），并指定部署别名和名为 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 项目清单文件中定义的模板变量

  1. 在清单文件中定义一个名为 desc 的模板变量：

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

  2. 创建使用模板变量的定义文件：

    DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc}}';

  3. 以 DEPLOY 模式调用 EXECUTE DCM PROJECT，并为 desc 变量指定一个值，覆盖其在清单文件中的默认值：

    EXECUTE DCM PROJECT MY_PROJECT DEPLOY
  USING CONFIGURATION FIRST_CONFIG (desc => 'This object is mine')
  FROM '/my/project/source';

为清单文件中未定义的模板变量提供值

  1. 创建一个包含所需命令的定义文件：

    DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc_new}}';

  2. 调用 EXECUTE DCM PROJECT 命令，并为 desc_new 变量指定一个值：

    EXECUTE DCM PROJECT MY_PROJECT (desc_new => 'This object is mine');