Skip to main content

Crate simbad_resolver

Crate simbad_resolver 

Source
Expand description

§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};

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);
}

§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,
};

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);

§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:

let eq = target.position()?; // skymath::Equatorial: validated RA/Dec carrying its epoch

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};

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:?}"),
}

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.

Modules§

caldwell
Static Caldwell → NGC/IC (or other) designation map.
guide
Guide
identity
Deterministic UUIDv5 derivation for a resolved target’s stable id.
normalize
Query normalization pipeline.
wire
Pure TSV/wire parsing helpers for a SIMBAD TAP basic ⋈ allfluxes row.

Structs§

BatchResolver
The async batch resolver. Generic over any Resolver; the cache and queue backends are type-erased so the type does not carry them.
CachedTarget
A cached canonical target plus its aliases, as read back from a Cache.
DrainSummary
Summary of a BatchResolver::drain pass.
FakeResolver
In-memory test double for Resolver.
FileCache
Options for the built-in file-backed cache.
OfflineResolver
A zero-cost Resolver that never reaches the network.
PendingItem
One queued batch item (read model for a Queue).
PositionMatch
One result of a position (cone-search) resolution.
RedbCache
The durable/ephemeral redb-backed Cache.
RedbQueue
The durable/ephemeral redb-backed Queue.
ResolvedAlias
One alternate designation/name for a resolved identity. The normalized form is the typeahead match surface.
ResolvedIdentity
A fully resolved canonical target identity returned by a crate::Resolver.
ResolverConfig
Configuration for the crate::SimbadResolver facade.
SearchHit
A single ranked typeahead hit.
SesameResolver
SIMBAD Sesame resolver: broad name coverage (SIMBAD + NED + VizieR aggregation via CDS Sesame’s -oxp XML flavour) at the cost of coarser output (no simbad_oid; object-type/alias completeness depends on which backend Sesame answers from first).
SimbadConfig
Configuration for a network-backed crate::Resolver (e.g. the SIMBAD TAP or Sesame resolver).
SimbadResolver
The cache-first resolver facade.
Store
An open redb database shared by a RedbCache and a RedbQueue.
TapResolver
Live SIMBAD TAP resolver: implements Resolver and PositionResolver.

Enums§

AliasKind
The kind of an alias attached to a resolved identity.
BatchDurability
Write-transaction durability Cache::upsert_batch uses, configured once when a Store is opened (see Store::open_with) — not per call. Maps to redb::Durability: Durable -> Immediate, Eventual -> None. Single-item Cache::upsert always stays Durable regardless of this setting — point writes should stay durable; only a bulk batch load is worth trading that away.
CacheBackend
How a SimbadResolver obtains its cache backend.
CacheError
Error type for Cache operations.
Error
Errors surfaced by the crate::SimbadResolver facade and crate::BatchResolver.
ObjectType
Closed object-type enum mapped from SIMBAD otype.
PendingState
State of a queued batch item.
QueueError
Error type for Queue operations.
Resolution
The outcome of a SimbadResolver::resolve call.
ResolveError
Errors produced by a crate::Resolver.
TargetSource
Provenance of a resolved identity.
UnresolvedReason
Why a query could not be resolved to a canonical target.
UpsertOutcome
Outcome of a Cache::upsert call.

Constants§

RANK_EXACT
Rank bucket for an exact normalized-alias match.
RANK_FUZZY
Rank bucket for a fuzzy (token-set similarity) match.
RANK_PREFIX
Rank bucket for a prefix match.
RANK_SUBSTRING
Rank bucket for a substring match.

Traits§

Cache
The pluggable identity store.
PositionResolver
Position resolution (cone search) is a separate capability some resolver backends provide; not every Resolver supports it.
Queue
The pluggable pending-work store for the async batch resolver.
Resolver
Resolve a designation or common name to one canonical identity.

Functions§

map_otype
Map a raw SIMBAD otype string to the closed ObjectType enum.