EXECUTE DCM PROJECT¶

Executes one of the following actions on a DCM project:

EXECUTE DCM PROJECT <name> PLAN performs a dry run of the DCM project to analyze the changes that would be applied to the target during a deployment, but doesn’t apply any changes.
EXECUTE DCM PROJECT <name> DEPLOY deploys the changes defined in the project’s definition files to the account.
EXECUTE DCM PROJECT <name> REFRESH ALL refreshes dynamic tables managed by the DCM project.
EXECUTE DCM PROJECT <name> TEST ALL tests all expectations from attached data metric functions managed by the DCM project.
EXECUTE DCM PROJECT <name> PREVIEW returns a data sample of the current definitions specified in the source path for the specified table, view, or dynamic table.

See also:: 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>'

Required parameters¶

name

Specifies the identifier for the DCM project to execute.

If the identifier contains spaces or special characters, the entire string must be enclosed in double quotes. Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

PLAN

Instructs Snowflake to perform a dry run of the DCM project. For a dry run, Snowflake analyzes the changes that would be applied to the target during a deployment, but doesn’t apply any changes.

DEPLOY [ AS 'deployment_name_alias' ]

Deploys the changes defined in the project’s definition files to the account; optionally specifies an alias for the deployment.

FROM 'source_files_path'

Specifies the directory that contains the source files for the DCM project. The directory must contain a manifest file and at least one definition file in /sources/definitions/. The manifest file provides the templating values in case a configuration was specified.

REFRESH ALL

Refreshes all dynamic tables that are currently managed by the DCM project.

TEST ALL

Tests all data quality expectations attached to tables, dynamic tables, or views which are currently managed by the DCM project.

PREVIEW fully_qualified_table_object_name

Returns a data sample of the current definitions specified in the source path for the specified table, view, or dynamic table - independent of any deployed state.

Optional parameters¶

USING CONFIGURATION config_name

Specifies the configuration to use. This lets you customize deployments for different environments, such as development, staging, or production, without using different project definition files.

If the configuration name is not in all uppercase, enclose it in double quotes.

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

Optionally specifies template variable values. Using this option overrides any default or configuration values for this specific variable. The single expression must have the following form: <variable_name> => <variable_value>. For lists, use the following form: <variable_name> => [<value1>, <value2>, ...]. For example: wh_size => 'MEDIUM' or teams => ['TEAM_A', 'TEAM_B'].

This lets you customize deployments for different environments, such as development, staging, or production, without using different project definition files.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:


Privilege	Object	Notes
OWNERSHIP	DCM project	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).

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Output¶

After the DCM project executes, this command returns the following output depending on the variation:

PLAN and DEPLOY: A single row containing a JSON object with the change log

PREVIEW: A resultset

REFRESH ALL: A single row containing a JSON object that contains the full response.

TEST ALL: A single row containing a JSON object that contains the full response.

Usage notes¶

When executing a DCM project with EXECUTE DCM PROJECT PLAN, the output of the command is the same as for the actual deployment. The difference is that no changes to the affected account are applied. This feature allows you to verify whether the rendered definition files have a valid syntax, what changes would be applied to the account, and wether the project owner role has the required privileges to apply these changes.

To avoid unintended changes and catch errors, always run EXECUTE DCM PROJECT PLAN before you deploy a DCM project.

Support for template variables¶

Template variables let you dynamically choose the content of the parameterized definitions files during the DCM project execution. You can use template variables in the following ways:

See the Template variable examples section for examples.

Examples¶

Basic examples¶

Execute a DCM project in PLAN mode to validate changes to a project without applying them:

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

Execute a DCM project in DEPLOY mode (to apply changes) to specify a deployment alias and a configuration named PROD:

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

Template variable examples¶

The following examples demonstrate how you can specify the value for template variables in an EXECUTE DCM PROJECT statement.

Override the template variable defined in the DCM project’s manifest file

Define a template variable named desc in the manifest file:

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

Create a definition file that uses the template variable:

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

Call the EXECUTE DCM PROJECT command in DEPLOY mode, and specify a value for the desc variable to override its default value in the manifest:
```
EXECUTE DCM PROJECT MY_PROJECT DEPLOY
  USING CONFIGURATION FIRST_CONFIG (desc => 'This object is mine')
  FROM '/my/project/source';
```

Provide a value for a template variable not defined in the manifest file

Create a definition file with the desired commands:

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

Call the EXECUTE DCM PROJECT command, and specify a value for the desc_new variable:
```
EXECUTE DCM PROJECT MY_PROJECT (desc_new => 'This object is mine');
```