You search for "how to deploy" in your company's knowledge base. Traditional search returns documents that contain those exact words, which might miss the deployment guide that uses the word "release" instead.
Semantic search understands that "deploy" and "release" and "ship to production" all mean the same thing. It returns relevant results even when they use different terminology.
This difference matters. In a traditional search system, you need to know the exact keywords used in documentation. In a semantic search system, you describe what you need in your own words.
This guide explains how both approaches work, their strengths and weaknesses, and why the best modern knowledge bases use a hybrid of both.
How Traditional (Keyword) Search Works
Traditional search, also called keyword search or lexical search, matches exact words or variations of words.
The Basic Approach
- Indexing: Break documents into words (tokens)
- Matching: Find documents that contain the search keywords
- Ranking: Score matches based on:
- Frequency: How often does the keyword appear?
- Position: Is it in the title, heading, or body?
- Rarity: Is this word common or specific? (TF-IDF scoring)
Example
Document: "How to Deploy Backend Services to Production"
Search: "deploy backend"
Match: ✅ Yes (exact keyword match)
Search: "ship backend to prod"
Match: ❌ No (different words: "ship" vs "deploy", "prod" vs "production")
Algorithms Behind Traditional Search
The most common traditional search algorithms:
- TF-IDF (Term Frequency-Inverse Document Frequency): Scores words based on how often they appear in a document vs across all documents
- BM25: An improvement on TF-IDF that handles document length better
- Boolean search: Exact matches using AND, OR, NOT operators
Strengths of Traditional Search
✅ Fast: Simple token matching is computationally cheap ✅ Exact matches: Perfect for finding specific terms, codes, or IDs ✅ Predictable: You know exactly why a result was returned ✅ Transparent: Easy to debug and explain
Weaknesses of Traditional Search
❌ Vocabulary mismatch: Fails when query uses different words than documents ❌ No understanding of meaning: "Hot dog" returns pages about temperature and canines ❌ Requires exact wording: Users must guess the keywords used in documentation ❌ Poor with synonyms: "Car" does not match "automobile"
Traditional search works well when you know what words to search for. It breaks down when you do not.
How Semantic Search Works
Semantic search understands meaning, not just keywords. It converts text into vector embeddings, mathematical representations of concepts, and finds similar concepts even when words differ.
The Basic Approach
- Embedding: Convert documents into high-dimensional vectors (arrays of numbers)
- Indexing: Store vectors in a vector database
- Query embedding: Convert the search query into a vector
- Similarity search: Find documents whose vectors are closest to the query vector
What Are Embeddings?
An embedding is a list of numbers (typically 768-1536 dimensions) that represents the semantic meaning of text.
Similar concepts have similar embeddings:
"deploy code" → [0.23, -0.15, 0.67, ..., 0.42]
"ship to production" → [0.24, -0.14, 0.69, ..., 0.41] # Very similar!
"breakfast recipes" → [0.89, 0.12, -0.33, ..., -0.18] # Completely different
The distance between vectors indicates semantic similarity. Close vectors = related concepts.
Example
Document: "How to Deploy Backend Services to Production"
Embedding: [0.12, 0.45, -0.23, ..., 0.78]
Search: "ship backend to prod"
Query Embedding: [0.13, 0.46, -0.22, ..., 0.79] # Very similar to document!
Match: ✅ Yes (semantic similarity, even with different words)
How Embeddings Are Created
Modern semantic search uses transformer models (like OpenAI's text-embedding-ada-002 or open-source alternatives) trained on billions of text examples.
These models learn that:
- "deploy" and "ship" and "release" are related
- "production" and "prod" mean the same thing
- "backend services" and "server-side components" are similar
You do not train these models yourself, you use pre-trained models via API or self-hosted.
Similarity Metrics
Once you have embeddings, you measure similarity using:
- Cosine similarity: Measures the angle between vectors (most common)
- Dot product: Faster but assumes normalized vectors
- Euclidean distance: Measures geometric distance
The search returns documents with the highest similarity scores.
Strengths of Semantic Search
✅ Understands meaning: Matches concepts, not just words ✅ Handles synonyms: "Deploy" matches "ship" and "release" ✅ Works across languages: Can find similar concepts in different languages ✅ Natural language queries: Users can describe what they need conversationally ✅ Discovers related content: Surfaces conceptually similar docs you might not have thought to search for
Weaknesses of Semantic Search
❌ Slower: Embedding generation and vector search are computationally expensive ❌ Less precise for exact matches: May miss exact codes, IDs, or specific terms ❌ Black box: Harder to explain why a result was returned ❌ Requires embeddings: Documents must be pre-processed and embedded ❌ Cost: API-based embeddings (like OpenAI) cost money at scale
Semantic search excels at conceptual queries but can miss exact matches.
Keyword vs Semantic: Side-by-Side Comparison
| Aspect | Keyword Search (BM25) | Semantic Search (Embeddings) |
|---|---|---|
| How it works | Exact word matching | Meaning-based matching |
| Query: "deploy code" | Matches "deploy" and "code" | Matches "ship", "release", "production" |
| Query: "error 404" | ✅ Perfect for exact codes | ❌ Might return general error docs |
| Query: "how do I ship features?" | ❌ Misses "deploy" docs | ✅ Finds deployment guides |
| Speed | Fast (milliseconds) | Slower (100-300ms) |
| Precision | High for exact terms | High for concepts |
| Explainability | Easy (matched these keywords) | Harder (semantic similarity score) |
| Best for | Exact terms, codes, IDs | Natural language, concepts |
The Hybrid Approach: Best of Both Worlds
The best modern knowledge bases combine keyword and semantic search to get the benefits of both.
How Hybrid Search Works
-
Run both searches in parallel:
- Keyword search (BM25) for exact matches
- Semantic search (embeddings) for conceptual matches
-
Combine results using one of these strategies:
- Reciprocal Rank Fusion (RRF): Merge results based on rank position
- Weighted scoring: Give semantic results 70% weight, keyword 30% (or vice versa)
- Reranking: Use a separate model to re-score combined results
-
Return top results from the combined, re-ranked list
Why Hybrid Works Better
Example query: "production outage last night"
-
Keyword search finds:
- Documents with "production" and "outage"
- Exact match on incident reports
-
Semantic search finds:
- "Service downtime" docs (synonyms)
- "Critical incidents" guides
- Troubleshooting runbooks (conceptually related)
-
Hybrid returns:
- Last night's incident report (exact match)
- General outage runbooks (semantically related)
- Monitoring guides (conceptually relevant)
You get precision (exact codes, dates, names) and recall (related concepts, synonyms).
Performance Considerations
Hybrid search is more expensive computationally:
- Keyword search: ~10ms
- Semantic search: ~100-300ms
- Reranking: +50-100ms
But the improved results are worth the latency for most use cases.
When to Use Each Approach
Use Keyword Search When:
- Searching for exact terms: error codes, ticket IDs, specific feature names
- Users know the exact terminology used in docs
- Speed is critical (real-time autocomplete, instant search)
- You need explainable results (regulatory, audit)
Example queries:
- "Error 500"
- "Customer #12345"
- "Next.js 14.2 API"
Use Semantic Search When:
- Users describe needs in natural language
- Documentation uses varied terminology
- You want to discover related content users might not think to search for
- Queries are conceptual rather than exact
Example queries:
- "How do I ship a new feature?"
- "What to do when the site is slow?"
- "Onboarding process for new engineers"
Use Hybrid Search When:
- You want the best results regardless of query type
- Users submit a mix of exact and conceptual queries
- You have the infrastructure to support it (most modern knowledge bases do)
Best choice for most teams: Hybrid. It handles all query types well.
Real-World Examples
Example 1: Support Team Search
Query: "customer can't log in"
Keyword search returns:
- Docs with "customer" and "log in"
- Might miss "authentication issues" or "sign-in problems"
Semantic search returns:
- Login troubleshooting
- Authentication runbooks
- Password reset guides
- SSO configuration docs
Winner: Semantic (better concept matching)
Example 2: Engineering Team Search
Query: "TypeError: Cannot read property 'map' of undefined"
Keyword search returns:
- Exact error message matches
- Stack Overflow-style debugging guides
Semantic search returns:
- General "undefined property" guides
- Related TypeScript errors
- Might be less precise
Winner: Keyword (exact error codes matter)
Example 3: Onboarding Search
Query: "how do I get access to staging?"
Keyword search returns:
- Docs containing "access" and "staging"
- Might miss "environment setup" or "credentials"
Semantic search returns:
- Environment access guides
- Onboarding checklists
- VPN setup (conceptually related)
Winner: Hybrid (both perspectives valuable)
Building Semantic Search: Technical Overview
If you are building a knowledge base with semantic search, here is what you need:
1. Choose an Embedding Model
API-based (easiest):
- OpenAI text-embedding-ada-002: $0.0001 per 1K tokens, 1536 dimensions
- Cohere embed-english-v3: $0.0001 per 1K tokens, 1024 dimensions
Open source (self-hosted):
- sentence-transformers (SBERT): Free, 384-768 dimensions
- e5-large: Free, 1024 dimensions
Trade-off: API models are easier but cost money. Self-hosted is free but requires infrastructure.
2. Choose a Vector Database
- Pgvector (Postgres extension): Great if you already use Postgres
- Pinecone: Managed, easy to use, pay-as-you-go
- Qdrant: Open source, can self-host or use cloud
- Weaviate: Open source, GraphQL API
For small teams, Pgvector is often the simplest choice.
3. Build the Pipeline
1. Document uploaded
2. Split into chunks (500-1000 tokens each)
3. Generate embeddings for each chunk (via API or local model)
4. Store embeddings in vector database with metadata
5. On search:
- Generate embedding for query
- Find top K most similar chunks (cosine similarity)
- Return documents with citation to exact chunks
4. Combine with Keyword Search
Run BM25 keyword search in parallel and merge results using Reciprocal Rank Fusion or weighted scoring.
Performance Tips
- Cache embeddings: Do not re-embed unchanged documents
- Batch embedding generation: Process multiple documents at once
- Use approximate nearest neighbor (ANN): HNSW or IVF for faster search
- Precompute common queries: Cache embeddings for frequent searches
The Future: Multimodal and Agentic Search
Semantic search is evolving beyond text:
- Multimodal embeddings: Search images, videos, and audio using the same approach
- Cross-language search: Find English docs from Spanish queries
- Agentic search: AI agents that search, synthesize, and answer in one step
The next generation of knowledge bases will not just find documents, they will understand questions, retrieve relevant chunks, and generate comprehensive answers with citations.
This is already happening: Docuscry uses semantic search to find relevant chunks, then generates AI answers with source links.
Conclusion
Traditional keyword search is fast, precise, and great for exact matches. It fails when users do not know the exact words to search for.
Semantic search understands meaning, handles synonyms, and works with natural language. It is slower and less precise for exact terms.
Hybrid search combines both approaches to deliver the best results regardless of query type. This is what modern knowledge bases should offer.
For teams building or evaluating knowledge bases, prioritize search quality above all else. The best-organized documentation is useless if no one can find it.
If you want a knowledge base with hybrid semantic + keyword search built-in, try Docuscry. It combines both approaches with AI-generated answers for the best search experience possible.
Ready to upgrade your team's search? Start your free trial or see how Docuscry's search works.