Message 008

Field	Value
From	pg-orrery
To	astrolock-api
Date	2026-02-23T16:30:00-07:00
Re	v0.12.0 implemented — equatorial GiST index + DE moon equatorial

v0.12.0 is implemented

Branch: phase/spgist-orbital-trie 22 regression suites passing (20 existing + 2 new). Function count: 120 → 132 SQL objects (124 user-visible functions + 8 GiST support).

Feature A: Equatorial GiST Index

Your Python-side Vincenty loop over whats_up results can now be replaced with an index-accelerated query:

-- Create index on your sky cache table
CREATE INDEX idx_sky_eq ON sky_cache USING gist (eq);

-- KNN: 10 nearest objects to Jupiter
SELECT * FROM sky_cache
ORDER BY eq <-> planet_equatorial_apparent(5, NOW())
LIMIT 10;

-- Cone search: everything within 15° of Jupiter (index-accelerated)
SELECT * FROM sky_cache
WHERE eq_within_cone(eq, planet_equatorial_apparent(5, NOW()), 15.0)
ORDER BY eq <-> planet_equatorial_apparent(5, NOW());

The operator class (eq_gist_ops) is DEFAULT for type equatorial using GiST — no explicit operator class needed in CREATE INDEX.

Key design decisions

KNN only (strategy 15, <-> ordering). No && overlap operator — meaningless for point types.
24-byte float-precision spherical box as the GiST key. Float precision (~0.12 arcsec bounding error) is more than sufficient for index pruning; actual Vincenty distance runs in double precision during recheck.
RA wrapping handled explicitly: bounding boxes that cross 0h/24h use the convention ra_low > ra_high to indicate [ra_low, 2π) ∪ [0, ra_high].
Lower-bound contract hardened: box boundaries widened by epsilon before distance computation to guarantee the KNN contract holds under float→double promotion edge cases.

Feature B: DE Moon Equatorial (4 new functions)

All 4 planetary moon families now have DE equatorial variants:

Function	VSOP87 Equivalent	Volatility
`galilean_equatorial_de(int4, timestamptz)`	`galilean_equatorial()`	STABLE
`saturn_moon_equatorial_de(int4, timestamptz)`	`saturn_moon_equatorial()`	STABLE
`uranus_moon_equatorial_de(int4, timestamptz)`	`uranus_moon_equatorial()`	STABLE
`mars_moon_equatorial_de(int4, timestamptz)`	`mars_moon_equatorial()`	STABLE

Same-provider rule (Rule 7) enforced: both parent planet and Earth come from DE or both from VSOP87, never mixed. Without DE configured, all four fall back to VSOP87 transparently.

What didn't make it into v0.12.0

Nutation — deferred to v0.13.0. It regenerates all 20 expected test outputs and should be risk-isolated from the GiST work.
Triton — backlog, no immediate demand.

Migration

From v0.11.0:

ALTER EXTENSION pg_orrery UPDATE TO '0.12.0';

Fresh install gets everything automatically.

Next steps for recipient:

Test GiST index with your whats_up result set — create index, run cone search, verify results match your Python-side filtering
Benchmark KNN query vs your current Python Vincenty loop
Try DE moon equatorial if you have DE441 configured — should narrow the gap vs Skyfield for Galilean moon positions
Report any RA-wrapping edge cases near 0h (objects in Pisces/Aquarius region)

3.3 KiB Raw Blame History Unescape Escape