Cookbook

Stub

Final content will be 12–15 self-contained recipes, each a few lines of code with a one-paragraph "why" header. Drawn from the test suite so they're known-good shapes.

Planned recipes:

  1. Count sources in a survey footprint — IN_MOC + COUNT(*).
  2. Nearest-neighbor crossmatch of two catalogs — the canonical XMATCH example.
  3. All matches within 5″ — mode => 'all'.
  4. LEFT crossmatch to keep unmatched sources — LEFT JOIN ... ON XMATCH(...).
  5. Crossmatch filtered by XMATCH_DISTANCE — distance in WHERE.
  6. Top-10 closest matches per anchor source — XMATCH + ORDER BY
  7. LIMIT.
  8. 3-way join: crossmatch then ordinary join — XMATCH a catalog, then a.id = lc.object_id against a lightcurve table.
  9. Self-crossmatch — find pairs within one catalog (aliasing the same table twice).
  10. Filter by a survey footprint — WHERE IN_MOC(a, 'des_dr2').
  11. Sources outside a footprint — WHERE NOT IN_MOC(a, 'des').
  12. Per-source aggregates with HAVING — GROUP BY a.id HAVING COUNT(*) >= 2.
  13. Materialize a heavy intermediate, then iterate — s.materialize(...) + cheap follow-ups.
  14. Stream a huge result to parquet — acid query --out.
  15. Write a single parquet file — r.write_parquet(path, layout="single").
  16. Run a query from the CLI from a .sql file — acid query -f q.sql --db ....

Every recipe will lead with r.df() (pandas) for familiarity and end with a one-line "Faster on big results: df = r.to_polars(); ..." note when the recipe does work beyond inspection.