docs(#294): recommend exact SUM(h3_cell_area()) over nominal per-cell constant (#295)

H3 cells are not equal-area; the nominal per-resolution constant is a global
average and undercounts region areas by well over 5% at the extremes (~6.6%
for California's res-8 grid). Update the human-facing README and datasets
guide to lead with exact SUM(h3_cell_area(hN,'km^2')) over distinct cells,
demoting the count x constant path to the unscoped-global fallback it is.

Matches h3-guide.md (the app-facing guidance, already correct). The STAC-
description root cause is tracked separately in boettiger-lab/data-workflows#389.

Author: cboettig

README.md

@@ -222,7 +222,7 @@ If every pod's imageID matches the pinned digest, prod is current and consistent
 ## Query Optimization Tips
 
 1. **Always include h0 in joins** - Enables partition pruning for 5-20x speedup
-2. **Use APPROX_COUNT_DISTINCT(h8)** - Fast area calculations with H3 hexagons
+2. **Compute areas with `SUM(h3_cell_area(h8, 'km^2'))`** - Exact per-cell area over distinct cells (H3 cells are not equal-area)
 3. **Filter small tables first** - Create CTEs to reduce join cardinality
 4. **Set THREADS=100** - Parallel S3 reads are I/O bound, not CPU bound
 5. **Enable object cache** - Reduces redundant S3 requests
@@ -233,10 +233,10 @@ See [query-optimization.md](query-optimization.md) for detailed guidance.
 
 All datasets use Uber's [H3 hexagonal grid system](https://h3geo.org) for spatial indexing:
 
-- Resolution 8 (h8): ~0.737 km² per hex
+- Resolution 8 (h8): ~0.74 km² per hex (nominal; true cell area varies ~0.55–0.82 km²)
 - Resolution 0-4 (h0-h4): Coarser resolutions for global analysis
 - Use `h3_cell_to_parent()` to join datasets at different resolutions
-- Use `APPROX_COUNT_DISTINCT(h8) * 0.737327598` to calculate areas in km²
+- Compute areas with `SUM(h3_cell_area(h8, 'km^2'))` over distinct cells — exact at any resolution. Multiplying a hex count by a nominal per-cell constant is a global-average approximation only, suitable for unscoped global aggregates. See [h3-guide.md](h3-guide.md).
 
 ## Testing
 

docs/guide/datasets.md

@@ -34,13 +34,25 @@ All datasets are indexed using [Uber's H3 hexagonal grid system](https://h3geo.o
 
 ### Area calculations
 
+H3 cells are **not** equal-area — true cell area varies with latitude and
+icosahedral distortion (res-8 cells range ~0.55–0.82 km²), so a nominal
+per-resolution constant introduces a systematic error (~6% for California).
+For a region, feature, or per-group area, sum the **exact** per-cell area over
+**distinct** cells:
+
 ```sql
--- Area in km² using H3 hex counts
-SELECT APPROX_COUNT_DISTINCT(h8) * 0.737327598 AS area_km2
-FROM read_parquet('s3://...')
-WHERE ...
+-- Exact area in km² (the proper method)
+SELECT SUM(h3_cell_area(h8, 'km^2')) AS area_km2
+FROM (SELECT DISTINCT h8, h0 FROM read_parquet('s3://...') WHERE ...);
 ```
 
+Only for unscoped global aggregates over millions of cells — where
+materializing every distinct cell would defeat the fast approximate path — fall
+back to multiplying an approximate count by the nominal constant
+(`APPROX_COUNT_DISTINCT(h8) * 0.737327598`, accurate to ~1–2% globally).
+
+See [h3-guide.md](../../h3-guide.md) for the full area guidance.
+
 ### Cross-dataset joins
 
 Always include `h0` in join conditions to enable partition pruning: