Sessions and materialize()

Stub

Final content will explain when to use acid.sql(...) vs acid.connect(...) vs Session.materialize(...), with a worked example of caching a heavy crossmatch and then running follow-up queries cheaply.

Topics planned:

  • acid.sql(query, catalogs=..., workers=...) — one-shot. Pays the startup cost every time.
  • with acid.connect(catalogs, workers=...) as s: s.sql(...) — keeps the worker pool and registry warm; 5–10× faster for repeated queries.
  • s.materialize("name", query) — promote an intermediate result to a real catalog you can use in later queries. The canonical EDA pattern: run a 3-way XMATCH once, materialize it, then iterate on filters and aggregates against the cached output.
  • s.list_catalogs(), s.add_catalog(name, **spec), s.explain(query), s.validate(query) — the introspection surface.
  • Lifecycle: when the worker pool starts, when it tears down, and the s.close() / context-manager pattern.