> For the complete documentation index, see [llms.txt](https://docs.espresso.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.espresso.ai/snowflake-optimizer/proxy-onboarding/dbt-markers.md).

# dbt Markers

dbt Markers lets Espresso make your dbt jobs cheaper while meeting your SLAs.

dbt Markers is a small, open-source dbt package from Espresso. It appends a JSON comment to every SQL statement dbt runs, naming the run and the model, test, seed or snapshot that issued it. It makes no network calls.

Supports dbt-core 1.6 or later and dbt Fusion, on Snowflake.

## Set up with the Espresso MCP server

The [Espresso MCP server](https://docs.espresso.ai/mcp-server.md) can do the setup for you. Connect it to your agent, open your dbt repo, and ask:

> Set up Espresso's dbt Markers in this repo.

The agent edits `packages.yml` and `dbt_project.yml` in each dbt project, keeping any query comment you already have, and tells you to run `dbt deps`. It doesn't run dbt or connect to Snowflake. See [Setting up dbt Markers](https://docs.espresso.ai/mcp-server/onboarding.md#setting-up-dbt-markers) for details.

## Set up by hand in 3 steps

### 1. Add the package to `packages.yml`

Add this entry next to your existing packages:

```yaml
packages:
  - git: "https://github.com/espressocomputing/dbt-markers.git"
    revision: v1.1.0
```

### 2. Add the query comment to `dbt_project.yml`

If the project has no `query-comment` block, add:

```yaml
query-comment:
  comment: "{{ dbt_markers.query_comment(node) }}"
  append: true
```

`append: true` is required. Snowflake drops comments placed before the statement.

If the project already has a `query-comment` block, keep your comment and merge it into dbt Markers' (see below). Don't replace it.

#### Keeping an existing query comment

dbt allows one `query-comment` block per project, and Espresso reads the whole comment as one JSON object. So your comment and dbt Markers' must end up in one object:

* **Your comment is a JSON object**, for example a macro that returns `tojson(...)`. Pass it to dbt Markers as `extra`:

  ```yaml
  query-comment:
    comment: "{{ dbt_markers.query_comment(node, extra=fromjson(my_query_comment(node))) }}"
    append: true
  ```

  If your comment is a fixed JSON string such as `'{"team": "analytics"}'`, write its keys directly: `extra={'team': 'analytics'}`.

  `extra` only adds keys. Keys dbt Markers already writes keep dbt Markers' value, and values that are objects, lists, null or empty strings are dropped. Rename any `node_id`, `node_refs` or `raw_code_hash` key in your comment, since Espresso would read it in place of its own.
* **Your comment is anything else**, such as plain text, or you label runs and models in a Snowflake query tag such as `DBT|PROD|...`. Don't combine the two into one string such as `"{{ my_comment() }} {{ dbt_markers.query_comment(node) }}"`: Espresso can't read it. Contact <support@espresso.ai>.

### 3. Run `dbt deps`

```bash
dbt deps
```

## What it records

* The run: `invocation_id`, the dbt command, start time, dbt version, project and target.
* The node: its unique ID, type, name, schema, materialization, warehouse, tags and dependencies.
* On dbt Cloud: the job, run and environment IDs.

## Run marker

Each run also issues one statement recording dbt's own arguments, such as `--select`:

```sql
select 1 /* {"dbt_markers_run": {"invocation_id": "...", "args": {...}}} */
```

## Privacy

Comments are stored in your Snowflake query history, readable by anyone who can read that history. No credentials are recorded. `--vars` and model `meta` are recorded exactly as given, so keep secrets out of them and use `env_var()` instead.

## FAQ

### Which commands emit a run marker?

Commands that run `on-run-start` hooks, such as `run`, `build`, `test`, `seed` and `snapshot`. `compile`, `ls` and `run-operation` emit nothing.

### Does it conflict with my own `on-run-start` hooks?

No. It runs alongside them.

### How large is the run marker?

About 1.5–3 KB, once per run.

### No comment shows up in query history.

Check that `append: true` is set and that `dbt deps` has run. `SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY` can lag by up to 45 minutes.

### How do I turn it off?

Remove the package, then remove the `query-comment` block, or restore your own comment if you merged one. Then run `dbt deps`.

## Release notes

* **v1.1.0**: Adds the run marker, one `select 1` per run recording dbt's own arguments, so runs launched from Python (for example Prefect or Airflow via `dbtRunner`) keep their selection. To upgrade, change `revision` to `v1.1.0` and run `dbt deps`. Nothing else changes.
* **v1.0.0**: First release.
