# dbt Description Suggestions

### Overview <a href="#overview" id="overview"></a>

The **dbt Description Suggestions** feature enables teams to propose and manage changes to dbt resource descriptions directly from Euno's interface. When you suggest a description change, Euno automatically creates a GitHub pull request with the updated YAML file, allowing your team to review, approve, and merge changes through your standard Git workflow.

This feature bridges the gap between metadata management in Euno and source control in your dbt repository, ensuring that documentation improvements flow seamlessly into your codebase.

{% hint style="info" %}
Note: in order to use this feature you must first enable the [Github](#id-1-github-integration) integration
{% endhint %}

### How It Works <a href="#how-it-works" id="how-it-works"></a>

#### Proposing a Description Change <a href="#proposing-a-description-change" id="proposing-a-description-change"></a>

1. **Navigate to Resource:** Open any dbt resource (model, source, semantic model, etc.) in the Data Model screen
2. **Open Sidepane:** Click on the resource to view its details in the right sidepane
3. **About Tab:** The description section will show a "Propose description" button for eligible resources<br>

   <figure><img src="/files/wPMAAZKk744W3DcPwJwe" alt=""><figcaption></figcaption></figure>
4. **Edit Description:** Click the button to open a markdown editor<br>

   <figure><img src="/files/Gk38YodLsD2UILasQewY" alt=""><figcaption></figcaption></figure>
5. **Submit Proposal:** Review your changes and click "Submit"<br>

   <figure><img src="/files/fFfX0iGYG3fIZ4LrdkBr" alt=""><figcaption></figcaption></figure>

Euno will then:

1. Create a deterministic branch name based on the resource and user (e.g., `euno/dbt-description/dbt_model/customers-a1b2c3d4`)
2. Fetch the current schema YAML file from the repository
3. Update the description field for the specified resource
4. Commit the change to the branch
5. Create a pull request (or update existing PR if one already exists)
6. Post a comment on the PR with the proposed description

#### Pull Request Details <a href="#pull-request-details" id="pull-request-details"></a>

**Branch Naming Convention:**

```
euno/dbt-description/{resource_type}/{sanitized_resource_name}-{user_hash}
```

**PR Title:**

```
Euno Suggestion: Update {resource_type} "{resource_name}" description
```

**PR Body:**

```markdown
This PR was automatically created by Euno on behalf of **{user_email}**.

**Resource:** `{resource_type}` {resource_name}

**Original Description:**
> {original_description or *None*}

**Suggested Description:**
> {new_description}
```

**Commit Message:**

```
Update description for {resource_type} {resource_name}
```

#### Managing Suggestions <a href="#managing-suggestions" id="managing-suggestions"></a>

**Viewing Active Suggestions**

When a suggestion is pending:

* The resource sidepane shows "Proposal pending approval" badge
* A "View PR" link provides direct access to the GitHub pull request
* Hovering shows creation date and status

**Updating a Suggestion**

To update an existing proposal:

1. Click the "Proposal pending approval" badge
2. Edit the description in the markdown editor
3. Submit the updated proposal

Euno will:

* Commit the new changes to the same branch
* Post a new comment on the PR with the updated description
* Preserve the PR history

#### After PR is Merged <a href="#after-pr-is-merged" id="after-pr-is-merged"></a>

Once your team merges the pull request:

1. The resource sidepane shows "Changes approved, waiting for crawl"
2. During the next crawl, Euno detects the updated description
3. The resource metadata is updated in Euno
4. The suggestion status is automatically cleared

#### Supported Resource Types <a href="#supported-resource-types" id="supported-resource-types"></a>

Description suggestions are available for the following dbt resource types:

* **Models, Sources, Seeds, Snapshots** — resource-level and column-level descriptions
* **Semantic Models** — resource-level descriptions, as well as dimension and measure descriptions

For sub-resources (columns, dimensions, measures), Euno resolves the parent resource's repository metadata automatically. Column, dimension, and measure names are matched case-insensitively.

#### dbt Docs Blocks <a href="#dbt-docs-blocks" id="dbt-docs-blocks"></a>

{% hint style="warning" %}
dbt supports defining descriptions in separate `.md` files using [docs blocks](https://docs.getdbt.com/docs/build/documentation#using-docs-blocks) (e.g., `description: '{{ doc("my_doc") }}'`). Euno's description suggestion feature **does not support docs blocks**. Submitting a suggestion for a resource that uses a docs block reference will replace the `{{ doc("...") }}` reference with plain inline text. The docs block `.md` file is not modified.

If your project uses docs blocks, avoid using description suggestions for those resources, or review the PR carefully before merging.
{% endhint %}

### Limitations <a href="#limitations" id="limitations"></a>

* Only supports GitHub (GitLab and Bitbucket not yet supported)
* One active proposal per user per resource
* Column, dimension, and measure descriptions must exist in the same schema file as the parent resource
* Does not support dbt docs blocks — see above


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.euno.ai/using-euno/dbt-description-suggestions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.