Omnisearch

Craft’s omnisearch is a unified search across every object in the catalog — satellites, planets, stars, deep sky objects, comets, radio frequencies, and rocket launches. It combines text matching with semantic vector search so you can find things by name, catalog ID, or natural language description.

How to search

Command palette

Press Ctrl+K (or Cmd+K on macOS) anywhere in the Craft UI to open the command palette. Type your query and results appear instantly, grouped by object type.

API endpoint

curl "https://your-domain/api/search?q=weather+satellites+polar+orbit"

Parameters

Parameter	Default	Description
q	required	Search query (min 1 character)
types	all	Comma-separated type filter: satellite, star, dso, planet, comet, frequency, launch
limit	20	Maximum results (max 50)
mode	hybrid	Search mode: hybrid, semantic, or text

What you can search for

Object type	Searchable fields	Examples
Satellites	Name, NORAD ID, international designator, group	ISS, 25544, starlink, amateur
Stars	Name, catalog ID (HIP, HD, HR), spectral type	Vega, HIP 91262, Polaris
Deep sky objects	Name, catalog ID (Messier, NGC, IC), description	M31, NGC 7000, Andromeda
Planets	Name	Mars, Jupiter, Saturn
Comets	Name, designation	Halley, C/2023 A3
Radio frequencies	Description, frequency value, modulation type	ISS APRS, 145.825 MHz, FM repeater
Rocket launches	Mission name, rocket name, launch provider	Falcon 9, Crew Dragon, SpaceX

Type shortcuts

Prefix your query with a shortcut to restrict results to a single type:

Shortcut	Type
/sat	Satellites
/star	Stars
/dso	Deep sky objects
/launch	Rocket launches
/freq	Radio frequencies
/comet	Comets

For example, /sat starlink searches only satellites, and /freq ISS searches only frequency records.

Hybrid search: how it works

Omnisearch runs two search strategies in parallel and merges the results:

Text search

Standard substring matching using PostgreSQL’s ILIKE operator with a GIN trigram index. This is fast and exact — if your query is a substring of the object’s name or catalog ID, it will match.

Text search is good for:

• Exact names (“ISS”, “M31”)
• NORAD IDs (“25544”)
• Partial names (“starli” matches “Starlink”)

Semantic search

Vector similarity search using pgvector. Each object in the catalog has a text representation (its search_text column) that gets embedded into a 1024-dimensional vector by the pgai vectorizer worker. Your query is also embedded, and the search finds objects whose vectors are closest by cosine distance.

Semantic search is good for:

• Descriptive queries (“weather satellites in polar orbit”)
• Conceptual matching (“amateur radio repeater satellites”)
• Queries that do not contain the exact object name

When both strategies return results, the merge logic:

1. Takes all semantic results first (higher priority, scored by vector distance)
2. Adds text results that are not already present
3. Boosts the score of any object found by both strategies
4. Sorts by final score descending
5. Truncates to the requested limit

The response includes a source field on each result ("semantic", "text", or "both") so you can see which strategy found it.

Search results

Each result includes:

{
  "name": "ISS (ZARYA)",
  "target_type": "satellite",
  "target_id": "25544",
  "description": null,
  "magnitude": 1.0,
  "score": 0.87,
  "source": "both",
  "groups": ["stations", "visual"],
  "url": "/catalog/satellite/25544"
}

Satellite results are enriched with live altitude data when available — the altitude_deg field tells you whether the object is currently above the horizon.

How embeddings are generated

The embedding pipeline runs automatically in the background:

1. When you seed the database or when new objects arrive (TLE updates, launch data refreshes), each object’s search_text column is populated with a concatenation of its searchable fields.

2. The pgai vectorizer worker container watches for new or updated search_text values.

3. For each change, the worker sends the text to the GPU embedding endpoint (configured via GPU_BASE_URL and GPU_API_KEY in .env) and stores the resulting 1024-dimensional vector.

4. The vectors are stored in dedicated embedding tables (satellite_embedding_store, celestial_object_embedding_store, target_frequency_embedding_store, rocket_launch_embedding_store).

After a fresh seed, the initial embedding generation for 22,000+ objects takes roughly 10 minutes. You can monitor progress:

docker compose exec db psql -U astrolock -d astrolock \
  -c "SELECT * FROM ai.vectorizer_status;"

Note

If the GPU embedding endpoint is unavailable, omnisearch falls back to text-only mode automatically. You will still get results, just without the semantic matching component. The response’s mode field will show "text" instead of "hybrid".

Search tips

• Be specific when you can — “ISS” is faster than “international space station” because the text index matches immediately
• Use natural language for discovery — “satellites that photograph the Earth” works well with semantic search even though no satellite has that exact phrase in its name
• Combine type shortcuts with descriptive queries — /freq UHF downlink narrows results to frequency records matching “UHF downlink”
• NORAD IDs are unambiguous — if you know the catalog number, searching for 25544 goes straight to the right object