ALTER DBT PROJECT¶

Syntax¶

ALTER DBT PROJECT [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER DBT PROJECT [ IF EXISTS ] ADD VERSION <version_name_alias>
  FROM '<source_location>'

ALTER DBT PROJECT [ IF EXISTS ] <name> SET
  [ DEFAULT_ARGS = '<string_literal>' ]
  [ COMMENT = '<string_literal>' ]

ALTER DBT PROJECT [ IF EXISTS ] <name> UNSET
  [ DEFAULT_ARGS ]
  [ COMMENT ]

Parameters¶

name

Specifies the identifier for the dbt project object to alter.

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.

RENAME TO new_name

Changes the name of the dbt project object to new_name. The new identifier must be unique for the schema.

For more information about identifiers, see Identifier requirements.

You can move the object to a different database and/or schema while optionally renaming the object. To do so, specify a qualified new_name value that includes the new database and/or schema name in the form db_name.schema_name.object_name or schema_name.object_name, respectively.

Note

• The destination database and/or schema must already exist. In addition, an object with the same name cannot already exist in the new location; otherwise, the statement returns an error.

• Moving an object to a managed access schema is prohibited unless the object owner (that is, the role that has the OWNERSHIP privilege on the object) also owns the target schema.

When an object is renamed, other objects that reference it must be updated with the new name.

ADD VERSION version_name_alias

Creates a new version name alias that corresponds to the version specified as source_location. The version name alias is a string literal.

FROM 'source_location'

A string that specifies the location of the source files and version for the dbt project from which the version name alias will be created.

The dbt project source files can be in any one of the following locations:

• A Git repository stage, for example:

  '@my_db.my_schema.my_git_repository_stage/branches/my_branch/path/to/dbt_project_or_projects_parent'

  For more information about creating a Git repository object in Snowflake that connects a Git repository to a workspace for dbt Projects on Snowflake, see Create a workspace connected to your Git repository. For more information about creating and managing a Git repository object and stage without using a workspace, see Using a Git repository in Snowflake and CREATE GIT REPOSITORY.

• An existing dbt project stage, for example:

  'snow://dbt/my_db.my_schema.my_existing_dbt_project_object/versions/last'

  The version specifier is required and can be last (as shown in the previous example), first, or the specifier for any existing version in the form version$<num>. For more information, see Versioning for dbt project objects and files.

• An internal named stage, for example:

  '@my_db.my_schema.my_internal_named_stage/path/to/dbt_projects_or_projects_parent'

  Internal user stages and table stages aren’t supported.

• A workspace for dbt on Snowflake, for example:

  'snow://workspace/user$.public."my_workspace_name"/versions/live/path/to/dbt_projects_or_projects_parent'

  We recommend enclosing the workspace name in double quotes because workspace names are case-sensitive and can contain special characters.

  The version specifier is required and can be last, first, live, or the specifier for any existing version in the form version$<num>. For more information, see Versioning for dbt project objects and files.

SET ...

Sets one or more specified properties or parameters to set for the dbt project object:

DEFAULT_ARGS = 'string_literal'

A string that specifies the default dbt command (https://docs.getdbt.com/reference/dbt-commands) and command line options (https://docs.getdbt.com/reference/global-configs/about-global-configs#available-flags) to use if EXECUTE DBT PROJECT specifies no command.

Important

Arguments that you explicitly specify in an EXECUTE DBT PROJECT command overwrite any and all DEFAULT_ARGS specified in the DBT PROJECT definition.

COMMENT = edition_num

Adds a comment or overwrites an existing comment for the dbt project object.

UNSET ...

Unsets one or more specified properties or parameters for the dbt project object, which resets the properties to NULL:

• DEFAULT_ARGS

• COMMENT

To unset multiple properties or parameters with a single ALTER statement, separate each property or parameter with a comma.

When unsetting a property or parameter, specify only the property or parameter name (unless the syntax above indicates that you should specify the value). Specifying the value returns an error.

Access control requirements¶

A role used to execute this SQL command must have at least one of the following privileges at a minimum:

The USAGE privilege on the parent database and schema are required to perform operations on any object in a schema.

Usage notes¶

• Regarding metadata:

  Attention

  Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

Examples¶

The following example updates a Git repository object in Snowflake to fetch the latest code from the Git repository and then updates the contents of the dbt project object by adding a new version:

-- Update the Git repository object to fetch the latest code

ALTER GIT REPOSITORY sales_db.integrations_schema.sales_dbt_git_stage FETCH;

-- Add a new version to the dbt project object based on the updated Git repository object

ALTER DBT PROJECT sales_db.dbt_projects_schema.sales_model
  ADD VERSION
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main/sales_dbt_project';

The following example sets the default arguments of a dbt project object to run on the prod target, which overwrites any previously set default arguments in the project definition:

ALTER DBT PROJECT sales_db.dbt_projects_schema.sales_model
  SET DEFAULT_ARGS = 'run --target prod';