Hybrid Search

Core Engine

How Relink ranks results, explains why they matched, and keeps filters aligned with search output.

The Search Algorithm

Relink uses a hybrid search approach powered by PostgreSQL, pgvector, and pg_trgm. Instead of relying purely on vector similarity (which struggles with exact keyword matches) or purely on full-text search (which misses conceptual synonyms and misspellings), we combine four distinct scores. The searchable text is precomputed during ingestion so search does not rebuild large document vectors on every request.

Four-Part Ranking

1. Semantic Similarity

Matches ideas and concepts. For longer natural-language searches, we embed the user query and compare it against stored document embeddings using cosine distance (<=>) in Postgres. Short exact queries such as domains, URLs, and tag-like terms skip this step for lower latency.

2. Keyword Search (FTS)

PostgreSQL native full-text search (to_tsvector) over a prebuilt search document. Title, tags, summaries, and notes are repeated more heavily than long-body text so high-signal metadata still outranks incidental mentions deep in the article.

3. Partial Match (ILIKE)

A fallback mechanism ensures that partial strings (for example, typing nextj instead of nextjs) do not return zero results by executing an ILIKE %query% comparison on exact-match-friendly fields such as title, domain, and URL.

4. Typo-Tolerant Fuzzy Match

PostgreSQL trigram similarity (pg_trgm) catches near-miss spellings such as desin sistem for design system. This score is focused on title, domain, and URL so typo tolerance stays fast even on larger archives.

Scoring Equation

The final ranking score is a weighted combination of all three match types. Results must pass a minimum threshold score (> 0.4) to be returned to the user, stripping out low-relevance noise.

SQL Scoring Logic

total_score = (semantic_score * 1.0) 
            + (keyword_score * 2.0) 
            + (partial_score * 2.0)
            + (fuzzy_score * 1.5)

Why a Result Appeared

Each result can include a short human-readable reason such as a title hit, a matching tag, summary overlap, note match, close spelling match, or a semantic-only explanation. This reason is rendered directly on the card so semantic search does not feel opaque.

Result-Aware UI

Search returns the same card-critical metadata as the main dashboard feed, including content type, collection assignment, thumbnails, PDF file state, and processing updates. That keeps badges, collection counts, and drawer behavior consistent while you are in search mode.

Usage Tip: Search results replace the dashboard grid, and collection counts in the sidebar also reflect the current result set. Resetting search returns the dashboard to its normal chronological view.