User guide¶

The chapters below cover everything you need to write real queries against your own catalogs. They assume you've completed the Quickstart.

• Concepts — HATS, HEALPix, MOCs, margin caches, the XMATCH operator. The mental model you'll lean on.
• Catalogs and the registry — pointing acid at your data: directories, YAML files, per-catalog overrides.
• Writing queries — the SQL dialect: joins, XMATCH, XMATCH_DISTANCE, IN_MOC, aggregates, what's supported.
• Working with results — arrow / df / to_polars / batches / write_parquet and when to pick which.
• Sessions and materialize() — connect(...) vs sql(...), and how to cache intermediates.
• Downloading catalogs — acid download from HTTP, SSH, and local mirrors; spatial and column subsets.
• Margin caches — what they are, why they matter, building one locally.
• Performance — workers, engines, predicate pushdown, when to spill to disk.
• MOC footprints — registering MOCs, using IN_MOC and NOT IN_MOC, catalog-footprint auto-resolution.