Fix ai report docs and allow inheriting watermark for time range resolution by pjain1 · Pull Request #9860 · rilldata/rill

pjain1 · 2026-09-04T10:35:44Z

UI changes

Opening an AI report. Clicking the link in a report email takes you straight to the AI conversation the report produced. Before, it showed an error page.
People without a Rill login can read it. The email link carries a key that lets the recipient view that one conversation without signing in. They see the conversation read-only: no list of other conversations, no share or connect buttons, and the message box is greyed out with a note saying to log in to continue.
Logged-in users can continue the conversation. If you are signed in and open the same link, you see the normal chat. When you type a reply, Rill switches over to your own account first, so the new conversation is yours and can see the same data you can.
The first message reads like a sentence. A report's opening message used to show the machine-readable instructions the report was run with. It now says something like "AI report for requests covering Sep 9 – 10, 2026, compared with Sep 8 – 9, 2026".
Small polish. Hovering a conversation in the left list shows its full name, since long names get cut off.

Checklist:

Covered by tests
Ran it and it works as intended
Reviewed the diff before requesting a review
Checked for unhandled edge cases
Linked the issues it closes
Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
Intend to cherry-pick into the release branch
I'm proud of this work!

…ples The AI resolver has always declared `explore`, `dimensions` and `measures` at the top level of the `ai` block, as decided during review of #8673, but the JSON schema and the docs generated from it still nested them under `context`. Since unknown resolver properties only produce a warning, the documented example silently dropped the explore. Also replaces the `iso_duration`/`iso_offset` examples, which the resolver rejects, with Rill time expressions, and documents the `time_zone` and `where` properties. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

There are correctness risks around backwards compatibility for the previously documented ai.context.* shape and around cache invalidation for explore-derived watermarks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates AI report documentation/schema to reflect the actual resolver properties (notably explore as a top-level field) and extends watermark inheritance so time range expressions can resolve against the latest data when an AI report targets an Explore.

Changes:

Add ResourceWatermark support for explore resources by delegating to the underlying metrics view’s watermark.
Update parser behavior/tests to record an Explore ref for AI reports when data.ai.explore is set.
Align JSON schema + docs examples/fields for AI report configuration (remove deprecated ISO fields, move explore out of context, document time_zone, etc).

File summaries

File	Description
runtime/queries/resource_watermark.go	Add explore watermark resolution via underlying metrics view
runtime/queries/resource_watermark_test.go	Test explore watermark inherits from its metrics view
runtime/parser/schema/project.schema.yaml	Fix AI report schema/docs example: `explore` at top-level; update time_range/comparison_time_range fields
runtime/parser/parser_test.go	Add parser coverage asserting report refs include Explore when `data.ai.explore` is set
runtime/parser/parse_partial_data.go	Add Explore as a dependency ref for AI resolver configs
docs/docs/reference/project-files/reports.md	Update AI report docs to match actual resolver props (no `context.explore`)
docs/docs/reference/project-files/models.md	Sync AI config docs to the updated schema/field set
docs/docs/reference/project-files/alerts.md	Sync AI config docs to the updated schema/field set

Review details

Files reviewed: 8/8 changed files
Comments generated: 2
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

🔵 Needs a closer look

Approval assessments differ, and the AI report example has an unresolved watermark inconsistency.

Review details

Suppressed comments (1)

runtime/parser/schema/project.schema.yaml:2884

The corrected AI report example still omits watermark: inherit, so its latest expressions remain anchored to the scheduled trigger time rather than the explore's data watermark. The report always passes an execution time to the AI resolver, and Executor.ResolveTimeRange replaces the metrics-view watermark with that value; only inherited watermark makes that value data-based. Add watermark: inherit to this example and regenerate the report reference so the example demonstrates the behavior described by this PR.

            explore: my_explore

Files reviewed: 8/8 changed files
Comments generated: 0 new
Review effort level: Balanced

Copilot

🟡 Changes recommended

Reconciler-level watermark inheritance coverage is required, and the schema example should be corrected.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

runtime/parser/schema/project.schema.yaml:2884

This example still omits watermark: inherit. Without it, ReportReconciler keeps the trigger time as the execution watermark (runtime/reconcilers/report.go:421-431), and the AI resolver then uses that value for latest; merely setting explore does not make these ranges data-relative. Add watermark: inherit to the example (and regenerate the reference docs) so it demonstrates the behavior described for explore.

            explore: my_explore

Files reviewed: 7/7 changed files
Comments generated: 1
Review effort level: Balanced

…rk: inherit` Reports already support `watermark: inherit`, which uses the lowest watermark of the report's refs as the execution time so that `latest` in time range expressions means the latest data rather than the trigger time. AI reports could not use it because they had no refs, so the reconciler silently fell back to the trigger time. - Add the `explore` of an AI report as a ref. This also makes the report wait for the explore to reconcile before running. - In the report reconciler, resolve explore refs to their metrics view before querying the watermark. This keeps the `ResourceWatermark` query keyed on the metrics view, whose cache key tracks the underlying data, rather than on the explore, which does not change when data refreshes. - Document the behavior on the `explore` property of the AI resolver. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copilot

🔵 Needs a closer look

The schema example still omits the inheritance setting needed to demonstrate the documented behavior.

Review details

Suppressed comments (1)

runtime/parser/schema/project.schema.yaml:2884

This example still omits the report-level watermark: inherit, so its latest/D expressions continue to use the trigger time rather than the explore's data watermark. Reports default to trigger_time (runtime/parser/parse_report.go:88-99), and metrics-view resolution replaces its timestamp bounds with the report execution time (runtime/metricsview/executor/executor_rewrite_time.go:79-84). Add inheritance here so the corrected example demonstrates the data-based behavior described below.

            explore: my_explore

Files reviewed: 8/8 changed files
Comments generated: 0 new
Review effort level: Balanced

The example uses `latest/D` expressions, so without `watermark: inherit` they resolve against the trigger time rather than the explore's data. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

nishantmonu51

👍 , LGTM.

Opening an AI report failed with "Required parameters are missing" because the report open page only knew canvas and query reports and fed AI reports to the explore query mapper. The runtime already appends `session_id` to the open link, and the UI-side redirect agreed on in #8673 was never added. - Redirect AI reports from the open page to `/-/ai/{session_id}`, forwarding the magic token in creator mode so the shared conversation can be read. - Treat `/-/ai/[conversationId]?token=...` as a public URL page and read the token from the URL there, mirroring report and alert pages, so anonymous recipients can authenticate with the token. - Give anonymous visitors a read-only view of the conversation: hide the conversation sidebar and header actions, and replace the input with a notice asking them to log in. - When a logged-in user continues a shared conversation opened with a magic token, switch the runtime client to their own credentials right before forking, so the fork and its analyses run with their access instead of the token's. - Describe a report's opening message by its explore and time range instead of rendering the analyst agent's raw arguments, which is what showed when a report had no user prompt. - Skip the cookie-authenticated project query in the AI layout on public URL pages; it only feeds the MCP dialog. - On the report detail page, link AI reports to the explore they analyze and hide the export format and row limit, which do not apply. - Add `isAIReportSpec` and resolve the dashboard name from the AI resolver's `explore` property. - Show the full session title as a tooltip on conversation items in the sidebar. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

pjain1 requested a lite review from Copilot September 4, 2026 10:35

Copilot started reviewing on behalf of pjain1 September 4, 2026 10:36 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Comment thread runtime/parser/parse_partial_data.go

Comment thread runtime/queries/resource_watermark.go Outdated

pjain1 requested a balanced review from Copilot September 4, 2026 11:24

Copilot started reviewing on behalf of pjain1 September 4, 2026 11:24 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

pjain1 force-pushed the parag/ai-report-schema-and-watermark branch from a56cde6 to 9b3ad28 Compare September 4, 2026 11:33

pjain1 requested a balanced review from Copilot September 4, 2026 11:33

Copilot started reviewing on behalf of pjain1 September 4, 2026 11:34 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Comment thread runtime/reconcilers/report.go

nishantmonu51 added Type:Bug Something isn't working Area:Time Size:M Medium change: 100-499 lines labels Sep 4, 2026

pjain1 force-pushed the parag/ai-report-schema-and-watermark branch from 9b3ad28 to 2b18a63 Compare September 4, 2026 17:28

pjain1 requested a balanced review from Copilot September 4, 2026 17:28

Copilot started reviewing on behalf of pjain1 September 4, 2026 17:29 View session

Copilot AI reviewed Sep 4, 2026

View reviewed changes

pjain1 requested review from begelundmuller and nishantmonu51 September 7, 2026 05:59

docs: use watermark: inherit in the AI report example

bc0a652

The example uses `latest/D` expressions, so without `watermark: inherit` they resolve against the trigger time rather than the explore's data. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

nishantmonu51 approved these changes Sep 9, 2026

View reviewed changes

dfliess mentioned this pull request Sep 10, 2026

AI report example: explore nested under context: #9849

Open

pjain1 and others added 2 commits September 10, 2026 19:40

use analyst agent as default if no specified

477a7cc

pjain1 requested a review from AdityaHegde September 10, 2026 18:09

Navigation Menu

Uh oh!

Fix ai report docs and allow inheriting watermark for time range resolution - #9860

Fix ai report docs and allow inheriting watermark for time range resolution#9860
pjain1 wants to merge 5 commits into
mainfrom
parag/ai-report-schema-and-watermark

pjain1 commented Sep 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

nishantmonu51 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

pjain1 commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

UI changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Suppressed comments (1)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (1)

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Suppressed comments (1)

Uh oh!

nishantmonu51 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

pjain1 commented Sep 4, 2026 •

edited

Loading