Comments¶

Platform (dbtCharts.com)

This page describes dbt Charts Platform, the hosted product at dbtCharts.com. These features are not part of the open source dct engine.

Anyone who is a member of your organization and can view a board can comment on it. Visitors who open a public board without signing in see no comments.

Comment on text¶

Select text inside one chart or one block (a chart's title, an axis label, a legend entry, the board title, a text block) and a chat-bubble icon appears at the end of your selection. Click it, or press Cmd/Ctrl + Alt + M, type your comment, and choose Comment. The words you selected stay highlighted.

A selection that runs across two charts or blocks, or into text that belongs to neither (the render timestamp, the footer), cannot be commented on. dbt Charts says so instead of showing the icon.

Read and reply¶

Hover the highlighted text to see the thread beside it. Click the highlight to pin the card open, then reply, edit your own comments, or resolve the thread. Esc, a click elsewhere, or pinning another thread closes the card. On a touch screen, tap the highlight.

Where two threads cover the same words, the later one is on top. The Comments list tells them apart.

Unread comments¶

A highlight is drawn in an accented tint while its thread has a comment you have not seen: someone else's new thread, a reply, or a reopen since you last looked. Pin the card (click the highlight) and the highlight returns to the usual tint; hovering does not count as reading, and your own comments never make a thread unread for you. The highlight's accessible label ends with "new" while it is unread. Opening a thread by its link also marks it read. dbt Charts does not poll, so a thread you have open learns of a reply when the board next renders or the page reloads.

The Comments list¶

The Comments button in the board menu lists every thread on the board:

Open: threads highlighted on the board. Click one to bring it into view and pin its card.
Resolved: threads someone marked resolved. They are no longer highlighted. Open one to read it or reopen it.
Detached: open threads whose text is no longer on the board, for example because the chart was removed or renamed in git. They keep the quote and the chart or block they were written on.

The author of a thread, or anyone who can edit the board, can resolve and reopen it. Only the author can edit a comment. Nothing is deleted.

Link to a thread¶

Add ?_comment=<thread id> to a board URL to open the board with that thread's card pinned. For a resolved or detached thread, the Comments list opens on it instead.

Comments on a review¶

A review's page has no comment box of its own: you comment on the change itself. Select text in a changed board's Proposed preview, as you would on the board, and the thread is posted from the review. It is still a board thread, so it shows on the board too, labeled "from review" with the review's title, and it stays there after the review merges or closes.

The review page has its own Comments list above the changes: every thread posted from this review, on any of its boards, open or resolved. Threads posted on a board outside the review are not listed there. An open review takes new comments; add ?_comment=<thread id> to the review's URL to open it with that thread pinned.

Request changes¶

Request changes opens a box under the review's actions asking what should change; the note is required. Posting it starts a thread in the review's Comments and marks the review as changes requested, together: a blank note does neither. A review has no text of its own, so the thread is pinned to the first words of the first changed board you can comment on (its title, when it has one). Replies and resolving work as on any thread. A review that changes no board you can comment on, or only boards with no text, has nothing to pin a note to: Request changes is a single button there, which marks the review as changes requested without a note.

Comment on a line of the YAML diff¶

Hover or focus a line in a changed board's YAML changes and a chat-bubble icon appears in its gutter. Click it to select the whole line and open the composer, or select text in the diff by hand. A line of the proposed file (added or unchanged) and a deleted line from the current file are both commentable. The thread is a review thread like any other and its line stays highlighted in the diff. If a later push edits the line, the thread is listed as detached in the review's Comments list. After the review merges, the board lists it as detached too, because the diff it was written on is gone.

Mentions¶

Type @ in a comment, a reply, or an edit to mention someone. The list offers the members of your organization who can view the board, then the organization's teams, then @wizard. Keep typing to narrow it, then pick one; the name goes into the text and the mention is recorded. Typing a name by hand does not mention anyone: pick it from the list.

A mention of a person notifies that person. A mention of a team notifies each member of the team who can view the board, at the moment you post; members who cannot view the board are left out, and joining the team later notifies no one. Someone mentioned both ways gets one notification, and you never notify yourself. A reply also notifies everyone who has written in the thread. Editing a comment notifies only the people you add in that edit; removing a name's text removes its mention.

Two people with the same name appear as @Name (email-name), and a team named like a person as @Name (team). Mention @wizard to ask the Wizard; see Ask Wizard in a comment.

On a review's page, a mention links to the review. Mentions also work from the API and the CLI.

Ask Wizard in a comment¶

Mention @wizard in a comment, a reply, or an edit to ask the Wizard, the same agent as the chat panel, about the text the thread is on. It replies in the thread as Wizard. The reply first reads "Wizard is working"; reload the board to see the answer. The Wizard knows the thread, the words you selected and the chart or block they are in, the board's variable values when you commented, and the branch you commented on. It works with your permissions.

If you can edit the board, the Wizard may change it when you ask, for example "split this by region". It commits to the branch you commented on, like an edit made in the editor. In a project that works in branches, a comment on the main view starts a change branch for you, and the reply names it. The reply says what changed and links to it. Nothing is written to the main branch until the change is merged. To undo a change, revert its commit. If the change removes the words you commented on, the thread moves to Detached on the next load and the reply says so.

If you cannot edit the board, the Wizard answers and says it could not make the change.

You get a notification when the Wizard replies, in the bell and by email. If the Wizard cannot finish, or has not answered after 15 minutes, the reply says so and you can mention it again. If it had already committed a change, the reply names the branch, so check it first. Nobody can edit the Wizard's replies. The Wizard's work counts toward your AI usage like a chat message.

Comment emails¶

Every notification is also emailed, a moment after you post, with the quoted text, the chart or block it is on, the comment, who sent it (and the team it came through), and a link that opens the thread. Choose which ones reach you under Account settings, Profile, Comment emails:

All mails mentions and replies (the default).
Mentions only mails mentions, including team mentions.
Off mails nothing. The bell still lists everything.

A notification for a board you can no longer view is not mailed.

Notifications¶

The bell in the rail's bottom group shows how many notifications you have not opened. Click it to list the 30 most recent, newest first, each with who did what, the board and the quoted text, and an excerpt. Opening one marks it read and takes you to the board with that thread pinned. Mark all read clears the count. A notification for a board you can no longer view stays in the list as "no longer available". The count updates when a page loads, not live.

Highlight colors¶

Highlights use the board's theme. Set style.comments.highlight for the tint of a thread you have seen and style.comments.highlight_new for the tint of an unread thread and of the comment you are writing:

style:
  comments:
    highlight: warning.subtle
    highlight_new: warning.border

Comments API¶

Every operation the comments on a board page offer is an endpoint, so a script or an agent can read what reviewers asked, answer them, and resolve a thread once the board is fixed. The endpoints call the same service as the page and apply the same rules: you can comment on a board you can open, only a thread's author edits it, and its author or a board editor resolves it.

Requests carry a bearer token (see Administer access from the CLI for signing in). A token needs comments:read to read and comments:write to post, reply, edit, resolve, or reopen. Both are used together with dashboards:read: a comment scope adds no access to boards, so a token holding only comments:* sees every board as a 404. Resolving or reopening someone else's thread also needs the board's edit access, which a token only has with dashboards:write. A board you cannot open, or that does not exist, is a 404.

All paths are under /api/orgs/<org>/projects/<project>/boards/<board>/comments, where <board> is the board's slug, such as finance/revenue.

Method and path	What it does	Scope
`GET`	Lists the board's threads, newest first. `?status=open` (the default), `resolved`, or `all`; `?owner=<id>` for one chart or block; `?review=<id>` for the threads posted from one review	`comments:read`
`POST`	Starts a thread: `body`, `owner`, `quote`, `mentions`; `review` posts it from an open review's page, on its change branch	`comments:write`
`GET /<id>`	One thread with its replies, oldest first	`comments:read`
`PATCH /<id>`	Edits a comment's body (its author only): `body`, and `mentions` to replace the comment's mentions	`comments:write`
`POST /<id>/replies`	Replies to a thread: `body`, `mentions`	`comments:write`
`POST /<id>/resolve`	Resolves a thread	`comments:write`
`POST /<id>/reopen`	Reopens a resolved thread	`comments:write`

A thread response carries the anchor (owner, owner_label, quote), detached (the text it was about has left the board), the board's variables and branch when it was posted, the review it was posted from (or null), resolved_at and resolved_by, and its replies. Query-string parameters other than the filters, such as ?region=EU on a post, are recorded as the board's variable values.

Each comment carries author_kind (member or wizard). A Wizard reply also carries wizard_status: working while its body is still empty, then answered or failed. When Wizard changed the board for the reply, change_url is where to see that change. Both are null on a member's comment.

Mentions over the API¶

mentions is a list of user:<email>, team:<slug>, and wizard, the same people and teams the @ list offers (see Mentions; GET /members and GET /teams list the emails and slugs). The body must also contain each one's @Display Name (a team's @Team Name), delimited by spaces or punctuation. A person or team you cannot mention on that board, or a name missing from the body, is a 422 on mentions; nothing is dropped silently. A new wizard mention also needs a token with the dashboards:write and connections:query scopes, because Wizard edits the board and queries its data as you; without both it is a 422 on mentions. A PATCH without mentions leaves the comment's mentions alone. On a PATCH that sends mentions, an id the comment already has is kept without the token check (so a typo fix never trips on a renamed member); a reply is a new comment and checks every id.

From the terminal¶

dct cloud comments wraps these endpoints. Every verb takes --board, plus the usual --org, --project, and --json:

dct cloud comments list --board finance/revenue --status all
dct cloud comments add --board finance/revenue --chart rev \
  --quote "by month" --body "Is this the booked or invoiced total?"
dct cloud comments reply <thread-id> --board finance/revenue --body "Invoiced."
dct cloud comments edit <comment-id> --board finance/revenue --body "Invoiced, net."
dct cloud comments resolve <thread-id> --board finance/revenue
dct cloud comments reopen <thread-id> --board finance/revenue

add, reply, and edit take --mention user:<email> or --mention team:<slug>, once per mention, with the matching @Name in --body. A dct cloud sign-in cannot mention wizard: it carries neither scope a Wizard mention needs.

list and add take --review <id>: the threads of one review, or a new thread posted from it. add takes --chart <id> or --block <path>. For a chart, leaving out --quote anchors the thread to the chart's title; for a block, --quote is required. A quote the board's text does not contain is refused and the server's message is printed. --json prints the thread as the API returns it.

Anchoring a thread without a browser¶

A thread is about a run of text. A client with no page to select from names the owner (a chart id, or title or text for the board's own, or a section's path) and the quote, and the server anchors the thread to the first occurrence of the quote in the owner's text.

A POST without quote anchors to the owner's label: a chart's title.

The server knows the text a board declares: chart titles and subtitles, the board title and text, and section headers. It does not know axis ticks or data labels, which exist only after a render. Section text and headers are matched as authored, so a quote that spells Markdown (**, __, ~~, backticks, link brackets) is refused, and so is a span that crosses markup; quote plain words instead. Single-character emphasis such as *really* is not caught: it anchors, but the highlight never paints, because the page shows no asterisks. A chart's title and subtitle are separate runs of text, so quote from one of them, not across both. A quote it cannot find is refused:

{
  "code": "comment_rejected",
  "message": "The comment was rejected.",
  "field_errors": {"quote": ["quote not found in Revenue by month"]}
}

An empty or over-long body (10,000 characters), a quote over 500 characters, and an owner that is not on the board are refused the same way, with status 422 and the offending field named. An action you may not take on a comment you can see, such as resolving someone else's thread without edit access, is also a 422, naming the rule. The board page answers the same refusal with its standard denial instead; the API can be specific because you can already see the board.