EXECUTE DCM PROJECT¶

Executa uma das seguintes ações em um projeto DCM:

EXECUTE DCM PROJECT <name> PLAN efetua dry run de um DCM project para analisar as alterações que serão aplicadas ao destino durante uma implantação, mas não aplica nenhuma alteração.
EXECUTE DCM PROJECT <name> DEPLOY implanta na conta as alterações definidas nos arquivos de definição do projeto.
EXECUTE DCM PROJECT <name> REFRESH ALL atualiza tabelas dinâmicas gerenciadas pelo DCM project.
EXECUTE DCM PROJECT <name> TEST ALL testa todas as expectativas de funções de métrica de dados anexadas e gerenciadas pelo DCM project.
EXECUTE DCM PROJECT <name> PREVIEW retorna uma amostra de dados das definições atuais especificadas no caminho de origem para a tabela, exibição ou tabela dinâmica especificada.

Consulte também:: CREATE DCM PROJECT, ALTER DCM PROJECT, DESCRIBE DCM PROJECT, DROP DCM PROJECT, SHOW DCM PROJECTS, SHOW DEPLOYMENTS IN DCM PROJECT

Sintaxe¶

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

Parâmetros obrigatórios¶

name

Especifica o identificador do projeto DCM a ser executado.

Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

PLAN

Instrui o Snowflake a efetuar dry run do DCM project. Para dry run, o Snowflake analisa as alterações que serão aplicadas ao destino durante uma implantação, mas não aplica nenhuma alteração.

DEPLOY [ AS 'deployment_name_alias' ]

Implanta na conta as alterações definidas nos arquivos de definição do projeto. Opcionalmente, especifica um alias para a implantação.

FROM 'source_files_path'

Especifica o diretório que contém os arquivos de origem para o DCM project. O diretório deve conter um arquivo de manifesto e pelo menos um arquivo de definição em /sources/definitions/. O arquivo de manifesto fornece os valores de modelagem, caso uma configuração tenha sido especificada.

REFRESH ALL

Atualiza todas as tabelas dinâmicas que são gerenciadas pelo DCM project no momento.

TEST ALL

Testa todas as expectativas de qualidade de dados anexadas a tabelas, tabelas dinâmicas ou exibições que são gerenciadas pelo DCM project no momento.

PREVIEW fully_qualified_table_object_name

Retorna uma amostra de dados das definições atuais especificadas no caminho de origem para a tabela, exibição ou tabela dinâmica especificada, seja qual for o estado implantado.

Parâmetros opcionais¶

USING CONFIGURATION config_name

Especifica a configuração a ser usada. Isso permite que você personalize as implantações de acordo com os diferentes ambientes, como desenvolvimento, preparação ou produção, sem usar arquivos de definição de projeto distintos.

Se o nome da configuração não estiver em letras maiúsculas, coloque-o entre aspas duplas.

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

Opcionalmente, especifica os valores das variáveis de modelo. O uso dessa opção substitui os valores padrão ou de configuração para a variável específica. A expressão única deve ter o seguinte formato: <variable_name> => <variable_value>. Para listas, use o seguinte formato: <variable_name> => [<value1>, <value2>, ...]. Por exemplo: wh_size => 'MEDIUM' ou teams => ['TEAM_A', 'TEAM_B'].

Isso permite que você personalize as implantações de acordo com os diferentes ambientes, como desenvolvimento, preparação ou produção, sem usar arquivos de definição de projeto distintos.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:


Privilégio	Objeto	Notas
OWNERSHIP	Projeto 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).

Operar em um objeto em um esquema requer pelo menos um privilégio no banco de dados pai e pelo menos um privilégio no esquema pai.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Saída¶

Após a execução de DCM project, esse comando retornará a seguinte saída dependendo da variação:

PLAN e DEPLOY: uma única linha contendo um objeto JSON com o log de alterações.
PREVIEW: um conjunto de resultados.
REFRESH ALL: uma única linha contendo um objeto JSON com a resposta completa.
TEST ALL: uma única linha contendo um objeto JSON com a resposta completa.

Saída de PLAN e DEPLOY¶

Nota

Durante a fase de versão preliminar, o formato exato da saída pode mudar.

A saída padrão do plano contém as seguintes informações sobre a execução do plano no formato 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>
            }
          ]
        }
      ]
    }
  ]
}


Propriedade	Descrição
`version`	Versão do esquema do formato de saída. A versão 2 é a mais recente e a única compatível.
`metadata`	Informações contextuais sobre a execução.
`metadata.timestamp`	Carimbo de data/hora ISO 8601 de quando o comando foi executado.
`metadata.query_id`	Identificador exclusivo da consulta que gerou este plano.
`metadata.project_name`	Nome totalmente qualificado do objeto de projeto DCM.
`metadata.user`	Nome do usuário que executou o comando.
`metadata.role_name`	Função ativa utilizada para executar o comando.
`metadata.command`	O comando que foi executado. `PLAN` ou `DEPLOY`.
`changeset`	Uma matriz de entradas de alteração. Cada entrada representa um objeto que seria ou foi criado, alterado ou descartado. Uma matriz vazia indica que as definições do projeto já estão sincronizadas com a conta.
`changeset[].type`	A ação planejada para o objeto. Valores possíveis: `CREATE`, `ALTER` e `DROP`.
`changeset[].object_id`	Identifica o objeto de destino.
`changeset[].object_id.domain`	O tipo de objeto Snowflake.
`changeset[].object_id.name`	Nome do objeto.
`changeset[].object_id.fqn`	Nome totalmente qualificado do objeto.
`changeset[].object_id.database`	Banco de dados que contém o objeto. Omitido para objetos em nível de conta.
`changeset[].object_id.schema`	Esquema que contém o objeto. Omitido para objetos em nível de banco de dados e de conta.
`changeset[].changes`	Uma matriz de descritores de alteração que detalha as modificações específicas de atributos.
`changeset[].changes[].kind`	O tipo de alteração. Possíveis valores: `set`, `changed`, `unset`, `nested`, `collection`. O valor de `kind` determina as chaves restantes no objeto.
`changeset[].changes[].attribute_name`	Nome do atributo que está sendo definido ou alterado. Presente quando `kind` é `set`, `changed` ou `unset`.
`changeset[].changes[].value`	O novo valor do atributo. Presente quando `kind` é `set` ou `changed`.
`changeset[].changes[].prev_value`	O valor anterior do atributo antes da alteração. Presente somente quando `kind` é `changed`.
`changeset[].changes[].collection_name`	Nome da coleção que está sendo modificada (por exemplo, `columns`, `constraints`, `privileges`, `expectations`). Presente somente quando `kind` é `collection`.
`changeset[].changes[].id_label`	Rótulo utilizado para identificar itens dentro da coleção (por exemplo, `name`). Presente somente em certas coleções.
`changeset[].changes[].changes`	Uma matriz aninhada de descritores de itens de coleção. Presente somente quando `kind` é `collection`.
`changeset[].changes[].changes[].kind`	O tipo de alteração no item da coleção. Valores possíveis: `added`, `removed` e `modified`.
`changeset[].changes[].changes[].item_id`	Identifica o item dentro da coleção. Pode ser uma cadeia de caracteres ou um objeto, dependendo do tipo da coleção.
`changeset[].changes[].changes[].changes`	Uma matriz de descritores de alteração adicionais para este item. Presente para itens `added` e `modified`. Sempre ausente para itens `removed`.

Exemplo de saída de um plano:

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

Saída de REFRESH ALL¶

A saída JSON contém os resultados da operação de atualização da tabela dinâmica no seguinte formato:

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


Propriedade	Descrição
`dts_refresh_result`	Contém os resultados da operação de atualização da tabela dinâmica.
`refreshed_tables[]`	Uma matriz de entradas, uma para cada tabela dinâmica que foi atualizada.
`table_name`	Nome totalmente qualificado da tabela dinâmica que foi atualizada.
`statistics`	Estatísticas de atualização da tabela.
`inserted_rows`	Número de linhas inseridas durante a atualização.
`deleted_rows`	Número de linhas excluídas durante a atualização.
`data_timestamp`	Carimbo de data/hora ISO 8601 que representa a atualização pontual dos dados após a atualização.

Um exemplo de saída JSON para uma atualização de tabela dinâmica:

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

Saída de TEST ALL¶

A saída de TEST contém o status geral e as expectativas com os valores no seguinte formato:

Nota

Durante a fase de versão preliminar, o formato exato da saída pode mudar.

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


Propriedade	Descrição
`status`	Resultado geral da execução do teste. Valores possíveis: `SUCCESSFUL` (todas as expectativas atendidas), `FAILED` (uma ou mais expectativas violadas).
`expectations[]`	Uma matriz de resultados de expectativa, um para cada expectativa de qualidade de dados avaliada.
`table_name`	Nome totalmente qualificado da tabela ou exibição na qual a expectativa foi avaliada.
`metric_database`	Banco de dados com a função de métrica de dados.
`metric_schema`	Esquema com a função de métrica de dados.
`metric_name`	Nome da função de métrica de dados (por exemplo, `NULL_COUNT`, `MIN`, `UNIQUE_COUNT`).
`expectation_name`	Nome da expectativa conforme definido no projeto.
`expectation_expression`	Expressão booliana usada como base para o valor da métrica avaliado (por exemplo, `value = 0`, `value >= 0`).
`value`	O resultado da avaliação da função de métrica de dados. Presente somente quando `expectation_violated` é `false`.
`expectation_violated`	Se a expectativa foi violada. `true` se o valor da métrica não satisfez a expressão de expectativa; caso contrário, `false`.
`column_names`	Uma matriz de nomes de colunas em que a função de métrica de dados foi avaliada.

Um exemplo de saída JSON de um teste de qualidade de dados:

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

Notas de uso¶

Ao executar um DCM project com EXECUTE DCM PROJECT PLAN, a saída do comando é igual a da implantação real. A diferença é que nenhuma alteração na conta afetada é aplicada. Esse recurso permite verificar se os arquivos de definição renderizados têm uma sintaxe válida, quais alterações serão aplicadas à conta e se a função de proprietário do projeto tem os privilégios necessários para aplicar as alterações.

Para evitar alterações não intencionais e detectar erros, sempre execute EXECUTE DCM PROJECT PLAN antes de implantar um DCM project.

Suporte para variáveis de modelo¶

As variáveis de modelo permitem que você escolha dinamicamente o conteúdo dos arquivos de definições parametrizados durante a execução do DCM project. Você pode usar variáveis de modelo das seguintes maneiras:

Consulte a seção Exemplos de variáveis de modelo para ver os exemplos.

Exemplos¶

Exemplos básicos¶

Executar um DCM project no modo PLAN para validar alterações em um projeto sem aplicá-las:

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

Executar um projeto DCM no modo DEPLOY (para aplicar alterações) para especificar um alias de implantação e uma configuração chamada PROD:

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

Exemplos de variáveis de modelo¶

Os exemplos a seguir demonstram como você pode especificar o valor das variáveis de modelo em uma instrução EXECUTE DCM PROJECT.

Substituir a variável de modelo definida no arquivo de manifesto do projeto DCM

Defina uma variável de modelo chamada desc no arquivo de manifesto:

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

Crie um arquivo de definição que use a variável de modelo:
```
DEFINE DATABASE NEW_DB;
DEFINE TABLE NEW_DB.PUBLIC.TBL (ID INT) COMMENT = '{{desc}}';
```
Chame o comando EXECUTE DCM PROJECT no modo DEPLOY e especifique um valor para a variável desc para substituir o valor padrão no manifesto:
```
EXECUTE DCM PROJECT MY_PROJECT DEPLOY
  USING CONFIGURATION FIRST_CONFIG (desc => 'This object is mine')
  FROM '/my/project/source';
```

Fornecer um valor para uma variável de modelo não definida no arquivo de manifesto

Crie um arquivo de definição com os comandos desejados:

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

Chame o comando EXECUTE DCM PROJECT e especifique um valor para a variável desc_new:
```
EXECUTE DCM PROJECT MY_PROJECT (desc_new => 'This object is mine');
```