docs: Rolling window calculations without date range, enabled by Tesseract

Author: igorlukanin

docs/pages/guides/recipes/data-modeling/period-over-period.mdx

@@ -17,6 +17,15 @@ _previous period_.
 these `rolling_window` measures and uses them in a calculation, e.g.,
 divides or subtracts them.
 
+<WarningBox>
+
+Tesseract, the [next-generation data modeling engine][link-tesseract],
+provides a more efficient way to calculate [period-over-period changes][link-period-over-period].
+Tesseract is currently in preview. Use the `CUBEJS_TESSERACT_SQL_PLANNER`
+environment variable to enable it.
+
+</WarningBox>
+
 The following data model allows to calculate a month-over-month change of
 some value. `current_month_sum` and `previous_month_sum` measures define
 two rolling windows and the `month_over_month_ratio` measure divides
@@ -89,4 +98,6 @@ Here's the result:
 
 [ref-rolling-window]: /reference/data-model/measures#rolling_window
 [ref-calculated-measure]: /product/data-modeling/overview#4-using-calculated-measures
-[ref-time-dimension-granularity]: /product/apis-integrations/rest-api/query-format#time-dimensions-format
+[ref-time-dimension-granularity]: /product/apis-integrations/rest-api/query-format#time-dimensions-format
+[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine
+[link-period-over-period]: /product/data-modeling/concepts/multi-stage-calculations#prior-date

docs/pages/product/data-modeling/concepts/multi-stage-calculations.mdx

@@ -5,7 +5,8 @@ or arbitrary SQL expressions.
 
 _Multi-stage calculations_ enable data modeling of more sophisticated _multi-stage measures_.
 They are calculated in two or more stages and often involve manipulations on already
-aggregated data.
+aggregated data. Each stage results in one or more [common table expressions][link-cte]
+(CTEs) in the generated SQL query.
 
 <WarningBox>
 
@@ -24,11 +25,79 @@ Please track [this issue](https://github.com/cube-js/cube/issues/8487).
 
 Common uses of multi-stage calculations:
 
+- [Rolling window](#rolling-window) calculations.
 - [Period-to-date](#period-to-date) calculations, e.g., year-to-date (YTD) analysis.
 - [Prior date](#prior-date) calculations, e.g., year-over-year sales growth.
 - [Fixed dimension](#fixed-dimension) calculations, e.g., comparing individual items to a broader dataset or calculating percent of total.
 - [Ranking](#ranking) calculations.
 
+## Rolling window
+
+Rolling window calculations are used to calculate metrics over a moving window of time.
+Use the [`rolling_window` parameter][ref-rolling-window] of a measure to define
+a rolling window.
+
+### Stages
+
+Here's how the rolling window calculation is performed:
+
+- **Date range.** First, the date range for the query is determined.
+If there's a time dimension with a date range filter in the query, it's used.
+Otherwise, the date range is determined by selecting the minimum and maximum
+values for the time dimension.
+
+<WarningBox>
+
+Tesseract enables rolling window calculations without the date range for the time dimension.
+If Tesseract is not used, the date range must be provided. Otherwise, the query would
+fail with the following error: `Time series queries without dateRange aren't supported`.
+
+</WarningBox>
+
+- **Time windows.** Then, the series of time windows is calculated. The size of the
+window is defined by the time dimension granularity and the `trailing` and
+`leading` parameters.
+- **Measure.** Finally, the measure is calculated for each window.
+
+### Example
+
+Data model:
+
+```yaml
+
+cubes:
+  - name: orders
+    sql: >
+      SELECT 1 AS id, '2025-01-01'::TIMESTAMP AS time UNION ALL
+      SELECT 2 AS id, '2025-01-11'::TIMESTAMP AS time UNION ALL
+      SELECT 3 AS id, '2025-01-21'::TIMESTAMP AS time UNION ALL
+      SELECT 4 AS id, '2025-01-31'::TIMESTAMP AS time UNION ALL
+      SELECT 5 AS id, '2025-02-01'::TIMESTAMP AS time UNION ALL
+      SELECT 6 AS id, '2025-02-11'::TIMESTAMP AS time UNION ALL
+      SELECT 7 AS id, '2025-02-21'::TIMESTAMP AS time UNION ALL
+      SELECT 8 AS id, '2025-03-01'::TIMESTAMP AS time UNION ALL
+      SELECT 9 AS id, '2025-03-11'::TIMESTAMP AS time UNION ALL
+      SELECT 10 AS id, '2025-03-21'::TIMESTAMP AS time UNION ALL
+      SELECT 11 AS id, '2025-03-31'::TIMESTAMP AS time UNION ALL
+      SELECT 12 AS id, '2025-04-01'::TIMESTAMP AS time
+
+    dimensions:
+      - name: time
+        sql: time
+        type: time
+ 
+    measures:
+      - name: rolling_count_month
+        sql: id
+        type: count
+        rolling_window:
+          trailing: unbounded
+```
+
+Query and result:
+
+<Screenshot src="https://ucarecdn.com/40179d09-3e10-4ada-8456-1deca6a5035d/" />
+
 ## Period-to-date
 
 Period-to-date calculations can be used to analyze data over different time periods:
@@ -388,4 +457,6 @@ Query and result:
 
 [link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine
 [ref-measures]: /product/data-modeling/concepts#measures
-[ref-dimensions]: /product/data-modeling/concepts#dimensions
+[ref-dimensions]: /product/data-modeling/concepts#dimensions
+[ref-rolling-window]: /reference/data-model/measures#rolling_window
+[link-cte]: https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression

docs/pages/reference/data-model/measures.mdx

@@ -248,28 +248,45 @@ cubes:
 
 ### `rolling_window`
 
-If you want to calculate some metric within a window, for example a week or a
-month, you should use a `rolling_window` parameter. The `trailing` and `leading`
-parameters define window size.
+The `rolling_window` parameter is used to for [rolling window][ref-rolling-window]
+calculations, e.g., to calculate a metric over a moving window of time, e.g. a
+week or a month.
 
 <WarningBox>
 
-`rolling_window` only works for a query where there's a single `timeDimension`
-with a defined date range.
+Rolling window calculations require the query to contain a single time dimension
+with a provided date range. It is used to calculate the minimum and maximum values
+for the series of time windows.
+
+With Tesseract, the [next-generation data modeling engine][link-tesseract],
+rolling window calculations don't require the date range for the time dimension.
+Tesseract is currently in preview. Use the `CUBEJS_TESSERACT_SQL_PLANNER`
+environment variable to enable it.
 
 </WarningBox>
 
-These parameters have a format defined as
-`(-?\d+) (minute|hour|day|week|month|year)`. The `trailing` and `leading`
-parameters can also be set to an `unbounded` value, which means infinite size
-for the corresponding window part. You can define `trailing` and `leading`
-parameters using negative integers.
+#### `offset`
+
+The `offset` parameter is used to specify the starting point of the time window.
+
+You can set the window `offset` parameter to either `start` or `end`, which will
+match the start or end of the window.
+
+By default, the `offset` parameter is set to `end`.
+
+#### `trailing` and `leading`
+
+The `trailing` and `leading` parameters define the size of the time window.
+The `trailing` parameter defines the size of the window part before the `offset` point,
+and the `leading` parameter defines the size of the window part after the `offset` point.
+
+These parameters have a format defined as `(-?\d+) (minute|hour|day|week|month|year)`.
+It means that you can define these parameters using both positive and negative integers.
+
+The `trailing` and `leading` parameters can also be set to `unbounded`,
+which means _infinite size_ for the corresponding window part.
 
-The `trailing` parameter is a window part size before the `offset` point and the
-`leading` parameter is after it. You can set the window `offset` parameter to
-either `start` or `end`, which will match the start or end of the selected date
-range. By default, the `leading` and `trailing` parameters are set to zero and
-`offset` is set to `end`.
+By default, the `leading` and `trailing` parameters are set to zero.
 
 <CodeTabs>
 
@@ -535,4 +552,6 @@ join will be created automatically.
 [ref-drilldowns]: /guides/recipes/data-exploration/drilldowns
 [ref-naming]: /product/data-modeling/syntax#naming
 [ref-playground]: /product/workspace/playground
-[ref-apis]: /product/apis-integrations
+[ref-apis]: /product/apis-integrations
+[ref-rolling-window]: /product/data-modeling/concepts/multi-stage-calculations#rolling-window
+[link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine