Snowflake DCM Projects — Extended capabilities (early access)

Introduction

This document describes a rolling set of new DCM Project capabilities that are available in private preview to selected customers. These features extend the core DCM Projects functionality with additional object types and deployment capabilities.

Over time, this document will be extended with new capabilities as they become available for early testing. Once a capability is sufficiently tested and stable, it will progress into the Public Preview release of DCM Projects and be removed from this document.

Early access for the following DCM capabilities is currently available in private preview:

For the main DCM documentation of all publicly available functionality, see Snowflake DCM Projects.

DEFINE AGENT

Use DEFINE AGENT to declaratively manage a Cortex Agent in a DCM Project. An agent definition consists of a YAML specification (models, instructions, tools, and tool resources) and an optional JSON profile (display settings such as the display name and color). For the content of the specification and profile, see CREATE AGENT.

You can provide the specification and profile in two ways:

  • Inline in the definition file, enclosed in $$ delimiters.
  • As files in a project asset, referenced with an asset:// URI in a FROM clause.

The specification and profile references are independent of each other. For example, you can combine an inline specification with a profile from a project asset.

Define an agent with an inline specification and profile

Use SPECIFICATION = $$ ... $$ and PROFILE = $$ ... $$ to write the YAML specification and the JSON profile directly in the definition file. Jinja templating variables, such as {{env_suffix}}, are rendered in inline specifications and profiles, so tool resources can point to the semantic views and warehouses of the current deployment target:

define agent DCM_DEMO{{env_suffix}}.SERVE.CITY_SALES_AGENT
    comment = 'Specification and profile inlined'
    specification =
      $$
        models:
          orchestration: auto

        instructions:
          response: |
            You are the City Sales Assistant for a fleet of food trucks. Answer
            questions about orders and revenue by customer city. Lead with the answer
            and include the date range for any figures.
          sample_questions:
            - question: "Which cities had the highest revenue?"
            - question: "How many orders were placed in each city?"

        tools:
          - tool_spec:
              type: cortex_analyst_text_to_sql
              name: orders
              description: "Food truck orders with customer city, revenue, profit, and order counts."

        tool_resources:
          orders:
            semantic_view: DCM_DEMO{{env_suffix}}.SERVE.ORDERS_SEMANTIC_VIEW
            execution_environment:
              type: warehouse
              warehouse: DCM_DEMO_WH{{env_suffix}}
      $$
    profile =
      $$
        {
          "display_name": "City Sales Assistant",
          "color": "blue"
        }
      $$
;

Define an agent from a project asset

To keep the specification and profile in separate files, place them in folders outside sources/definitions/ and declare them as project assets in manifest.yml. In the following example, the specification is specific to one agent, while the profile sits directly under agents/ so that other agents can share it:

my_dcm_project/
├── manifest.yml
├── agents/
│   ├── profile.json
│   └── menu_analyst/
│       └── menu_analyst_spec.yaml
└── sources/
    └── definitions/
        └── agents.sql          ← DEFINE AGENT statement
assets:
  menu_analyst:
    path: 'agents/menu_analyst/**/*'
  agent_profile:
    path: 'agents/profile.json'

Then reference the assets in the FROM clause of the SPECIFICATION and PROFILE properties. The FROM clause only accepts references to assets declared in the manifest, not file paths. When an asset declares a single file, such as agent_profile, the asset name resolves to that file:

define agent DCM_DEMO{{env_suffix}}.SERVE.MENU_ANALYST_AGENT
    comment = 'Specification from the menu_analyst asset, profile from the shared agent_profile asset'
    specification
        from 'asset://menu_analyst/menu_analyst_spec.yaml'
    profile
        from 'asset://agent_profile'
;

You can reuse the same asset across multiple agent definitions.

Agent versions and DCM deployments

Cortex Agents have built-in versioning, which separates a mutable live version from immutable named versions that you create with COMMIT or ADD VERSION. When you define and deploy an agent with a DCM project, each deployment that changes the agent definition updates only the agent’s live version. A DCM deployment doesn’t commit the live version, add a named version, or change the default version.

Named versions are immutable, so a DCM deployment leaves every named version unchanged, including versions that an alias or the default version points to. This separation supports an intentional two-step release process: deploy a new live version to production with DCM and test it there. When the live version is ready for users, commit it or change the default version manually.

Functional limitations

  • YAML specification files and JSON profile files in a project asset don’t support Jinja templating. Object names, such as the semantic view and warehouse under tool_resources, must be written as literal names. If you need Jinja templating, for example to point tool resources to different objects per deployment target, use an inline specification or profile instead.
  • The PLAN and DEPLOY changeset detects changes to an asset file or to an inline specification or profile, but doesn’t parse their content yet. The changeset shows that the specification or profile changed, but not what changed inside the YAML or JSON.

DEFINE STAGE … FROM a project asset

Use DEFINE STAGE with a FROM clause to define an internal stage that DCM populates with the files of a project asset during deployment. For example, you can deploy seed data files for dictionary tables, such as country codes or other lookup values.

Warning

DCM manages the full content of a stage defined with FROM. During deployment, DCM removes any file from the stage that isn’t in the asset path, including files that were uploaded to the stage manually.

Place the files outside sources/definitions/ and declare them as a project asset in manifest.yml. An asset can be a single file or a glob pattern. The following example deploys an internal stage for CSV files that seed dictionary tables:

my_dcm_project/
├── manifest.yml
├── seed_data/
│   ├── country_codes.csv
│   └── currency_codes.csv
└── sources/
    └── definitions/
        └── stages.sql          ← DEFINE STAGE statement
assets:
  lookup_values:
    path: 'seed_data/**/*'

Then reference the asset in the FROM clause of a DEFINE STAGE statement:

define stage DCM_DEMO{{env_suffix}}.RAW.SEED_DATA
    from 'asset://lookup_values/'
    comment = 'Seed data for dictionary tables'
;

The PLAN and DEPLOY changesets capture file changes in the asset as an ALTER on the stage and list the names of the files that were added, modified, or removed. They don’t parse file content, so the changeset doesn’t show what changed inside a file. For example, snow dcm plan output after adding one file and editing another looks like this:

ALTER    STAGE    DCM_DEMO_DEV.RAW.SEED_DATA
└─ files
   ├─ added region_codes.csv
   └─ modified country_codes.csv

Planned 1 entity (0 to create, 1 to alter, 0 to drop).

Functional limitations

  • FROM is supported only for internal stages.
  • DCM doesn’t apply Jinja templating to the content of asset files. Files are uploaded to the stage as they are.
  • Procedures and functions can’t reference a stage defined with FROM in their IMPORTS clause yet.

DEFINE API INTEGRATION

Use DEFINE API INTEGRATION to declaratively manage an API integration in a DCM Project. API integrations store configuration for HTTPS API services, including cloud proxy services, Git repository APIs, and external Model Context Protocol (MCP) servers.

DEFINE EXTERNAL ACCESS INTEGRATION

Use DEFINE EXTERNAL ACCESS INTEGRATION to declaratively manage an external access integration in a DCM Project. External access integrations allow UDF or procedure handler code to access external network locations through configured network rules and, when needed, secrets.

DEFINE STORAGE INTEGRATION

Use DEFINE STORAGE INTEGRATION to declaratively manage a storage integration in a DCM Project. Storage integrations connect Snowflake to external cloud storage without requiring users to supply cloud credentials when creating stages or loading and unloading data.

DEFINE DBT PROJECT

You can define a dbt project, its orchestration, infrastructure, and access control together in a single DCM Project folder, then deploy everything to any environment with one command.

Most commonly used is the combination of dbt projects + Tasks to execute dbt test and dbt run on a defined schedule. You can define a DAG of Tasks to orchestrate runs of different dbt projects or individual models.

Create a DCM Project for dbt

An existing dbt project folder can include:

  • models
  • dbt_project.yml
  • packages.yml
  • profiles.yml

Place the dbt project in a subfolder under sources/, outside sources/definitions/. For example, use sources/dbt/dbt_pipeline/.

Note

Project assets aren’t yet supported for DEFINE DBT PROJECT. For now, specify the relative path to the dbt project under sources/ directly in the FROM clause. Asset support is planned for an upcoming release and will become the standard way to reference dbt project files.

my_dcm_project/
├── manifest.yml
└── sources/
    ├── definitions/
    │   ├── pipeline.sql          ← DEFINE DBT PROJECT statement
    │   ├── access.sql
    │   └── infra.sql
    └── dbt/
        └── dbt_pipeline/         ← path referenced in the FROM clause
            ├── dbt_project.yml
            ├── packages.yml
            ├── profiles.yml
            └── models/

Add the DEFINE DBT PROJECT statement to your DCM definitions with:

  • The relative path from manifest.yml to the dbt project folder
  • A default target (which can use Jinja templating to match the DCM deployment target)

In addition, you can add Tasks to execute dbt commands after the deployment as well as grants on the dbt project object or future tables and views.

A DCM Project for a dbt pipeline containing the dbt project with its seeds, macros, and models, tasks that execute dbt test and dbt run, and expectations, grants, and schema definitions.
define dbt project {{db}}.PROJECTS.DBT_PIPELINE
    from 'sources/dbt/dbt_pipeline'
    default_target = '{{dbt_env}}'
;


define task {{db}}.PROJECTS.RUN_DBT_PIPELINE  -- optional: Task(s) to execute your deployed dbt project
    warehouse = {{wh}}
    schedule = '60 MINUTE'
    started     -- (optional) new DCM-specific property that defines the target-state after a DCM deployment
  as
    execute dbt project {{db}}.PROJECTS.DBT_PIPELINE args='run';

define task {{db}}.PROJECTS.TEST_DBT_PIPELINE
    warehouse = {{wh}}
    after {{db}}.PROJECTS.RUN_DBT_PIPELINE
    started
  as
    execute dbt project {{db}}.PROJECTS.DBT_PIPELINE args='test';

Pass DCM variables to dbt

DCM Jinja templating and dbt templating variables are completely isolated. There’s no automatic pass-through between the DCM manifest.yml configuration and the dbt profiles.yml targets. The two configurations must be maintained separately and kept in sync.

If you need values from the DCM templating context inside a dbt run (for example, the active dbt target), pass them explicitly through the args of the EXECUTE DBT PROJECT statement. Jinja in args is rendered by DCM before the command is executed, so any DCM templating variable can be injected.

define dbt project DCM_DEMO_2_MARKETING{{env_suffix}}.PROJECTS.DBT_PIPELINE
    from 'sources/dbt/dbt_pipeline'
    default_target = '{{dbt_env}}'
;


-- Task graph to schedule dbt project test and run
define task DCM_DEMO_2_MARKETING{{env_suffix}}.PROJECTS.DBT_PIPELINE_RUN
    warehouse = DCM_DEMO_2_MARKETING_WH{{env_suffix}}
    schedule = '60 MINUTE'
    started
  as
    execute dbt project DCM_DEMO_2_MARKETING{{env_suffix}}.PROJECTS.DBT_PIPELINE
        args='run --target {{dbt_env}}'
;

Plan & deploy a DCM Project for dbt

Run your regular DCM plan and deploy commands. If the DEFINE DBT PROJECT statement or any file in the dbt project folder has changed since the last successful deployment, PLAN:

  • Render the jinja templating
  • Compile the entire DCM Project
  • Show the dbt project as part of the plan output

PLAN DELTA also detects these changes and shows the dbt project in the changeset.

The dbt project is compiled during DEPLOY, not during PLAN. PLAN only validates that the dbt project object can be created successfully. It doesn’t check whether the dbt project will run successfully.

Tables created by dbt don’t show as “DCM managed entities” because they aren’t defined directly in the DCM definitions. Removing the DEFINE DBT PROJECT statement drops the dbt project object on the next deployment, but it won’t drop the tables created by dbt.

You can also consider creating a new DCM Project for dbt on top of an existing “platform” project.

A DCM Project for a dbt pipeline containing the dbt project, tasks, expectations, grants, and schema definitions above a second DCM Project that contains database, schema, warehouse and integration.

Functional limitations

  • PLAN and DEPLOY output only show the operation for a Snowflake dbt project object (CREATE / ALTER / DROP) and don’t show more granular changes in the dbt project configuration or models.
  • Dependencies: dbt models can refer to other objects defined in DCM, but other DCM objects can’t reference tables created by dbt, meaning dbt projects can’t have downstream dependencies.
  • The relative path must resolve to a folder under sources/ in the DCM Project. You can’t specify a path to another repository or a folder outside the DCM Project.

DEFINE ICEBERG TABLE

Use DEFINE ICEBERG TABLE to declaratively manage an Apache Iceberg™ table that uses Snowflake as the Iceberg catalog in a DCM project. The table can store its data and metadata either in your cloud storage through an external volume or in Snowflake storage (EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED').

DEFINE ICEBERG TABLE supports only Snowflake-managed Iceberg tables. Externally managed Iceberg tables, which use a catalog integration to connect to an external Iceberg catalog, aren’t supported.

Functional limitations

  • Parquet Direct tables aren’t supported yet.
  • You can’t define external volumes in a DCM project. When a table uses an external volume, the external volume must already exist and the deploying role needs the USAGE privilege on the external volume.
  • The following properties can’t be changed after the table is created, because ALTER ICEBERG TABLE doesn’t support them:
    • EXTERNAL_VOLUME
    • BASE_LOCATION
    • STORAGE_SERIALIZATION_POLICY
    • TRANSIENT
  • Upgrading a table from Iceberg version 2 to version 3 is permanent. A version 3 table can’t be downgraded to version 2.

DCM Lite

DCM Lite is a lightweight way to benefit from the dry-run capabilities of DCM PLAN: validate whether statements would run successfully, and see their impact on existing objects in the changeset output. You write the definitions directly in a BEGIN ... END block of an EXECUTE DCM PLAN or EXECUTE DCM DEPLOY statement. Because DCM Lite doesn’t require a DCM Project object, you don’t need additional privileges to create one, you don’t create any files such as a manifest file, and you don’t manage a project or its artifacts. Each execution is completely ephemeral.

DCM Lite only supports PLAN and DEPLOY operations. It’s intended for the following uses:

  • Getting started with DCM: Users who are new to DCM can try DCM plans on their own statements, and then consider moving to the full capabilities of DCM projects.
  • Validating DDL from coding agents: Coding agents can use DCM Lite to safely validate DDL syntax before running it.

Differences from a DCM project

Because DCM Lite has no DCM Project object, it differs from a regular DCM project in the following ways:

  • No managed objects: The statements and the objects they define aren’t managed by any DCM project. Every run is completely independent of any previous run. Removing a statement from a later run doesn’t drop the object that an earlier run deployed.
  • No project owner role: DCM Lite always runs with caller’s rights, using the privileges of the role that runs the statement.
  • No deployment history or artifacts: Executions don’t appear in any DCM deployment history, and DCM Lite doesn’t store any artifacts.
  • No templating or variables: Definitions don’t support Jinja templating or any variables.

Note

DCM Lite doesn’t work for objects, grants, or attachments that are already managed by an existing DCM project.

Syntax

EXECUTE DCM { PLAN | DEPLOY }
FROM
BEGIN
  <definitions>
END;

Where <definitions> contains DEFINE, GRANT, and ATTACH statements. Every statement that works in the definition files of a regular DCM project works in DCM Lite, except for Jinja templating and variables.

DCM Lite uses the same automatic dependency resolution as a regular DCM project to execute all statements in the right order. You can write the statements inside the BEGIN ... END block in any order.

Example

Plan the creation of a database and a schema, and a grant on the schema:

execute DCM PLAN
from
begin
	define schema MY_TEST_DB.TEST;
	define database MY_TEST_DB;
	grant usage on schema MY_TEST_DB.TEST to role PUBLIC;
end;

Output

EXECUTE DCM PLAN and EXECUTE DCM DEPLOY return the same JSON changeset as EXECUTE DCM PROJECT ... PLAN and EXECUTE DCM PROJECT ... DEPLOY. For the format, see PLAN and DEPLOY output.

To make the changeset easier to read for humans, you can run the following statement directly after EXECUTE DCM PLAN or EXECUTE DCM DEPLOY. It uses RESULT_SCAN(LAST_QUERY_ID()) to flatten the JSON output into a table with one row per object:

-- flatten json output to table
with JSON_INPUT as (
	select $1 as PLAN
	from table(result_scan(last_query_id())))
select
	f.value:type ::string as OPERATION_TYPE,
	f.value:object_id:domain ::string as OBJECT_TYPE,
	f.value:object_id:fqn ::string as OBJECT_NAME,
	listagg(distinct
		case c.value:kind::string
			when 'set' then c.value:attribute_name || '=' || c.value:value::string
			when 'collection' then c.value:collection_name || ': ' || g.value:kind || ' ' || g.value:item_id:desc::string
			else c.value::string
		end, '; ') as CHANGES
from
	JSON_INPUT,
	lateral flatten(input => JSON_INPUT.PLAN:changeset) f,
	lateral flatten(input => f.value:changes, outer => true) c,
	lateral flatten(input => c.value:changes, outer => true) g
group by
	all
order by
	OPERATION_TYPE
;

DCM Test Branches

DCM Test Branches lets you validate the business logic of DCM project definition changes before you deploy them. Test scripts run against cloned objects on an isolated, fully managed branch, which leaves the objects in your account untouched. For more information, see DCM Test Branches.

Note

DCM Test Branches is a separate private preview. It isn’t automatically enabled for DCM Projects early access customers and requires a separate sign-up.

CLI enhancements

An early-access version of the Snowflake CLI includes improvements to several DCM Projects commands. Re-run the same command with --force occasionally to pick up the latest updates to the early-access build:

uv tool install 'git+https://github.com/snowflakedb/snowflake-cli.git@dcm-early-access'
uv tool install --force 'git+https://github.com/snowflakedb/snowflake-cli.git@dcm-early-access'

To revert to the latest official release on main:

uv tool uninstall snowflake-cli
uv tool install snowflake-cli

Note

Details of these improvements (such as syntax and output format) are subject to change while they’re in early access.

All of the commands (except snow dcm init) support the --save-output flag, which saves the command output as a .json file under out/.

snow dcm compile (new command)

snow dcm compile runs a static analysis of all DCM definitions and returns any errors or warnings found, grouped by file and entity. It’s intended for quickly checking iterative definition changes and catching errors before committing.

  • Validates syntax and dependencies
  • Runs faster than PLAN, but doesn’t catch all possible errors. (Always run PLAN to preview changes before deploying)
  • Shows a compressed file upload summary (file counter per path) with a progress bar

snow dcm dependencies (new command)

snow dcm dependencies runs a static analysis of all DCM definitions and builds a Mermaid flowchart representing the dependencies between all objects in the project (tables, dynamic tables, views, functions, procedures, and tasks).

The diagram is written to out/dependencies.md. The CLI prints a link to the file so you can open it in your IDE’s Markdown preview and explore the dependency graph visually.

Note that these dependencies refer to the deployment of objects (CREATE). It does not resolve run-time dependencies (for example, a Task that calls a stored procedure).

  • Generate a dependency diagram for the current project:
    snow dcm dependencies
    
    snow dcm dependencies --target dev
    

snow dcm init (new command)

snow dcm init is the starting point for two common workflows: creating a brand-new empty DCM Project, or deploying an existing set of DCM definitions (from a repository or local path) to a new target environment. In both cases it bootstraps the project in a single run: it writes or updates a manifest.yml, creates the DCM Project object in Snowflake, and provisions any missing supporting objects (database, schema, warehouse). Before making any change, it prints a summary of every action and asks for confirmation. Nothing is created if you decline.

To start a new project the init process will walk you through all required steps for setting up a new project structure:

snow dcm init -c my_connection

If you want to use an existing project folder and add a new target for a new account, then run init from a directory that already contains a manifest.yml. A new target block is appended and your existing definitions are left untouched:

snow dcm init --target prod_2 -c my_connection

During a run, init resolves everything a target needs:

  • Target name — defaults to your account alias; re-prompts if the name is invalid or already used.
  • DCM Project object name — defaults to the target name. Identifiers with special characters are automatically wrapped in double quotes.
  • Database and schema — uses your connection’s defaults (or prompts when there are none) and creates them if they don’t exist.
  • Project owner — uses your current role, or prompts if it can’t be determined.
  • Warehouse — uses your connection’s warehouse, or provisions an X-Small DCM_WH (or a name you choose) and tells you how to configure it.

For automation and CI, pass --force to approve all changes non-interactively. --force requires --target; if that target already exists it’s reused as-is rather than failing:

snow dcm init \
  --project-name my_project \
  --target dev \
  --project-identifier MY_DB.MY_SCHEMA.MY_PROJECT \
  --force \
  -c my_connection

The following options control init behavior:

OptionDescription
--project-name <name>Create a new project in a subfolder of this name. Omit to add a target to an existing manifest.yml.
--target <name>Name of the target to create in the manifest. Defaults to the account alias. Required with --force.
--project-identifier <id>Identifier of the DCM Project object (for example, MY_DB.MY_SCHEMA.MY_PROJECT). Defaults to the target name.
--if-not-existsDo nothing if the DCM Project object already exists in Snowflake.
--forceApprove all changes non-interactively.