From 568b98b413d3bbe5afdbf29c9c3a4993be46634f Mon Sep 17 00:00:00 2001
From: Reuven Gonzales <reuven@karibalabs.co>
Date: Wed, 20 Nov 2024 23:49:52 +0800
Subject: [PATCH] Improve metrics macros docs (#2480)

---
 warehouse/metrics_mesh/README.md | 87 ++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/warehouse/metrics_mesh/README.md b/warehouse/metrics_mesh/README.md
index 7355c1a2c..a2e633a6a 100644
--- a/warehouse/metrics_mesh/README.md
+++ b/warehouse/metrics_mesh/README.md
@@ -63,6 +63,45 @@ Metrics are generated using the tools in `metrics_tools`.
 
 ## Metrics Special Macros
 
+### `@metrics_peer_ref`
+
+Reference a different metrics table that is being generated by the timeseries
+metrics factory. This should only be used if the table dependency is also
+defined in the same factory.
+
+#### Parameters
+
+- `name` - The name of the table dependency
+- `entity_type` - _optional_ - The entity type for the current peer reference.
+  Defaults to the entity type used in the current metric
+- `window` - _optional_ - The size of the table dependency's window. If
+  `time_aggregation` is not set, this and `unit` must be set.
+- `unit` - _optional_ - The unit of the table dependency's window. If
+  `time_aggregation` is not set, this and the `window` must be set.
+- `time_aggregation` - _optional_ - The time aggregation used (one of `daily`,
+  `weekly`, `monthly`). If this is not set then `window` and `unit` must be set.
+
+_NOTE: Optional parameters should use the "kwargs" syntax in sqlmesh dialect.
+This looks like `key := 'value'`_
+
+#### Example
+
+Select star from a dependent table that matches the current rolling window settings:
+
+```sql
+SELECT *
+-- As noted in the docs the `entity_type` is inferred from the settings on this metric
+FROM @metrics_peer_ref(`dep`, window := @rolling_window, unit := @rolling_unit)
+```
+
+Select star from a dependent table that matches the current time aggregation
+settings, but only for the `artifact` entity type.
+
+```sql
+SELECT *
+FROM @metrics_peer_ref(`dep`, entity_type := 'artifact', time_aggregation := @time_aggregation)
+```
+
 ### `@metrics_sample_date`
 
 Derives the correct sample date for a metric based on the metric type (normal
@@ -187,3 +226,51 @@ Usage:
 ```
 @metrics_entity_type_alias(some_column, 'some_{entity_type}_column")
 ```
+
+### `@relative_window_sample_date`
+
+_WARNING: Interface likely to change_
+
+Gets a rolling window sample date relative to the a passed in base date. This is
+intended to allow comparison of multiple rolling intervals to each other. This
+doesn't specifically use the rolling window parameters of a table dependency
+(that will likely change in the future), but is instead just a convenience
+function to calculate the correct dates that would be used to make that rolling
+window comparison. We calculate a relative window's sample date using this
+formula:
+
+```
+$base + INTERVAL $relative_index * $window $unit
+```
+
+_Note: The dollar sign `$` is used here to signify that this is a parameter in the above
+context_
+
+Inherently, this won't, for now, work on custom unit types as the interval must
+be a valid SQL interval type. Also note, the base should almost _always_ be the
+`@metrics_end` date.
+
+#### Parameters
+
+- `base` - The date time to use as the basis for this relative sample date
+  calculation
+- `window` - The rolling window size of the table we'd like to depend on
+- `unit` - The rolling window unit of the table we'd like to depend on
+- `relative_index` - The relative index to the current interval. This allows us
+  to look forward or back a certain number of rolling intervals in an upstream
+  table.
+
+#### Examples
+
+To get the date for the current, the last, and the second to last sample date of
+a 90 day rolling window, you could do the following:
+
+```sql
+SELECT
+  -- Relative index 0. This just becomes 2024-01-01
+  @relative_window_sample_date('2024-01-01', 90, 'day', 0)
+  -- Relative index -1. This becomes 2023-10-03
+  @relative_window_sample_date('2024-01-01', 90, 'day', -1)
+  -- Relative index -2. This becomes 2023-07-05
+  @relative_window_sample_date('2024-01-01', 90, 'day', -2)
+```