simbad-resolver 0.5.0

SIMBAD astronomical target resolver for Rust: resolve names, designations, and positions to canonical identities, with a pluggable redb-backed cache.
Documentation

simbad-resolver

CI crates.io docs.rs

A Rust library for resolving astronomical object names, catalog designations, and sky positions to canonical target identities using SIMBAD.

Given an input such as M31, NGC 224, Andromeda Galaxy, C 14, or a sky position, simbad-resolver queries SIMBAD and returns a single canonical identity: a stable id, ICRS J2000 coordinates, an object-type classification, a Johnson V magnitude when SIMBAD has one (v_mag, None otherwise), the object's alias set, and the provenance of the record.

Resolved identities are stored in a pluggable cache, so repeated lookups are served locally instead of re-querying SIMBAD. An async batch resolver processes many names against a durable queue.

It is a single crate with no required feature flags: the network resolvers and a redb-backed store (durable or in-memory) ship in the default build.

Documentation

Full API documentation is generated from the source and published on docs.rs: docs.rs/simbad-resolver. For a task-oriented walkthrough (resolving a name, testing offline, batching, storage), see the guide (also in this repo at docs/guide.md).

cargo doc --open

Resolving

Two SIMBAD backends are available, both built in:

  • TapResolver queries the SIMBAD TAP service with ADQL. It returns SIMBAD object ids, object types, the full alias set, a Johnson V magnitude (via a LEFT OUTER JOIN on allfluxes, None when the object has no V photometry), and supports cone search by position.
  • SesameResolver queries the CDS Sesame name resolver, which aggregates SIMBAD, NED, and VizieR. It resolves a broader range of names but returns coordinates and a primary designation only; object type and aliases can be filled in by supplying a TapResolver as an enricher.

Both implement the Resolver trait, so either can back a SimbadResolver facade or a BatchResolver.

Caldwell designations (C 14) are not SIMBAD identifiers; the facade translates them to the underlying catalog designation via caldwell::caldwell_to_designation before resolving, then binds the original C n as an alias.

Positions

Resolving by sky position (cone search) is the PositionResolver capability, implemented by TapResolver. Its resolve_position returns the objects within radius_deg of an ICRS position, nearest first, as PositionMatch values. This hits the live endpoint, so it needs network access:

use simbad_resolver::{PositionResolver, TapResolver};

# async fn run() -> Result<(), simbad_resolver::ResolveError> {
let resolver = TapResolver::with_defaults()?;
// Objects within 0.05° of M 31's ICRS position, nearest first (max 5).
let matches = resolver.resolve_position(10.684_708, 41.268_75, 0.05, 5).await?;
for m in &matches {
    println!("{} at {:.4}°", m.identity.primary_designation, m.separation_deg);
}
# Ok(())
# }

Search

SimbadResolver::search is a local, network-free typeahead over cached aliases, ranked exact > prefix > substring. Enabling fuzzy matching with ResolverConfig::with_fuzzy fills remaining result slots with token-set similarity hits in the RANK_FUZZY tier. This does not change resolve, which stays exact-normalized.

Overrides

SimbadResolver::apply_override binds a chosen canonical target as authoritative: it adds the supplied alias and marks the row sticky (source = user-override), so a later re-resolve does not overwrite it. See the guide for an example.

Storage

The facade selects its cache with a CacheBackend, chosen at construction — there is no separate "enable caching" step, because the cache is load-bearing (resolve returns cached rows). The built-in backend is redb (a pure-Rust embedded ACID store):

For an uncached one-shot lookup, call a bare Resolver (e.g. TapResolver) directly instead of the facade.

Under the hood the built-in variants open a Store (still public: Store::open / Store::in_memory, each exposing .cache() and .queue() over one database). Open the Store yourself to share one database between a SimbadResolver and a BatchResolver:

use simbad_resolver::{
    BatchResolver, CacheBackend, ResolverConfig, SimbadResolver, Store, TapResolver,
};

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let store = Store::open("targets.redb")?;
let config = ResolverConfig::new("your.namespace");

// Both operate over the same rows: the facade caches resolved targets, the
// batch resolver drains its queue into that same cache.
let facade = SimbadResolver::new(
    TapResolver::with_defaults()?,
    CacheBackend::custom(store.cache()),
    config.clone(),
)?;
let batch =
    BatchResolver::new(TapResolver::with_defaults()?, store.cache(), store.queue(), config);
# let _ = (facade, batch);
# Ok(())
# }

Coordinates

Resolved-object types (ResolvedIdentity, CachedTarget, and the cone-search PositionMatch) keep their canonical ra_deg/dec_deg (f64, ICRS J2000 degrees) and also expose a typed accessor:

# use simbad_resolver::ResolvedIdentity;
# fn coordinates(target: &ResolvedIdentity) -> Result<(), Box<dyn std::error::Error>> {
let eq = target.position()?; // skymath::Equatorial: validated RA/Dec carrying its epoch
# let _ = eq;
# Ok(())
# }

position() returns a skymath::Equatorial — this crate depends on skymath for that shared, domain-validated coordinate type, so downstream consumers (ranking, formatting) share one representation with no conversion. SIMBAD's ICRS output is treated as J2000 at planning grade (≤ ~1 arcminute); the raw f64 fields remain the source of truth.

Usage

This calls the live SIMBAD TAP endpoint, so it needs network access to run.

use simbad_resolver::{CacheBackend, Resolution, ResolverConfig, SimbadResolver, TapResolver};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let resolver = TapResolver::with_defaults()?;
// Ephemeral cache; `CacheBackend::file("targets.redb")` persists across restarts.
let facade =
    SimbadResolver::new(resolver, CacheBackend::InMemory, ResolverConfig::new("your.namespace"))?;

match facade.resolve("M31").await? {
    Resolution::Resolved(target) => {
        println!("{} at ({}, {})", target.primary_designation, target.ra_deg, target.dec_deg);
    }
    Resolution::Unresolved { reason, .. } => println!("unresolved: {reason:?}"),
}
# Ok(())
# }

When a query does not resolve, the Resolution::Unresolved reason is a UnresolvedReason: Offline (backend unreachable/timed out/disabled — retry later; cached objects still resolve), Unknown (no such object — give up), or Ambiguous (several distinct objects — disambiguate the query).

See the guide for a walkthrough that also covers testing without the network (OfflineResolver/FakeResolver) and batch resolution.

[dependencies]
simbad-resolver = "0.2"

Attribution

This library queries SIMBAD, operated at CDS, Strasbourg, France. Applications that display resolved data should credit CDS and send an identifying User-Agent header (configurable via SimbadConfig).

License

License: MPL 2.0

This project is licensed under the Mozilla Public License 2.0 — see LICENSE for details.

You can use this library in closed-source projects. If you modify any of the source files in this library, the modified files must be made available under the MPL-2.0 when distributed.