Categories:: Information Schema , Table functions

DBT_PROJECT_EXECUTION_HISTORY¶

Returns the execution history of dbt Projects on Snowflake.

Call this function to get metadata and results from past dbt Project executions within seven days of the current time. Optionally, specify the values to filter the results by.

Use this function with the following system functions to access dbt artifacts and logs programmatically:

For more information, see Access dbt artifacts and logs programmatically.

See also:: CREATE DBT PROJECT, EXECUTE DBT PROJECT

Syntax¶

DBT_PROJECT_EXECUTION_HISTORY (
  [ OBJECT_NAME => '<name>' ]
  [ , OBJECT_TYPE = { WORKSPACE | DBT PROJECT }]
  [ , START_TIME_RANGE_START => <start_time> ]
  [ , START_TIME_RANGE_END => <end_time>  ]
  [ , RESULT_LIMIT = <integer> ]
  [ , COMMAND = <dbt_command> ]
  [ , USER_NAME = <user_name> ]
  [ , DATABASE = <db_name> ]
  [ , SCHEMA = <schema_name> ]
)

Copy

Arguments¶

OBJECT_NAME = <name>

Name of the workspace or dbt project that the run belongs to.

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

OBJECT_TYPE = { WORKSPACE | DBT PROJECT }

The type of the object, WORKSPACE or DBT PROJECT, the run belongs to.

START_TIME_RANGE_START | START_TIME_RANGE_END = timestamp

Timestamp to filter a range of dbt project runs.

RESULT_LIMIT = integer

An integer specifying the maximum number of rows returned by the function, from 1 - 10,000 inclusive.

Default: 100

COMMAND = dbt_command

Specifies the dbt command (https://docs.getdbt.com/reference/dbt-commands) used to execute the dbt project.

USER_NAME = user_name

Name of the user that initiated the dbt project object run.

DATABASE = db_name

Return only records for the specified database.

SCHEMA = schema_name

Return only records for the specified schema.

Output¶

The function returns the following columns.

To view these columns, you must use a role with the MONITOR privilege.

Column Name	Data Type	Description
QUERY_ID	TEXT	ID of the query.
QUERY_START_TIME	TIMESTAMP_LTZ	The time the query started.
QUERY_END_TIME	TIMESTAMP_LTZ	The time the query ended.
USER_NAME	TEXT	The user that created the dbt Project.
OBJECT_NAME	TEXT	Name of the workspace or dbt Project the run belonged to.
OBJECT_TYPE	TEXT	Type of object, such as WORKSPACE or DBT PROJECT.
DATABASE_NAME	TEXT	Database of the object.
SCHEMA_NAME	TEXT	Schema of the object.
COMMAND	TEXT	The command that was run for the object.
ARGS	TEXT	The arguments that were used in the run for the object.
ERROR_CODE	NUMBER	If applicable, the error code for the run.
ERROR_MESSAGE	TEXT	If applicable, error message stating why the run failed.
WAREHOUSE	TEXT	Warehouse used for the object.
STATE	TEXT	State of run, such as HANDLED_ERROR or SUCCESS.

Access control requirements¶

This table function includes only runs from workspaces and dbt Projects in which you have the following privileges:

OWNERSHIP or USAGE on workspaces
OWNERSHIP, USAGE, or MONITOR on dbt Projects

Usage notes¶

Use the exact dbt Project name (case-sensitive if created with quotes). If no row matches (wrong dbt Project name or no runs yet), you might get an Inputs may not be null. error.

Examples¶

For examples of using the DBT_PROJECT_EXECUTION_HISTORY table function, see Access dbt artifacts and logs programmatically.