docs: add quickstart and note gcsfs requirement (#188)

- Add a short, dependency-light Quickstart (air_temperature + MAX) near
the top of the README so the first example is fast to read and run, and
  demote the heavy ARCO-ERA5 walkthrough to 'A bigger example'.
- Note that the gs:// ARCO-ERA5 example requires gcsfs, in both the
  README and docs/examples.md.

Closes #184
Closes #185


```python
import xarray as xr
import xarray_sql as xql

ds = xr.tutorial.open_dataset('air_temperature')

ctx = xql.XarrayContext()
ctx.from_dataset('air', ds, chunks=dict(time=100))

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
''')

# Option 1: a flat pandas DataFrame.
clim.to_pandas().head()

# Option 2: round-trip back to an Xarray Dataset and plot the annual cycle as
# a time series. `month` is a derived column, so name it as the dimension; the
# variable's units are recovered from the registered table.
clim_ds = clim.to_dataset(dims=["month"])
clim_ds["air"].plot()
```

<img width="600" height="429" alt="image"
src="https://github.com/user-attachments/assets/eaeca35b-ad8b-4ce5-94b3-a421a0dbd29a"
/>

Author: ahuang11

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:

docs/examples.md

@@ -1,25 +1,43 @@
 # Examples
 
+A query result can be consumed two ways: as a flat pandas DataFrame
+(`to_pandas`) or written back to an Xarray Dataset (`to_dataset`). This computes
+a climatology — the mean annual cycle, one value per month of the year — and
+shows both.
+
+> **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
 
 ds = xr.tutorial.open_dataset('air_temperature')
 
 ctx = xql.XarrayContext()
-ctx.from_dataset('air', ds, chunks=dict(time=24))
+ctx.from_dataset('air', ds, chunks=dict(time=100))
 
-result = ctx.sql('''
+clim = ctx.sql('''
   SELECT
-    "lat", "lon", AVG("air") as air_avg
+    CAST(date_part('month', "time") AS INTEGER) AS month,
+    AVG("air") AS air
   FROM
     "air"
   GROUP BY
-   "lat", "lon"
+    CAST(date_part('month', "time") AS INTEGER)
+  ORDER BY
+    month
 ''')
 
-df = result.to_pandas()
-df.head()
+# Option 1: a flat pandas DataFrame.
+clim.to_pandas().head()
+
+# Option 2: round-trip back to an Xarray Dataset and plot the annual cycle as
+# a time series. `month` is a derived column, so name it as the dimension; the
+# variable's units are recovered from the registered table.
+clim_ds = clim.to_dataset(dims=["month"])
+clim_ds["air"].plot()
 ```
 
 ## Mixed-dimension datasets: ARCO-ERA5
@@ -35,6 +53,8 @@ Open a year of ARCO-ERA5 and let SQL `WHERE` clauses do the filtering — the
 library prunes time partitions and pushes dimension-column filters down. Use
 the `table_names` kwarg to give each dimension group a friendly name:
 
+> **Note:** reading from `gs://` requires `gcsfs` (`pip install gcsfs`).
+
 ```python
 import xarray as xr
 import xarray_sql as xql