Functions: Rise/Set & Constellations

Functions for predicting when celestial bodies rise and set, and for identifying which constellation a sky coordinate falls in. Rise/set prediction uses bisection search on elevation with a 7-day search window. Constellation identification uses the Roman (1987) boundary table (CDS VI/42, 357 segments), precessing input coordinates to B1875.0 internally.

Tip

Rise/set functions return NULL for circumpolar bodies and bodies that never rise. Use the corresponding _rise_set_status() function to distinguish between these cases.

---

sun_next_rise

Returns the next geometric sunrise after the given time. The geometric horizon is 0 degrees --- no refraction or semidiameter correction.

Signature

sun_next_rise(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next sunrise, or NULL if the Sun does not rise within 7 days (circumpolar or never-rises).

Example

-- Next sunrise from Boise
SELECT sun_next_rise('43.7N 116.4W 800m'::observer, now());

---

sun_next_set

Returns the next geometric sunset after the given time.

Signature

sun_next_set(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next sunset, or NULL if the Sun does not set within 7 days.

Example

-- How long until sunset?
SELECT sun_next_set('43.7N 116.4W 800m'::observer, now()) - now() AS time_until_sunset;

---

moon_next_rise

Returns the next geometric moonrise after the given time.

Signature

moon_next_rise(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next moonrise, or NULL if the Moon does not rise within 7 days.

Example

-- Next moonrise
SELECT moon_next_rise('40.0N 105.3W 1655m'::observer, now());

---

moon_next_set

Returns the next geometric moonset after the given time.

Signature

moon_next_set(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next moonset, or NULL if the Moon does not set within 7 days.

Example

-- Moon visibility window
SELECT moon_next_rise('40.0N 105.3W 1655m'::observer, now()) AS moonrise,
       moon_next_set('40.0N 105.3W 1655m'::observer, now()) AS moonset;

---

planet_next_rise

Returns the next geometric rise time for a planet after the given time.

Signature

planet_next_rise(body_id int4, obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 1=Mercury, 2=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next rise, or NULL if the planet does not rise within 7 days. Raises an error for invalid body_id (0=Sun, 3=Earth, 10=Moon have dedicated functions).

Example

-- When does Jupiter rise tonight?
SELECT planet_next_rise(5, '43.7N 116.4W 800m'::observer, now());

---

planet_next_set

Returns the next geometric set time for a planet after the given time.

Signature

planet_next_set(body_id int4, obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 1=Mercury, 2=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next set, or NULL if the planet does not set within 7 days.

Example

-- Venus visibility window
SELECT planet_next_rise(2, '43.7N 116.4W 800m'::observer, now()) AS venus_rise,
       planet_next_set(2, '43.7N 116.4W 800m'::observer, now()) AS venus_set;

---

sun_next_rise_refracted

Returns the next refracted sunrise after the given time. The threshold is -0.833 degrees geometric elevation, accounting for atmospheric refraction (0.569 deg) and the Sun’s semidiameter (0.266 deg). Refracted sunrise is earlier than geometric sunrise.

Signature

sun_next_rise_refracted(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted sunrise, or NULL if the Sun does not rise within 7 days.

Example

-- Refracted vs geometric sunrise difference
SELECT sun_next_rise_refracted(obs, t) AS refracted,
       sun_next_rise(obs, t) AS geometric
FROM (VALUES ('43.7N 116.4W 800m'::observer, '2024-01-15 00:00:00+00'::timestamptz)) AS v(obs, t);

---

sun_next_set_refracted

Returns the next refracted sunset after the given time. Uses the same -0.833 degree threshold. Refracted sunset is later than geometric sunset.

Signature

sun_next_set_refracted(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted sunset, or NULL if the Sun does not set within 7 days.

Example

-- How much longer is the refracted day?
SELECT sun_next_set_refracted(obs, t) - sun_next_rise_refracted(obs, t) AS refracted_day,
       sun_next_set(obs, t) - sun_next_rise(obs, t) AS geometric_day
FROM (VALUES ('43.7N 116.4W 800m'::observer, '2024-03-20 00:00:00+00'::timestamptz)) AS v(obs, t);

---

moon_next_rise_refracted

Returns the next refracted moonrise after the given time. Uses the -0.833 degree threshold (refraction + semidiameter).

Signature

moon_next_rise_refracted(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted moonrise, or NULL if the Moon does not rise within 7 days.

Example

SELECT moon_next_rise_refracted('40.0N 105.3W 1655m'::observer, now());

---

moon_next_set_refracted

Returns the next refracted moonset after the given time. Uses the -0.833 degree threshold.

Signature

moon_next_set_refracted(obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted moonset, or NULL if the Moon does not set within 7 days.

Example

SELECT moon_next_set_refracted('40.0N 105.3W 1655m'::observer, now());

---

planet_next_rise_refracted

Returns the next refracted rise time for a planet after the given time. The threshold is -0.569 degrees geometric elevation, accounting for atmospheric refraction only (planets are point sources).

Signature

planet_next_rise_refracted(body_id int4, obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 1=Mercury, 2=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted rise, or NULL if the planet does not rise within 7 days.

Note

Sun and Moon use a -0.833 degree threshold (refraction + semidiameter). Planets use -0.569 degrees (refraction only --- even Jupiter at opposition is only 24 arcseconds).

Example

-- Refracted vs geometric rise for Saturn
SELECT planet_next_rise_refracted(6, obs, t) AS refracted,
       planet_next_rise(6, obs, t) AS geometric
FROM (VALUES ('43.7N 116.4W 800m'::observer, now())) AS v(obs, t);

---

planet_next_set_refracted

Returns the next refracted set time for a planet after the given time. Uses the -0.569 degree threshold.

Signature

planet_next_set_refracted(body_id int4, obs observer, t timestamptz) → timestamptz

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 1=Mercury, 2=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
obs	observer	Observer location
t	timestamptz	Search start time

Returns

The timestamptz of the next refracted set, or NULL if the planet does not set within 7 days.

Example

-- Mars visibility tonight (refracted)
SELECT planet_next_rise_refracted(4, obs, t) AS mars_rise,
       planet_next_set_refracted(4, obs, t) AS mars_set
FROM (VALUES ('43.7N 116.4W 800m'::observer, now())) AS v(obs, t);

---

sun_rise_set_status

Reports whether the Sun rises and sets, is circumpolar, or never rises at the given location and time. Samples elevation at 48 points across 24 hours.

Signature

sun_rise_set_status(obs observer, t timestamptz) → text

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Reference time (defines the 24h sampling window)

Returns

One of three text values: 'rises_and_sets', 'circumpolar', or 'never_rises'.

Example

-- Why doesn't the Sun set? (Arctic summer)
SELECT sun_rise_set_status('70N 25E 0m'::observer, '2024-06-21 00:00:00+00'::timestamptz);
-- → 'circumpolar'

-- Normal mid-latitude behavior
SELECT sun_rise_set_status('43.7N 116.4W 800m'::observer, now());
-- → 'rises_and_sets'

---

moon_rise_set_status

Reports whether the Moon rises and sets, is circumpolar, or never rises at the given location and time.

Signature

moon_rise_set_status(obs observer, t timestamptz) → text

Parameters

Parameter	Type	Description
obs	observer	Observer location
t	timestamptz	Reference time

Returns

One of three text values: 'rises_and_sets', 'circumpolar', or 'never_rises'.

Example

-- Check Moon status before querying rise/set
SELECT moon_rise_set_status('80N 0E 0m'::observer, now()) AS status,
       moon_next_rise('80N 0E 0m'::observer, now()) AS next_rise;

---

planet_rise_set_status

Reports whether a planet rises and sets, is circumpolar, or never rises at the given location and time.

Signature

planet_rise_set_status(body_id int4, obs observer, t timestamptz) → text

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 1=Mercury, 2=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune
obs	observer	Observer location
t	timestamptz	Reference time

Returns

One of three text values: 'rises_and_sets', 'circumpolar', or 'never_rises'.

Example

-- Check all planets' status from a high-latitude site
SELECT body_id, name,
       planet_rise_set_status(body_id, '65N 18W 0m'::observer, now()) AS status
FROM (VALUES (1,'Mercury'),(2,'Venus'),(4,'Mars'),(5,'Jupiter'),
             (6,'Saturn'),(7,'Uranus'),(8,'Neptune')) AS p(body_id, name);

---

constellation

Returns the 3-letter IAU constellation abbreviation for a sky position. Uses the Roman (1987) boundary table (CDS VI/42) with 357 boundary segments. Input coordinates are precessed from J2000 to B1875.0 internally to match the boundary epoch.

Signature

constellation(eq equatorial) → text
constellation(ra_hours float8, dec_deg float8) → text

Parameters

Overload 1 --- from equatorial type:

Parameter	Type	Description
eq	equatorial	Equatorial sky position (RA in hours, Dec in degrees)

Overload 2 --- from explicit coordinates:

Parameter	Type	Unit	Description
ra_hours	float8	hours	Right ascension in J2000, range [0, 24)
dec_deg	float8	degrees	Declination in J2000, range [-90, 90]

Returns

A 3-letter IAU constellation abbreviation (e.g., 'Ori', 'UMa', 'Sgr'). There are 88 possible values, one for every IAU constellation.

Example

-- What constellation is Jupiter in?
SELECT constellation(planet_equatorial(5, now()));
-- → 'Ari'

-- Polaris
SELECT constellation(2.5303, 89.2641);
-- → 'UMi'

-- Orion's belt star Alnitak
SELECT constellation(5.679, -1.943);
-- → 'Ori'

---

constellation_full_name

Converts a 3-letter IAU constellation abbreviation to its full IAU name.

Signature

constellation_full_name(abbr text) → text

Parameters

Parameter	Type	Description
abbr	text	3-letter IAU abbreviation (e.g., 'Ori', 'UMa')

Returns

The full IAU constellation name (e.g., 'Orion', 'Ursa Major'), or NULL if the abbreviation is not recognized.

Example

-- Full name for display
SELECT constellation_full_name(constellation(planet_equatorial(5, now())));
-- → 'Aries'

-- All 88 constellations (abbreviated sample)
SELECT constellation_full_name('Ori') AS orion,
       constellation_full_name('UMa') AS ursa_major,
       constellation_full_name('Sgr') AS sagittarius,
       constellation_full_name('Crx') AS invalid;
-- → 'Orion', 'Ursa Major', 'Sagittarius', NULL

-- What constellation is each planet in right now?
SELECT name,
       constellation(planet_equatorial(body_id, now())) AS abbr,
       constellation_full_name(constellation(planet_equatorial(body_id, now()))) AS constellation
FROM (VALUES (1,'Mercury'),(2,'Venus'),(4,'Mars'),(5,'Jupiter'),
             (6,'Saturn'),(7,'Uranus'),(8,'Neptune')) AS p(body_id, name);