Skip to content

How it works

xarray-sql lets SQL engines query Xarray Datasets as if they were tables, and turns query results back into Datasets. The explainer below walks through the three steps with a tiny slice of ARCO-ERA5 2 m temperature: eight days at 48 points on the globe, small enough to show every row. The slice is saved with the page, so it loads instantly and needs no Python.

What happens in each step

  1. Registering a Dataset with register (or Context.from_dataset) creates a table whose rows are the Dataset's grid cells. The table reads from the Dataset as the query runs, one chunk at a time, so registering copies nothing.
  2. Querying runs in the engine: DuckDB, DataFusion, or any engine that reads Arrow. Filters on dimension columns are pushed down to the table, which skips every partition whose coordinate range cannot match, so a selective query reads few chunks. See Engines.
  3. Round-tripping with to_dataset pivots the result rows back onto a grid and restores metadata from the registered Dataset. By default the result is lazy: each access reruns the query for just the part you select.

To run real queries over a public Zarr store, try xarray-sql in the browser.