support static data range, rollup priorities

docs/docs/developers/build/metrics-view/rollups.md

@@ -70,6 +70,57 @@ rollups:
       exclude: [total_clicks] # all measures except total_clicks
 ```
 
+### Declaring Coverage with `data_time_range`
+
+By default Rill discovers a rollup's time coverage at query time by running `SELECT min(time), max(time)` against the rollup table. If you'd rather declare coverage statically — to skip the probe, or to scope a rollup to a specific window — set `data_time_range` on the rollup. The value is a [rilltime expression](/reference/time-syntax/time-syntax):
+
+```yaml
+rollups:
+  - model: events_hourly
+    time_grain: hour
+    data_time_range: -1Y to now        # rolling last 12 months
+    dimensions: [publisher, domain]
+    measures: [total_impressions]
+  - model: events_daily_archive
+    time_grain: day
+    data_time_range: -5Y to -1Y        # 1 to 5 years ago
+    dimensions: [publisher, domain]
+    measures: [total_impressions]
+```
+
+A query for last week routes to `events_hourly`; a query 18 months back routes to `events_daily_archive`; a query reaching past 5 years falls back to the base.
+
+You can declare coverage on the metrics view itself the same way — this skips the probe on the base table:
+
+```yaml
+data_time_range: -5Y to now
+```
+
+When `data_time_range` is set, the rilltime expression is resolved against fixed anchors at query time: `now`/`latest`/`watermark` all resolve to the current wallclock, and `earliest` resolves to the zero epoch. So `inf` (a shorthand for `earliest to latest`) declares "all time from zero epoch to now." Mixing declared and undeclared rollups in the same metrics view is fine — each table independently decides whether to probe or to use its declaration.
+
+### Selection Priority and Definition Order
+
+When two rollups have the same time grain and both could answer a query, the **first one declared in the YAML wins**. This is the lever for priority-style routing: list narrower / fewer-row rollups first.
+
+```yaml
+rollups:
+  # Same grain, different dimension sets. Priority is declared by order.
+  - model: events_daily_narrow   # selected for queries that only need publisher
+    time_grain: day
+    dimensions: [publisher]
+    measures: [total_impressions]
+  - model: events_daily_wide     # selected when publisher + domain are queried
+    time_grain: day
+    dimensions: [publisher, domain]
+    measures: [total_impressions]
+  - model: events_daily_wider      # selected when publisher + domain + country are queried
+    time_grain: day
+    dimensions: [publisher, domain, country]
+    measures: [total_impressions]
+```
+
+A query on `publisher` alone is eligible against all three — `events_daily_narrow` wins because it's listed first. A query on `publisher` + `domain` knocks `events_daily_narrow` out of eligibility, so `events_daily_wide` wins.
+
 ### Configuration Reference
 
 - **`model`** (required) — The pre-aggregated table or model.
@@ -78,8 +129,9 @@ rollups:
 - **`database`**, **`database_schema`** (optional) — Override the OLAP database and schema for the rollup table.
 - **`dimensions`** (optional) — Field selector for which base-view dimensions are present in the rollup. Defaults to all.
 - **`measures`** (optional) — Field selector for which base-view measures are present in the rollup. Defaults to all.
+- **`data_time_range`** (optional) — Rilltime expression describing the rollup's time coverage. When set, Rill skips the OLAP `min/max` probe for this rollup and uses the declared bounds for coverage checks.
 
-A metrics view must define a `timeseries` to use rollups. The full schema is documented in the [metrics view reference](/reference/project-files/metrics-views#rollups).
+A metrics view must define a `timeseries` to use rollups. The metrics view itself also accepts a top-level `data_time_range` to declare the base table's coverage. The full schema is documented in the [metrics view reference](/reference/project-files/metrics-views#rollups).
 
 ## How Rollup Selection Works
 
@@ -116,7 +168,7 @@ For each eligible rollup, Rill checks that the rollup actually contains data for
 Among rollups that pass eligibility and coverage:
 
 1. Prefer the **coarsest grain** — fewer rows to scan.
-2. On a tie, prefer the rollup with the **smallest data range** (tightest coverage).
+2. On a tie, prefer the rollup **declared earlier** in the `rollups` list — this is the lever for explicit priority among same-grain rollups.
 
 The base table is used if no rollup is eligible.
 

docs/docs/reference/project-files/metrics-views.md

@@ -60,6 +60,10 @@ _[string]_ - Refers to the timestamp column from your model that will underlie x
 
 _[string]_ - A SQL expression that tells us the max timestamp that the measures are considered valid for. Usually does not need to be overwritten 
 
+### `data_time_range`
+
+_[string]_ - Optional [rilltime](https://docs.rilldata.com/reference/time-syntax/time-syntax) expression describing the base table's time coverage (e.g. `-5Y to now`, `inf`). When set, Rill skips the `min`/`max` OLAP probe for the model/table and uses the declared bounds for coverage checks. 
+
 ### `smallest_time_grain`
 
 _[string]_ - Refers to the smallest time granularity the user is allowed to view. The valid values are: millisecond, second, minute, hour, day, week, month, quarter, year 
@@ -312,6 +316,8 @@ _[array of object]_ - Pre-aggregated rollup tables that can be used to accelerat
 
       - **`exclude`** - _[object]_ - Select all fields except those listed here 
 
+  - **`data_time_range`** - _[string]_ - Optional [rilltime](https://docs.rilldata.com/reference/time-syntax/time-syntax) expression describing the rollup's time coverage (e.g. `-1Y to now`, `-5Y to -1Y`, `inf`). When set, Rill skips the `min`/`max` OLAP probe for this rollup and uses the declared bounds for coverage checks. 
+
 ### `security`
 
 _[object]_ - Defines [security rules and access control policies](/developers/build/metrics-view/security) for resources