DCM Projects files and templates¶

Map between project definitions and project objects¶

DCM Projects definition files aren’t strictly tied to a specific DCM project object. You can use the same set of definitions to deploy to multiple projects, either on different Snowflake accounts or by referencing different configuration profiles. For example, the same definition files on a repository branch can be deployed to both DEV and PROD accounts as shown in the following figure.

Similarly, you can execute a DCM Projects object by referencing definition files from different paths. For example, your CI/CD automation can deploy definitions from your main branch, and you can manually run a PLAN from your local definition files against the same project to check how your definitions diverge from the latest deployment. You can also use this approach for ad-hoc manual deployments from other branches or local paths.

Macros¶

Macro files are any SQL files located in the macros folder and its sub-folders. They can only contain macros.

An example of a directory structure of a DCM project with macro files is:

My_dcm_project
 |_ manifest.yml
 |_ sources
    |_ definitions
       |_ my_definitions.sql
    |_ macros
       |_ my_global_macros.sql

Similar to functions in regular programming languages, macros help organize often-used pieces of code into reusable functions, thereby avoiding repetition and following the DRY (Don’t Repeat Yourself) principle. Macros in DCM Projects work in the same way as Jinja2 macros with the following exceptions:

• Dedicated location for macro files in the macros folder.

• Macros defined in macro files are automatically visible in other source files. The import Jinja tag is not permitted.

• Duplicate definition of a macro with the same name is detected and rejected.

Template comments¶

In SQL commands, you can add -- before your code to comment out the line. Jinja still processes variables within the SQL code but leaves the SQL comments.

For example, the following Jinja code:

-- hello {{ project_owner_role }}

Renders as:

-- hello DCM_DEVELOPER

Commented out commands do not execute in SQL. You can use template comments to debug Jinja templating without affecting your SQL code.

To ignore Jinja code during rendering, add # inside opening and closing brackets as shown in the following example:

{# This Jinja comment will not appear in the rendered output. #}

Configurations¶

When using templates in your object definitions, you have the following options:

• Assign values to variables at runtime.

• Define different configuration profiles under templating: configurations: in the manifest.yml. Each target can reference a configuration through templating_config. See Project templating configurations for more details.

  If configuration profiles are defined and a target references one through templating_config, the configuration is automatically applied when using that target. For examples, see Plan a DCM project.

  The primary use case for configuration profiles in DCM Projects is to target different environments. Configuration profiles allow you to do the following:

  • Deploy the same code to multiple environments.

  • Test production code on a non-prod environment at a reduced scale.

  • Maintain multiple isolated environments on the same account.

  Not all templating configurations have to be referenced by a target profile. You can keep unused configurations to switch the templating config for your target from one to another.

• Define shared default values under templating: defaults: to avoid repeating common variables across configurations. See Project templating configurations for more details.

• Overwrite specific variables with one-time values at runtime using the --variable flag in CLI.

Variables are resolved with a three-tier hierarchy: global defaults < configuration variables < runtime execution variables.

Dictionaries¶

DCM Projects templating supports dictionaries as variable values, enabling structured configuration for complex multi-tenant or multi-resource deployments.

By grouping related configuration details into dictionaries, you get:

• Granular control: Apply specific settings, such as warehouse sizes, retention policies, and grants, to individual resources without writing unique logic for every variation.

• Cleaner code bases: Replace repetitive hard-coded scripts with dynamic loops that adapt based on the configuration.

• Scalability: Onboard new teams or resources by adding entries to your configuration, rather than refactoring deployment pipelines.

templating:
  defaults:
    user: "GITHUB_ACTIONS_SERVICE_USER"
    wh_size: "X-SMALL"
  configurations:
    PROD:
      env_suffix: ""
      project_owner_role: "DCM_PROD_DEPLOYER"
      teams:
        - name: "Marketing"
          wh_size: "MEDIUM"
          data_retention_days: 14
          needs_sandbox_schema: true
        - name: "Finance"
          wh_size: "X-LARGE"
          data_retention_days: 90
          needs_sandbox_schema: false
        - name: "HR"
          data_retention_days: 30
          needs_sandbox_schema: false

-- loop through team dictionaries
{% for team in teams %}
    {% set team_name = team.name | upper %}

    -- inject dictionary values directly into object properties
    define schema DCM_DEMO_1{{env_suffix}}.{{team_name}}
        comment = 'using JINJA dictionary values'
        data_retention_time_in_days = {{ team.data_retention_days }};

    -- pass the name to your macro
    {{ create_team_roles(team_name) }}

    define table DCM_DEMO_1{{env_suffix}}.{{team_name}}.PRODUCTS(
        ITEM_NAME varchar,
        ITEM_ID varchar,
        ITEM_CATEGORY array
    )
    data_metric_schedule = 'TRIGGER_ON_CHANGES';

    {% if team_name == 'HR' %}
        define table DCM_DEMO_1{{env_suffix}}.{{team_name}}.EMPLOYEES(
            NAME varchar,
            ID int
        )
        comment = 'This table is only created in HR';
    {% endif %}

    -- use dictionary booleans to deploy optional infrastructure
    {% if team.needs_sandbox_schema | default(false) %}
        define schema DCM_DEMO_1{{env_suffix}}.{{team_name}}_SANDBOX
            comment = 'Sandbox schema defined via dictionary flag'
            data_retention_time_in_days = 1;
    {% endif %}

{% endfor %}