xarray_sql 0.3.0__tar.gz → 0.3.1__tar.gz

{xarray_sql-0.3.0 → xarray_sql-0.3.1}/Cargo.lock

@@ -3375,7 +3375,7 @@ checksum = "ea2f10b9bb0928dfb1b42b65e1f9e36f7f54dbdf08457afefb38afcdec4fa2bb"
 
 [[package]]
 name = "xarray_sql"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "arrow",
  "async-stream",

{xarray_sql-0.3.0 → xarray_sql-0.3.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "xarray_sql"
-version = "0.3.0"
+version = "0.3.1"
 authors = ["Alex Merose"]
 edition = "2021"
 exclude = [
@@ -25,7 +25,11 @@ async-trait = "0.1"
 datafusion = { version = "52.0.0" }
 datafusion-ffi = { version = "52.0.0" }
 futures = { version = "0.3" }
-pyo3 = { version = "0.26.0", features = ["extension-module"] }
+# `abi3-py310` builds against CPython's stable ABI, so a single wheel per
+# platform works on all CPython >= 3.10 (matching `requires-python`). This
+# lets the release workflow ship pre-built wheels for every interpreter
+# without compiling per-version, avoiding local rebuilds on install.
+pyo3 = { version = "0.26.0", features = ["extension-module", "abi3-py310"] }
 tokio = { version = "1.46.1", features = ["rt"] }
 
 

{xarray_sql-0.3.0 → xarray_sql-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xarray_sql
-Version: 0.3.0
+Version: 0.3.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
@@ -57,6 +57,57 @@ pip install xarray-sql
 ## What is this?
 
 This is an experiment to provide a SQL interface for array datasets.
+Succinctly, we "pivot" Xarray Datasets to treat them like tables so we can run
+SQL queries against them.
+
+## Quickstart
+
+Open a Dataset, register it as a table with `from_dataset`, compute a
+climatology in SQL, then write the result back to Xarray and plot it:
+
+> **Note:** this example also needs `pooch` and a netCDF backend (for the
+> tutorial download) and `matplotlib` (for the plot):
+> `pip install pooch netCDF4 matplotlib`.
+
+```python
+import xarray as xr
+import xarray_sql as xql
+
+# 4x-daily surface air temperature on a lat/lon grid, 2013-2014.
+ds = xr.tutorial.open_dataset('air_temperature')
+
+ctx = xql.XarrayContext()
+ctx.from_dataset('air', ds, chunks=dict(time=100))
+
+# A climatology — the mean annual cycle — computed in SQL: average air
+# temperature for each month of the year, over all grid cells and years.
+clim = ctx.sql('''
+  SELECT
+    CAST(date_part('month', "time") AS INTEGER) AS month,
+    AVG("air") AS air
+  FROM "air"
+  GROUP BY CAST(date_part('month', "time") AS INTEGER)
+  ORDER BY month
+''')
+
+# Write the SQL result back to an Xarray Dataset. `month` is a derived
+# column, so name it as the dimension; the variable's units are recovered
+# from the registered table. The result is one value per month: air(month).
+clim_ds = clim.to_dataset(dims=["month"])
+
+# Plot the annual cycle as a time series.
+clim_ds["air"].plot()  # in a script, call matplotlib.pyplot.show() to display
+```
+
+That's the round trip — Xarray in, SQL in the middle, Xarray (and a plot) back
+out.
+
+## A bigger example: ARCO-ERA5
+
+The same interface scales to cloud-native datasets with hundreds of variables,
+like [ARCO-ERA5](https://github.com/google-research/arco-era5).
+
+> **Note:** reading from `gs://` requires `gcsfs` (`pip install gcsfs`).
 
 ```python
 import xarray as xr
@@ -148,9 +199,6 @@ ctx.sql('''
 _(A runnable version of this example lives at
 [`perf_tests/era5_temp_profile.py`](perf_tests/era5_temp_profile.py).)_
 
-Succinctly, we "pivot" Xarray Datasets to treat them like tables so we can run
-SQL queries against them. 
-
 ## Why build this?
 
 A few reasons:
@@ -185,6 +233,35 @@ that lets the DB engine translate the underlying Dataset arrays into DataFusion
 Ultimately, the initial insight of the `pivot()` function -- that any ndarray can be
 translated into a 2D table -- underlies this performant query mechanism. 
 
+## Does it work?
+
+Yes. The recurring worry is that the SQL interface is a toy — fine for `SELECT`s,
+but not for the operations geoscience actually runs. So we wrote a suite that
+takes the staples of geospatial and climate analysis — the ones we assume *need*
+an array library — and expresses each one in SQL, then **checks the SQL answer
+against an xarray/array reference** to floating-point tolerance:
+
+* **Spectral indices** (NDVI) — column arithmetic over a real Sentinel-2 scene.
+* **Climatology, anomalies, zonal means** — `GROUP BY` and self-`JOIN` against
+  the 0.25° **ARCO-ERA5** archive registered as a lazy table. Each query is
+  bounded to a small window (a few days over a region) and reads only that
+  slice — the point is that you can aim a query at a multi-decade archive and
+  pay only for the data it asks for, not that the query scans the whole record.
+* **Forecast skill** — scoring the **Pangu-Weather** and **GraphCast** ML models
+  against ERA5 (WeatherBench 2) as a `JOIN` on `valid_time = init + lead`; it
+  reproduces the published result that GraphCast beats Pangu at every lead.
+* **Raster × vector zonal stats** — a range `JOIN` of the ERA5 grid against a
+  table of regions.
+* **Reprojection and regridding** — a scalar PROJ UDF (validated against Earth
+  Engine's own geodesy via [Xee](https://github.com/google/Xee)) and a
+  sparse-weight-table `JOIN` (regridding real SRTM terrain).
+
+Every case matches its array reference. The headline finding: these operations
+are not really "array" operations at all — they are `GROUP BY`, `JOIN`, window
+functions, and `CASE` in disguise, and a query engine runs them at scale. See
+[`benchmarks/geospatial/`](benchmarks/geospatial/) and the write-up,
+[Geospatial operations are relational operations](docs/geospatial.md).
+
 ## Why does this work?
 
 Underneath Xarray, Dask, and Pandas, there are NumPy arrays. These are paged in

{xarray_sql-0.3.0 → xarray_sql-0.3.1}/README.md

@@ -14,6 +14,57 @@ pip install xarray-sql
 ## What is this?
 
 This is an experiment to provide a SQL interface for array datasets.
+Succinctly, we "pivot" Xarray Datasets to treat them like tables so we can run
+SQL queries against them.
+
+## Quickstart
+
+Open a Dataset, register it as a table with `from_dataset`, compute a
+climatology in SQL, then write the result back to Xarray and plot it:
+
+> **Note:** this example also needs `pooch` and a netCDF backend (for the
+> tutorial download) and `matplotlib` (for the plot):
+> `pip install pooch netCDF4 matplotlib`.
+
+```python
+import xarray as xr
+import xarray_sql as xql
+
+# 4x-daily surface air temperature on a lat/lon grid, 2013-2014.
+ds = xr.tutorial.open_dataset('air_temperature')
+
+ctx = xql.XarrayContext()
+ctx.from_dataset('air', ds, chunks=dict(time=100))
+
+# A climatology — the mean annual cycle — computed in SQL: average air
+# temperature for each month of the year, over all grid cells and years.
+clim = ctx.sql('''
+  SELECT
+    CAST(date_part('month', "time") AS INTEGER) AS month,
+    AVG("air") AS air
+  FROM "air"
+  GROUP BY CAST(date_part('month', "time") AS INTEGER)
+  ORDER BY month
+''')
+
+# Write the SQL result back to an Xarray Dataset. `month` is a derived
+# column, so name it as the dimension; the variable's units are recovered
+# from the registered table. The result is one value per month: air(month).
+clim_ds = clim.to_dataset(dims=["month"])
+
+# Plot the annual cycle as a time series.
+clim_ds["air"].plot()  # in a script, call matplotlib.pyplot.show() to display
+```
+
+That's the round trip — Xarray in, SQL in the middle, Xarray (and a plot) back
+out.
+
+## A bigger example: ARCO-ERA5
+
+The same interface scales to cloud-native datasets with hundreds of variables,
+like [ARCO-ERA5](https://github.com/google-research/arco-era5).
+
+> **Note:** reading from `gs://` requires `gcsfs` (`pip install gcsfs`).
 
 ```python
 import xarray as xr
@@ -105,9 +156,6 @@ ctx.sql('''
 _(A runnable version of this example lives at
 [`perf_tests/era5_temp_profile.py`](perf_tests/era5_temp_profile.py).)_
 
-Succinctly, we "pivot" Xarray Datasets to treat them like tables so we can run
-SQL queries against them. 
-
 ## Why build this?
 
 A few reasons:
@@ -142,6 +190,35 @@ that lets the DB engine translate the underlying Dataset arrays into DataFusion
 Ultimately, the initial insight of the `pivot()` function -- that any ndarray can be
 translated into a 2D table -- underlies this performant query mechanism. 
 
+## Does it work?
+
+Yes. The recurring worry is that the SQL interface is a toy — fine for `SELECT`s,
+but not for the operations geoscience actually runs. So we wrote a suite that
+takes the staples of geospatial and climate analysis — the ones we assume *need*
+an array library — and expresses each one in SQL, then **checks the SQL answer
+against an xarray/array reference** to floating-point tolerance:
+
+* **Spectral indices** (NDVI) — column arithmetic over a real Sentinel-2 scene.
+* **Climatology, anomalies, zonal means** — `GROUP BY` and self-`JOIN` against
+  the 0.25° **ARCO-ERA5** archive registered as a lazy table. Each query is
+  bounded to a small window (a few days over a region) and reads only that
+  slice — the point is that you can aim a query at a multi-decade archive and
+  pay only for the data it asks for, not that the query scans the whole record.
+* **Forecast skill** — scoring the **Pangu-Weather** and **GraphCast** ML models
+  against ERA5 (WeatherBench 2) as a `JOIN` on `valid_time = init + lead`; it
+  reproduces the published result that GraphCast beats Pangu at every lead.
+* **Raster × vector zonal stats** — a range `JOIN` of the ERA5 grid against a
+  table of regions.
+* **Reprojection and regridding** — a scalar PROJ UDF (validated against Earth
+  Engine's own geodesy via [Xee](https://github.com/google/Xee)) and a
+  sparse-weight-table `JOIN` (regridding real SRTM terrain).
+
+Every case matches its array reference. The headline finding: these operations
+are not really "array" operations at all — they are `GROUP BY`, `JOIN`, window
+functions, and `CASE` in disguise, and a query engine runs them at scale. See
+[`benchmarks/geospatial/`](benchmarks/geospatial/) and the write-up,
+[Geospatial operations are relational operations](docs/geospatial.md).
+
 ## Why does this work?
 
 Underneath Xarray, Dask, and Pandas, there are NumPy arrays. These are paged in

xarray_sql-0.3.1/benchmarks/geospatial/01_ndvi.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "xarray-sql",
+#   "xarray",
+#   "aiohttp",
+#   "requests",
+#   "pystac-client",
+#   "zarr>=3",
+#   "numpy",
+# ]
+#
+# [tool.uv.sources]
+# xarray-sql = { path = "../../", editable = true }
+# ///
+"""NDVI — "apply_ufunc over a raster" is just column arithmetic.
+
+The Normalized Difference Vegetation Index is the workhorse of optical remote
+sensing: ``NDVI = (NIR - Red) / (NIR + Red)``, computed per pixel. The array
+paradigm reaches for ``xarray.apply_ufunc`` (the coiled/benchmarks #1545
+"vectorized operations" case) to broadcast this over a whole scene.
+
+But a per-pixel formula over two bands is just *column arithmetic over two
+columns*::
+
+    SELECT x, y, (nir - red) / (nir + red) AS ndvi
+    FROM scene
+    ORDER BY y, x
+
+Each pixel is one row; the ufunc is the SELECT expression. Invalid pixels are
+already NaN (xarray decodes the band's ``_FillValue`` on open), and NaN
+propagates through the arithmetic on both sides — so the masking is free, no
+``CASE`` required.
+
+Dataset: a real Sentinel-2 L2A scene in **Zarr** from the ESA EOPF sample
+service, discovered with ``pystac-client`` and opened the canonical way with
+``xarray`` — ``xr.open_datatree`` yields the reflectance bands (B04=red,
+B08=NIR at 10 m) already scaled to reflectance and carrying their ``x``/``y``
+coordinates. We read one window so the case stays bounded. Requires network;
+skips cleanly if the service is offline.
+"""
+
+from __future__ import annotations
+
+import xarray as xr
+
+import xarray_sql as xql
+
+from _harness import (
+    CaseSkipped,
+    assert_grid_close,
+    measured,
+    run_case,
+    show_result,
+    show_sql,
+)
+
+# EOPF sample-service STAC catalog; an agricultural AOI near Torino, Italy, in
+# early May (peak spring growth). The search is deterministic — it resolves to
+# a specific archived Sentinel-2 product.
+_STAC = "https://stac.core.eopf.eodc.eu"
+_BBOX = [7.2, 44.5, 7.4, 44.7]
+_DATETIME = "2025-04-25/2025-05-05"
+
+# A 1024×1024 (~105 km²) window over vegetated valley floor.
+_Y0, _X0, _N = 4_000, 6_000, 1_024
+
+
+def _load_scene() -> tuple[xr.Dataset, str]:
+    """Discover a Sentinel-2 L2A product and open its 10 m red/NIR bands.
+
+    Idiomatic end to end: ``pystac-client`` finds the product, ``open_datatree``
+    opens the hierarchical EOPF Zarr, and the ``reflectance/r10m`` node already
+    carries B04/B08 scaled to reflectance (nodata decoded to NaN) with
+    ``x``/``y`` coordinates — no manual scaling or coordinate reconstruction.
+    """
+    try:
+        from pystac_client import Client
+
+        catalog = Client.open(_STAC)
+        search = catalog.search(
+            collections=["sentinel-2-l2a"],
+            bbox=_BBOX,
+            datetime=_DATETIME,
+            max_items=1,
+        )
+        item = next(search.items())
+        tree = xr.open_datatree(
+            item.assets["product"].href, engine="zarr", chunks={}
+        )
+    except StopIteration as exc:
+        raise CaseSkipped("no Sentinel-2 product found for the query") from exc
+    except Exception as exc:  # noqa: BLE001 — any failure → skip, not crash
+        raise CaseSkipped(f"EOPF Sentinel-2 unavailable ({exc})") from exc
+
+    r10m = tree["measurements/reflectance/r10m"].to_dataset()
+    scene = (
+        r10m[["b04", "b08"]]
+        .rename(b04="red", b08="nir")
+        .isel(y=slice(_Y0, _Y0 + _N), x=slice(_X0, _X0 + _N))
+    )
+    return scene, item.id
+
+
+def main() -> None:
+    scene, item_id = _load_scene()
+    n = scene.sizes["y"] * scene.sizes["x"]
+    print(f"  Sentinel-2 L2A {item_id}")
+    print(
+        f"  scene window: {dict(scene.sizes)}  ({n:,} pixels, B04=red/B08=NIR)"
+    )
+
+    ctx = xql.XarrayContext()
+    ctx.from_dataset("scene", scene, chunks={"y": 256, "x": 256})
+
+    sql = """
+        SELECT x, y, (nir - red) / (nir + red) AS ndvi
+        FROM scene
+        ORDER BY y, x
+    """
+    show_sql(sql)
+
+    for _ in measured("SQL NDVI"):
+        got = ctx.sql(sql).to_dataset(dims=["y", "x"]).ndvi
+
+    # Array reference: the same formula in pure xarray. ``.compute()`` reads the
+    # window and evaluates it here (the scene is lazy), so this measures the same
+    # read-and-compute the SQL side does — not just graph construction.
+    for _ in measured("xarray reference"):
+        ref = ((scene.nir - scene.red) / (scene.nir + scene.red)).compute()
+
+    # Compare the xarray way — aligned by coordinate label, so the ORDER BY
+    # above is enough and neither side needs an explicit sort.
+    assert_grid_close("NDVI (per-pixel)", got, ref, rtol=1e-6)
+
+    show_result(got)
+
+    valid = ref.notnull()
+    print(
+        f"\n  NDVI over {int(valid.sum()):,} valid pixels: "
+        f"min {float(ref.min()):.3f}, "
+        f"mean {float(ref.mean()):.3f}, "
+        f"max {float(ref.max()):.3f}"
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_case(main, "NDVI: per-pixel column arithmetic"))

xarray_sql-0.3.1/benchmarks/geospatial/02_climatology.py

@@ -0,0 +1,137 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "xarray-sql",
+#   "xarray",
+#   "gcsfs",
+#   "zarr>=3",
+# ]
+#
+# [tool.uv.sources]
+# xarray-sql = { path = "../../", editable = true }
+# ///
+"""Diurnal climatology — the "rechunk + grouped reduction" that is a GROUP BY.
+
+A *climatology* is the average value for each time-of-cycle, computed
+independently at every location: "what is the typical temperature here at
+06:00?" In the array paradigm (and in the coiled/benchmarks #1545 write-up)
+this is the canonical painful workload — load native Zarr chunks, *rechunk* to
+put all of time in one chunk ("pencils"), run a grouped reduction over the
+calendar, then rechunk back to "pancakes" for output.
+
+The rechunking exists only to serve the array layout. The *operation* is::
+
+    SELECT latitude, longitude, hour_of_day, AVG("2m_temperature")
+    GROUP BY latitude, longitude, hour_of_day
+
+Group by location and time-of-cycle, average the rest — the same answer as
+``da.groupby("time.hour").mean()``. ERA5 is hourly, so grouping by hour of day
+gives a clean 24-bin **diurnal cycle**, one sample per day in the window.
+
+We register the full ARCO-ERA5 archive as a lazy table, but the climatology here
+is computed over a *bounded window* — a few summer days over a CONUS-ish box. The
+``WHERE`` prunes the read, so the query touches only ``2m_temperature`` over that
+window and never scans the rest of the archive. The point is not that we reduce
+the whole record; it is that you can aim a query at a multi-decade archive and pay
+only for the slice it asks for.
+"""
+
+from __future__ import annotations
+
+import datetime
+
+import xarray as xr
+
+import xarray_sql as xql
+
+from _harness import (
+    CaseSkipped,
+    assert_grid_close,
+    measured,
+    run_case,
+    show_result,
+    show_sql,
+    timed,
+)
+
+_URL = "gs://gcp-public-data-arco-era5/ar/full_37-1h-0p25deg-chunk-1.zarr-v3"
+# A few days over a CONUS-ish box (ERA5 latitude descends; lon is 0–360°E).
+_START, _END = datetime.datetime(2020, 6, 1), datetime.datetime(2020, 6, 3, 23)
+_LAT_N, _LAT_S = 50.0, 25.0
+_LON_W, _LON_E = 235.0, 290.0
+_PARAMS = {
+    "start": _START,
+    "end": _END,
+    "lat_s": _LAT_S,
+    "lat_n": _LAT_N,
+    "lon_w": _LON_W,
+    "lon_e": _LON_E,
+}
+
+
+def main() -> None:
+    # Open the full ARCO-ERA5 archive lazily — no data is read here. ERA5 mixes
+    # surface (time, lat, lon) and atmospheric (… level …) variables, so register
+    # it as two tables under an ``era5`` schema; the query below touches only the
+    # surface table's 2m_temperature.
+    try:
+        import gcsfs  # noqa: F401 — required by the gs:// protocol
+
+        ds = xr.open_zarr(_URL, chunks=None, storage_options={"token": "anon"})
+    except Exception as exc:  # noqa: BLE001 — any failure → skip, not crash
+        raise CaseSkipped(f"ARCO-ERA5 unavailable ({exc})") from exc
+
+    ctx = xql.XarrayContext()
+    with timed("register full ERA5 (lazy)"):
+        ctx.from_dataset(
+            "era5",
+            ds,
+            chunks={"time": 6},
+            table_names={
+                ("time", "latitude", "longitude"): "surface",
+                ("time", "level", "latitude", "longitude"): "atmosphere",
+            },
+        )
+
+    sql = """
+        SELECT latitude,
+               longitude,
+               date_part('hour', time) AS hour,
+               AVG("2m_temperature") - 273.15 AS clim_c
+        FROM era5.surface
+        WHERE time      BETWEEN $start AND $end
+          AND latitude  BETWEEN $lat_s AND $lat_n
+          AND longitude BETWEEN $lon_w AND $lon_e
+        GROUP BY latitude, longitude, date_part('hour', time)
+        ORDER BY latitude DESC, longitude, hour
+    """
+    show_sql(sql)
+
+    # A climatology is a gridded product: round-trip the result back to an
+    # xarray Dataset keyed by (latitude, longitude, hour) — how it is used.
+    for _ in measured("SQL diurnal climatology (lazy read)"):
+        got = ctx.sql(sql, param_values=_PARAMS).to_dataset(
+            dims=["latitude", "longitude", "hour"]
+        )
+
+    # Array reference: the textbook groupby-over-the-cycle reduction, in °C —
+    # the same lazy window, materialized only on demand.
+    for _ in measured("xarray reference"):
+        window = ds["2m_temperature"].sel(
+            time=slice(_START, _END),
+            latitude=slice(_LAT_N, _LAT_S),
+            longitude=slice(_LON_W, _LON_E),
+        )
+        ref = window.groupby("time.hour").mean("time") - 273.15
+
+    assert_grid_close(
+        "diurnal climatology (°C)", got.clim_c, ref, rtol=1e-4, atol=1e-2
+    )
+
+    show_result(got)
+
+
+if __name__ == "__main__":
+    raise SystemExit(
+        run_case(main, "Climatology: GROUP BY lat, lon, hour (ARCO-ERA5)")
+    )

xarray_sql-0.3.1/benchmarks/geospatial/03_zonal_mean.py

@@ -0,0 +1,132 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#   "xarray-sql",
+#   "xarray",
+#   "gcsfs",
+#   "zarr>=3",
+# ]
+#
+# [tool.uv.sources]
+# xarray-sql = { path = "../../", editable = true }
+# ///
+"""Zonal mean — the array reduction that is secretly a GROUP BY.
+
+A *zonal mean* averages a field around each circle of latitude (over all
+longitudes, and here over a day of hours too), collapsing a 3-D field to a 1-D
+profile of value-vs-latitude — the classic pole-to-pole temperature curve. In
+the array paradigm this is ``da.mean(dim=["longitude", "time"])``, a reduction
+over two axes.
+
+Relationally it is nothing more than::
+
+    SELECT latitude, AVG("2m_temperature") GROUP BY latitude
+
+The "axes" we reduce over are just the columns we *don't* group by. Same answer,
+and the SQL reads like the plain-English definition of a zonal mean.
+
+Dataset: the full **ARCO-ERA5** archive (0.25° global, 1.3M hourly timesteps).
+The table is the whole reanalysis; ``WHERE time …`` prunes it to one day, and
+the GROUP BY produces a 721-point global temperature profile.
+"""
+
+from __future__ import annotations
+
+import datetime
+
+import xarray as xr
+
+import xarray_sql as xql
+
+from _harness import (
+    CaseSkipped,
+    assert_grid_close,
+    measured,
+    run_case,
+    show_result,
+    show_sql,
+    timed,
+)
+
+_URL = "gs://gcp-public-data-arco-era5/ar/full_37-1h-0p25deg-chunk-1.zarr-v3"
+# One day of hourly data, global; the WHERE below prunes ERA5 to this window.
+_DAY = "2020-06-01"
+_START, _END = (
+    datetime.datetime(2020, 6, 1, 0),
+    datetime.datetime(2020, 6, 1, 23),
+)
+
+
+def main() -> None:
+    # Open the full ARCO-ERA5 archive (lazy, dask off) — no slicing here; the
+    # SQL WHERE clause prunes it to the window we ask for.
+    try:
+        import gcsfs  # noqa: F401 — required by the gs:// protocol
+
+        ds = xr.open_zarr(_URL, chunks=None, storage_options={"token": "anon"})
+    except Exception as exc:  # noqa: BLE001 — any failure → skip, not crash
+        raise CaseSkipped(f"ARCO-ERA5 unavailable ({exc})") from exc
+
+    print(
+        f"  ARCO-ERA5: {ds.sizes['time']:,} hourly timesteps, "
+        f"{ds.sizes['latitude']}×{ds.sizes['longitude']} grid, "
+        f"{len(ds.data_vars)} variables (no pre-slicing)"
+    )
+
+    # ERA5 mixes surface (time, lat, lon) and atmospheric (… level …) variables,
+    # so register it as two tables under an ``era5`` schema.
+    ctx = xql.XarrayContext()
+    with timed("register full ERA5"):
+        ctx.from_dataset(
+            "era5",
+            ds,
+            chunks={"time": 6},
+            table_names={
+                ("time", "latitude", "longitude"): "surface",
+                ("time", "level", "latitude", "longitude"): "atmosphere",
+            },
+        )
+
+    # Pass the day's bounds as query parameters; the query still reads only that
+    # one day out of the whole archive.
+    sql = """
+        SELECT latitude,
+               AVG("2m_temperature") - 273.15 AS air_mean_c
+        FROM era5.surface
+        WHERE time BETWEEN $start AND $end
+        GROUP BY latitude
+        ORDER BY latitude DESC
+    """
+    show_sql(sql)
+
+    # Round-trip the profile back to an xarray Dataset keyed by latitude.
+    for _ in measured("SQL zonal mean (reads one day)"):
+        got = ctx.sql(
+            sql, param_values={"start": _START, "end": _END}
+        ).to_dataset(dims=["latitude"])
+
+    # Array reference: reduce the same day over the two un-grouped axes.
+    for _ in measured("xarray reference"):
+        ref = (
+            ds["2m_temperature"].sel(time=_DAY).mean(["longitude", "time"])
+            - 273.15
+        )
+
+    assert_grid_close(
+        "zonal mean (2m_temp vs latitude, °C)",
+        got.air_mean_c,
+        ref,
+        rtol=1e-4,
+        atol=1e-3,
+    )
+
+    show_result(got)
+
+    print("\n  Global temperature profile (every 72nd parallel, °C):")
+    print(got.air_mean_c.isel(latitude=slice(None, None, 72)).to_series())
+
+
+if __name__ == "__main__":
+    raise SystemExit(
+        run_case(main, "Zonal mean: GROUP BY latitude (ARCO-ERA5)")
+    )