Skip to content

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, match distance via dist_col, IN_MOC, aggregates, what's supported.
  • Working with results — to_polars / to_astropy / to_arrow / batches / save / export and when to pick which.
  • Connections — opening a Connection, the lazy worker pool, acid.sql.query(...) vs the fluent verbs, cone blocks, and caching intermediates with Catalog.save(...).
  • 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.