Search and discovery

Users shouldn't have to browse through categories to find an answer. Search surfaces the right article instantly — and the better your articles are written, the better results your users get.

How search works

Your help center uses a hybrid approach that combines two complementary search strategies:

Keyword search (40% weight) — PostgreSQL full-text search on article titles and content. Fast and precise for exact terms. Works without any external services.

Semantic search (60% weight) — Vector similarity search using your configured embedding model and pgvector. Understands meaning, not just words. A user searching "can't log in" will match an article titled "Reset your password" even though the words don't overlap.

The two scores are combined and ranked. The result is search that handles both "what's my API rate limit" and "why is my data not updating" equally well.

Where search appears

Search is available in three places:

• Help center homepage — The main search bar users see when they visit your help center
• Widget help tab — Embedded search inside the feedback widget, so users can find answers without leaving your app
• Admin article list — Filter your own articles by keyword while managing content

How embeddings are generated

When you create or update an article, Quackback automatically generates a vector embedding for it using your configured embedding model. The embedding captures the semantic meaning of the title and content as a 1536-dimensional vector stored in pgvector.

You don't need to trigger this manually. Save an article and the embedding updates in the background.

The same AI configuration used for other AI features powers the embeddings — set AI_EMBEDDING_MODEL alongside your API key and endpoint. Choose a model that produces 1536-dimensional vectors, such as text-embedding-3-small. There's nothing separate to configure for the help center.

Optimize articles for search

Search quality depends on how your articles are written. A few practices make a real difference:

Use clear, keyword-rich titles. Titles get the most weight. "Reset your password" beats "Account access issues" for users searching "forgot password."

Write meaningful descriptions. Descriptions appear in search results. A good description answers the article's core question in one sentence, which helps users pick the right result without opening every link.

Use headings to structure content. Headings break long articles into scannable sections and add more keyword surface area for full-text search.