From c5c85e8fffbf6788faa581c0cd6d1169f7a6f2a1 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Thu, 5 Feb 2026 22:45:21 +0000
Subject: [PATCH] fix: correct weightCol for percentage change aggregations in
 DataTable docs

- Update example-project total-rows page to use prev_* columns as weightCol
  for percentage change columns (sales_change_pct0, num_orders_change_pct0,
  aov_change_pct0)
- Add tip in DataTable documentation explaining that weightCol should be
  the baseline/previous value when aggregating percentage changes

Co-Authored-By: Caleb Keller <calebmkeller@gmail.com>
---
 sites/docs/pages/components/data/data-table/index.md      | 5 +++++
 .../example-project/src/pages/tables/total-rows/+page.md  | 8 ++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/sites/docs/pages/components/data/data-table/index.md b/sites/docs/pages/components/data/data-table/index.md
index dc1f579fdc..89d7d4e31f 100644
--- a/sites/docs/pages/components/data/data-table/index.md
+++ b/sites/docs/pages/components/data/data-table/index.md
@@ -368,6 +368,11 @@ limit 5
 ```
 </DocTab>
 
+:::tip Weighted Mean for Percentage Changes
+When aggregating percentage changes (e.g., year-over-year growth rates), use `weightCol` to specify the **baseline/previous value** column, not the current value. This ensures the weighted average is calculated correctly, as percentage changes are relative to their original values.
+
+For example, if you have `sales_change_pct` calculated as `(current_sales - previous_sales) / previous_sales`, the `weightCol` should be `previous_sales`.
+:::
 
 
 #### Custom Aggregations Values
diff --git a/sites/example-project/src/pages/tables/total-rows/+page.md b/sites/example-project/src/pages/tables/total-rows/+page.md
index e4bf7f4c9b..0ad2f4f4bc 100644
--- a/sites/example-project/src/pages/tables/total-rows/+page.md
+++ b/sites/example-project/src/pages/tables/total-rows/+page.md
@@ -206,9 +206,9 @@ If no `weightCol` is specified, the result will be identical to the result from
   <Column id=prev_sales_usd0k totalAgg=weightedMean weightCol=sales_usd0k/>
   <Column id=prev_num_orders_num0 totalAgg=weightedMean weightCol=sales_usd0k/>
   <Column id=prev_aov_usd2 totalAgg=weightedMean weightCol=sales_usd0k/>
-  <Column id=sales_change_pct0 totalAgg=weightedMean weightCol=sales_usd0k/>
-  <Column id=num_orders_change_pct0 totalAgg=weightedMean weightCol=sales_usd0k/>
-  <Column id=aov_change_pct0 totalAgg=weightedMean weightCol=sales_usd0k/>
+  <Column id=sales_change_pct0 totalAgg=weightedMean weightCol=prev_sales_usd0k/>
+  <Column id=num_orders_change_pct0 totalAgg=weightedMean weightCol=prev_num_orders_num0/>
+  <Column id=aov_change_pct0 totalAgg=weightedMean weightCol=prev_aov_usd2/>
 </DataTable>
 
 
@@ -317,4 +317,4 @@ SELECT 'Brazil', 'South America', 1609, 0.032, 0.1375, 0.1007, 0.091, -4.5, 80.2
   <Column id=debt_to_gdp totalAgg=mean fmt='0"%"'/>
   <Column id=current_account totalAgg=mean fmt='0.0"%"'/>
   <Column id=population totalAgg=sum fmt='#,##0"M"'/>
-</DataTable>
\ No newline at end of file
+</DataTable>