Expand description
§simbad-resolver
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:
TapResolverqueries the SIMBAD TAP service with ADQL. It returns SIMBAD object ids, object types, the full alias set, a Johnson V magnitude (via aLEFT OUTER JOINonallfluxes,Nonewhen the object has no V photometry), and supports cone search by position.SesameResolverqueries 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 aTapResolveras 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):
CacheBackend::InMemory— ephemeral, nothing written to disk (alsoDefault).CacheBackend::file("targets.redb")— durable, file-backed; survives restarts.CacheBackend::custom(my_cache)— anyCacheimplementation you supply.
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 epochposition() 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
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
UUIDv5derivation for a resolved target’s stable id. - normalize
- Query normalization pipeline.
- wire
- Pure TSV/wire parsing helpers for a SIMBAD TAP
basic ⋈ allfluxesrow.
Structs§
- Batch
Resolver - The async batch resolver. Generic over any
Resolver; the cache and queue backends are type-erased so the type does not carry them. - Cached
Target - A cached canonical target plus its aliases, as read back from a
Cache. - Drain
Summary - Summary of a
BatchResolver::drainpass. - Fake
Resolver - In-memory test double for
Resolver. - File
Cache - Options for the built-in file-backed cache.
- Offline
Resolver - A zero-cost
Resolverthat never reaches the network. - Pending
Item - One queued batch item (read model for a
Queue). - Position
Match - One result of a position (cone-search) resolution.
- Redb
Cache - The durable/ephemeral redb-backed
Cache. - Redb
Queue - The durable/ephemeral redb-backed
Queue. - Resolved
Alias - One alternate designation/name for a resolved identity. The
normalizedform is the typeahead match surface. - Resolved
Identity - A fully resolved canonical target identity returned by a
crate::Resolver. - Resolver
Config - Configuration for the
crate::SimbadResolverfacade. - Search
Hit - A single ranked typeahead hit.
- Sesame
Resolver - SIMBAD Sesame resolver: broad name coverage (SIMBAD + NED + VizieR
aggregation via CDS Sesame’s
-oxpXML flavour) at the cost of coarser output (nosimbad_oid; object-type/alias completeness depends on which backend Sesame answers from first). - Simbad
Config - Configuration for a network-backed
crate::Resolver(e.g. the SIMBAD TAP or Sesame resolver). - Simbad
Resolver - The cache-first resolver facade.
- Store
- An open redb database shared by a
RedbCacheand aRedbQueue. - TapResolver
- Live SIMBAD TAP resolver: implements
ResolverandPositionResolver.
Enums§
- Alias
Kind - The kind of an alias attached to a resolved identity.
- Batch
Durability - Write-transaction durability
Cache::upsert_batchuses, configured once when aStoreis opened (seeStore::open_with) — not per call. Maps toredb::Durability:Durable->Immediate,Eventual->None. Single-itemCache::upsertalways staysDurableregardless of this setting — point writes should stay durable; only a bulk batch load is worth trading that away. - Cache
Backend - How a
SimbadResolverobtains its cache backend. - Cache
Error - Error type for
Cacheoperations. - Error
- Errors surfaced by the
crate::SimbadResolverfacade andcrate::BatchResolver. - Object
Type - Closed object-type enum mapped from SIMBAD
otype. - Pending
State - State of a queued batch item.
- Queue
Error - Error type for
Queueoperations. - Resolution
- The outcome of a
SimbadResolver::resolvecall. - Resolve
Error - Errors produced by a
crate::Resolver. - Target
Source - Provenance of a resolved identity.
- Unresolved
Reason - Why a query could not be resolved to a canonical target.
- Upsert
Outcome - Outcome of a
Cache::upsertcall.
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.
- Position
Resolver - Position resolution (cone search) is a separate capability some resolver
backends provide; not every
Resolversupports 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
otypestring to the closedObjectTypeenum.