Configuring query comments

dbt injects a SQL comment into the top of the queries that it runs against your database. This comment can be used to attribute SQL statements to specific dbt resources like models and tests. The contents of this comment can be configured in your dbt project.

Default query comments

By default, dbt will add a JSON comment containing the information like the dbt version, profile and target names, and node ids for the resources it runs. In practice, this looks like:

/* {"app": "dbt", "dbt_version": "0.15.0rc2", "profile_name": "debug",
"target_name": "dev", "node_id": "model.dbt2.my_model"} */
create view analytics.analytics.orders as (
select ...
);

Configuring query comments

You can configure the comment that dbt injects into your query by adding a query-comment configuration to your dbt_project.yml file. This configuration should return a string that dbt will wrap in a SQL comment and inject into the header of your query. You can disable query comments by setting the query-comment config to null or leaving it blank.

Static comments

The following example injects a comment that reads /* executed by dbt */ into the header of the SQL queries that dbt runs.

dbt_project.yml
name: my_project
version: 1.0.0
...
query-comment: "executed by dbt"

Example output:

/* executed by dbt */
select ...

Dynamic comments

The following example injects a comment that varies based on the configured user specified in the active dbt target.

dbt_project.yml
name: my_project
version: 1.0.0
...
query-comment: "run by {{ target.user }} in dbt"

Example output:

/* run by drew in dbt */
select ...

Using macros

The query-comment config can reference macros in your dbt project.

macros/comment.sql
{% macro my_comment() %}
dbt {{ dbt_version }}: running {{ node.unique_id }} for target {{ target.name }}
{% endmacro %}
dbt_project.yml
name: my_project
version: 1.0.0
...
query-comment: "{{ my_comment() }}"

Compilation context

The following context variables are available when generating a query comment:

Context VariableDescription
dbt_versionThe version of dbt being used
env_varSee env_var
modulesSee modules
run_started_atWhen the dbt invocation began
invocation_idA unique ID for the dbt invocation
fromjsonSee fromjson
tojsonSee tojson
logSee log
varSee var
targetSee target
connection_nameA string representing the internal name for the connection. This string is generated by dbt.
nodeA dictionary representation of the parsed node object. Use node.unique_id, node.database, node.schema, etc

Example comment

The following example shows a JSON query comment which can be parsed to understand the performance characteristics of your dbt project.

macros/query_comment.sql
{% macro query_comment(node) %}
{%- set comment_dict = {} -%}
{%- do comment_dict.update(
app='dbt',
dbt_version=dbt_version,
profile_name=target.get('profile_name'),
target_name=target.get('target_name'),
) -%}
{%- if node is not none -%}
{%- do comment_dict.update(
file=node.original_file_path,
node_id=node.unique_id,
node_name=node.name,
resource_type=node.resource_type,
package_name=node.package_name,
relation={
"database": node.database,
"schema": node.schema,
"identifier": node.identifier
}
) -%}
{% else %}
{%- do comment_dict.update(node_id='internal') -%}
{%- endif -%}
{% do return(tojson(comment_dict)) %}
{% endmacro %}

Use this macro with:

dbt_project.yml
name: my_project
version: 1.0.0
...
query-comment: "{{ query_comment(node) }}"