EXECUTE DBT PROJECT

Executes the specified dbt project object or the dbt project in a Snowflake workspace using the dbt command and command line options specified.

See also:

CREATE DBT PROJECT, ALTER DBT PROJECT, DESCRIBE DBT PROJECT, DROP DBT PROJECT, SHOW DBT PROJECTS

Syntax

Executes the dbt project object with the specified name.

EXECUTE DBT PROJECT [ IF EXISTS ] <name>
  [ARGS = '[<dbt_command>] [--<dbt_cli_option> <option_value_1> [...]] [...]']
  [PROJECT_ROOT = '<subdirectory_path>']
Copy

Variant syntax

Executes the dbt project that is saved in a workspace with the specified workspace name. The user who owns the workspace must be the user who runs this command variant.

EXECUTE DBT PROJECT [ IF EXISTS ] [FROM WORKSPACE <name>]
  [ARGS = '[<dbt_command>] [--<dbt_cli_option> <option_value_1> [...] [...]]]'
  [PROJECT_ROOT = '<subdirectory_path>']
Copy

Required parameters

<name>

When executing a dbt project object, specifies the name of the dbt project object to execute.

When executing a dbt project by using the FROM WORKSPACE option, specifies the name of the workspace for dbt Projects on Snowflake. The workspace name is always specified in reference to the public schema in the user’s personal database, which is indicated by user$.

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

The following example shows a workspace name reference:

user$.public."My dbt Project Workspace"

Optional parameters

ARGS = '[dbt_command] [--dbt_cli_option option_value_1 [...] [...]]'

Specifies the dbt command and supported command line options to run when the dbt project executes. This is a literal string that must conform to the syntax and requirements of dbt CLI commands.

If no value is specified, the dbt project executes with the dbt command and command line options specified in the dbt project object definition. If you specify dbt CLI options without specifying a dbt command, the dbt run command executes by default.

Important

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

Default: No value

PROJECT_ROOT = 'subdirectory_path'

Specifies the subdirectory path to the dbt_project.yml file within the dbt project object or workspace.

If no value is specified, the dbt project executes with the dbt_project.yml file in the root directory of the dbt project object.

If no dbt_project.yml file exists in the root directory or in the PROJECT_ROOT subdirectory, an error occurs.

Default: No value

Output

Column

Description

0|1 Success

TRUE if the dbt project executed successfully; otherwise, FALSE. If the dbt project fails to execute, an exception message is returned.

EXCEPTION

Any exception message returned by the dbt project execution. If the dbt project executes successfully, the string None is returned.

STDOUT

The standard output returned by the dbt project execution.

OUTPUT_ARCHIVE_URL

The URL of the output archive that contains output files of the dbt project execution. This includes log files and artifacts that dbt writes to the /target directory. For more information, see About dbt artifacts in dbt documentation. Selecting this link directly results in an error; however, you can use this URL to retrieve dbt project files and output. For more information, see Programmatically accessing dbt artifacts and logs.

Access control requirements

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

Privilege

Object

USAGE

dbt project

The USAGE privilege on the parent database and schema are required to perform operations on any object in a 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.

Note

The dbt command specified in EXECUTE DBT PROJECT runs with the privileges of the role specified in the outputs block of the projects profiles.yml file. Operations are further restricted to only those privileges granted to the Snowflake user calling EXECUTE DBT PROJECT. Both the user and the role specified must have the required privileges to use the warehouse, perform operations on the database and schema specified in the project’s profiles.yml file, and perform operations on any other Snowflake objects that the dbt model specifies.

Examples

Default run command with target and models specified

Execute a dbt run targeting the dev profile in the dbt_project.yml file in the root directory of the dbt project object and selecting three models from the project DAG. No run command is explicitly specified and is executed by default.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = '--select simple_customers combined_bookings prepped_data --target dev';
Copy

Explicit test command with target and models specified

Execute a dbt test command targeting the prod profile in the dbt_project.yml file in the root directory of the dbt project object and selecting three models from the project DAG.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = '--select simple_customers combined_bookings prepped_data --target prod';
Copy

Explicit run command with downstream models specified

Execute a dbt run command targeting the dev profile in the dbt_project.yml file and selecting all models downstream of the simple_customers model using the dbt + notation.

EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project
  ARGS = 'run --select simple_customers+ --target dev';
Copy

Default run command specifying a subdirectory project with default run and DEFAULT ARGS from dbt project object definition

For a dbt project object containing subdirectories for three dbt projects, execute a dbt run command for the dbt project in the project2 subdirectory. The run command is assumed, and the command targets the dev profile, which was specified using DEFAULT ARGS in the DBT PROJECT definition.

EXECUTE DBT PROJECT my_database.my_schema.my_parent_dbt_project PROJECT_ROOT = 'project2';
Copy

Run and test dbt projects using production tasks

Create a task for a production dbt target that executes a dbt run command on a six-hour interval. Then create a task that executes the dbt test command after each dbt run task completes. The EXECUTE DBT PROJECT command for each task targets the prod profile in the dbt_project.yml file in the root directory of the dbt project object.

CREATE OR ALTER TASK my_database.my_schema.run_dbt_project
  WAREHOUSE = my_warehouse
  SCHEDULE = '6 hours'
AS
  EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project args='run --target prod';


CREATE OR ALTER TASK change_this.public.test_dbt_project
        WAREHOUSE = my_warehouse
        AFTER run_dbt_project
AS
  EXECUTE DBT PROJECT my_database.my_schema.my_dbt_project args='test --target prod';
Copy
Language: English