@mhalder/qdrant-mcp-server 1.1.0 → 1.2.0

package/examples/filters/README.md

@@ -1,18 +1,11 @@
-# Advanced Filtering Examples
+# Advanced Filtering
 
-This example demonstrates powerful metadata filtering capabilities using Qdrant's filter syntax.
+Master complex metadata filtering with boolean logic for powerful search refinement.
 
-## What You'll Learn
-
-- Complex boolean logic (AND, OR, NOT)
-- Range filters for numeric values
-- Combining multiple filter conditions
-- Real-world filtering scenarios
+**Time:** 20-30 minutes | **Difficulty:** Intermediate to Advanced
 
 ## Setup
 
-Create a collection with sample e-commerce data:
-
 ```
 Create a collection named "products"
 
@@ -29,117 +22,46 @@ Add these documents to products:
 
 ## Filter Examples
 
-### 1. Simple Match Filter (AND)
-
-Find electronics products:
+### Basic Filters
 
 ```
+# Match single category
 Search products for "device for music" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}]}
-```
-
-Expected: Returns p1, p4, p6 (all electronics)
+# Returns: p1, p4, p6
 
-### 2. Multiple Conditions (AND)
-
-Find in-stock electronics:
-
-```
+# Multiple conditions (AND)
 Search products for "gadgets" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": true}}]}
-```
-
-Expected: Returns p1, p4, p6 (in-stock electronics only)
+# Returns: p1, p4, p6 (in-stock electronics)
 
-### 3. OR Logic with Should
-
-Find either sports or accessories:
-
-```
+# OR logic
 Search products for "gear" with filter {"should": [{"key": "category", "match": {"value": "sports"}}, {"key": "category", "match": {"value": "accessories"}}]}
-```
-
-Expected: Returns p3, p5, p7, p8 (sports OR accessories)
+# Returns: p3, p5, p7, p8
 
-### 4. Negation with Must Not
-
-Find everything except clothing:
-
-```
+# NOT logic
 Search products for "shopping" with filter {"must_not": [{"key": "category", "match": {"value": "clothing"}}]}
+# Returns: All except p2
 ```
 
-Expected: Returns all products except p2
-
-### 5. Range Filter - Greater Than
-
-**Note:** Range filters require Qdrant's range condition syntax. The current implementation supports match filters. For range queries, you would need to use Qdrant's native range syntax:
-
-Conceptual example (not yet implemented in MCP server):
-
-```json
-{
-  "must": [
-    {
-      "key": "price",
-      "range": {
-        "gt": 100.0
-      }
-    }
-  ]
-}
-```
-
-### 6. Complex Boolean Logic
-
-Find in-stock products that are either:
-
-- Electronics with rating > 4.5, OR
-- Sports items under $50
+### Complex Combinations
 
 ```
+# In-stock products (electronics OR sports)
 Search products for "quality products" with filter {"must": [{"key": "in_stock", "match": {"value": true}}], "should": [{"key": "category", "match": {"value": "electronics"}}, {"key": "category", "match": {"value": "sports"}}]}
-```
-
-### 7. Combining Multiple Must Conditions
-
-Find highly-rated in-stock electronics:
-
-```
-Search products for "best gadgets" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": true}}, {"key": "rating", "match": {"value": 4.5}}]}
-```
-
-Note: Exact match on rating. For range queries, use Qdrant's range filter syntax.
-
-### 8. Brand Filtering
 
-Find AudioTech products:
-
-```
-Search products for "audio equipment" with filter {"must": [{"key": "brand", "match": {"value": "AudioTech"}}]}
-```
-
-Expected: Returns p1 only
-
-### 9. Out of Stock Products
-
-Find what needs restocking:
+# Non-electronic in-stock items
+Search products for "shopping" with filter {"must": [{"key": "in_stock", "match": {"value": true}}], "must_not": [{"key": "category", "match": {"value": "electronics"}}]}
+# Returns: p2, p5, p8
 
-```
+# Out of stock items
 Search products for "items" with filter {"must": [{"key": "in_stock", "match": {"value": false}}]}
-```
+# Returns: p3, p7
 
-Expected: Returns p3, p7 (out of stock items)
-
-### 10. Category Exclusion with Multiple Conditions
-
-Find non-electronic in-stock items:
-
-```
-Search products for "shopping" with filter {"must": [{"key": "in_stock", "match": {"value": true}}], "must_not": [{"key": "category", "match": {"value": "electronics"}}]}
+# Brand filtering
+Search products for "audio equipment" with filter {"must": [{"key": "brand", "match": {"value": "AudioTech"}}]}
+# Returns: p1 only
 ```
 
-Expected: Returns p2, p5, p8 (in-stock, non-electronics)
-
-## Filter Syntax Reference
+## Filter Syntax
 
 ### Structure
 
@@ -153,24 +75,16 @@ Expected: Returns p2, p5, p8 (in-stock, non-electronics)
 
 ### Match Filter
 
-Exact value matching:
-
 ```json
 {
   "key": "field_name",
   "match": {
-    "value": "exact_value"
+    "value": "exact_value" // Works with strings, numbers, booleans
   }
 }
 ```
 
-Works with:
-
-- Strings: `"value": "electronics"`
-- Numbers: `"value": 4.5`
-- Booleans: `"value": true`
-
-### Range Filter (Qdrant Native)
+### Range Filters (Native Qdrant)
 
 For numeric comparisons (future enhancement):
 
@@ -188,68 +102,54 @@ For numeric comparisons (future enhancement):
 
 ## Real-World Scenarios
 
-### E-commerce Product Search
-
-"Show me affordable fitness equipment"
-
 ```
+# E-commerce: affordable fitness equipment
 Search products for "fitness equipment" with filter {"must": [{"key": "category", "match": {"value": "sports"}}, {"key": "in_stock", "match": {"value": true}}]}
-```
-
-### Inventory Management
 
-"Which electronics need restocking?"
-
-```
+# Inventory: electronics needing restock
 Search products for "electronics" with filter {"must": [{"key": "category", "match": {"value": "electronics"}}, {"key": "in_stock", "match": {"value": false}}]}
-```
-
-### Quality Control
 
-"Show me all highly-rated available products"
-
-```
+# Quality control: highly-rated available products
 Search products for "top rated products" with filter {"must": [{"key": "in_stock", "match": {"value": true}}]}
 ```
 
-## Limitations and Workarounds
+## Workarounds
 
-### Current Limitations
+### Price Ranges
 
-1. **No native range filters**: Can't directly filter by price ranges like "between $50-$100"
-2. **No text search on metadata**: Metadata matching is exact, not fuzzy
-3. **No nested object queries**: Flat metadata structure only
+Add `price_tier` to metadata:
 
-### Workarounds
+```json
+{"price_tier": "budget", "price": 29.99}    // <$50
+{"price_tier": "mid", "price": 149.99}      // $50-$200
+{"price_tier": "premium", "price": 299.99}  // >$200
+```
 
-1. **Price ranges**: Add price_tier to metadata:
+### Multiple Categories
 
-   ```json
-   {"price_tier": "budget", "price": 29.99}  // budget: <$50
-   {"price_tier": "mid", "price": 149.99}    // mid: $50-$200
-   {"price_tier": "premium", "price": 299.99} // premium: >$200
-   ```
+Use array-based tags:
 
-2. **Multiple categories**: Use array-based tags:
+```json
+{ "tags": ["electronics", "wearable", "fitness"] }
+```
+
+### Date Filtering
 
-   ```json
-   { "tags": ["electronics", "wearable", "fitness"] }
-   ```
+Use comparable string format:
 
-3. **Date filtering**: Store dates as strings in comparable format:
-   ```json
-   { "created_date": "2024-03-15" } // YYYY-MM-DD for lexicographic comparison
-   ```
+```json
+{ "created_date": "2024-03-15" } // YYYY-MM-DD
+```
 
 ## Best Practices
 
-1. **Keep metadata flat**: Avoid deep nesting for better filter performance
-2. **Use consistent types**: Don't mix strings and numbers for the same field
-3. **Index commonly filtered fields**: Design metadata around common queries
-4. **Test filters first**: Validate filter syntax before complex queries
-5. **Combine with semantic search**: Use filters to narrow, then semantic search to rank
+1. **Flat metadata** - Avoid deep nesting
+2. **Consistent types** - Don't mix strings/numbers for same field
+3. **Index common fields** - Design around frequent queries
+4. **Test filters first** - Validate syntax before complex queries
+5. **Combine with search** - Use filters to narrow, semantic search to rank
 
-## Clean Up
+## Cleanup
 
 ```
 Delete collection "products"
@@ -258,5 +158,5 @@ Delete collection "products"
 ## Next Steps
 
 - Review [Qdrant filtering documentation](https://qdrant.tech/documentation/concepts/filtering/)
-- Explore the [Knowledge Base Example](../knowledge-base/) for organizational patterns
-- Check the main README for full filter syntax support
+- Explore [Knowledge Base](../knowledge-base/) example for organizational patterns
+- See [main README](../../README.md) for complete filter syntax reference

package/examples/hybrid-search/README.md

@@ -0,0 +1,199 @@
+# Hybrid Search
+
+Combine semantic vector search with keyword (BM25) search for more accurate and comprehensive results.
+
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
+
+## What is Hybrid Search?
+
+Hybrid search combines two search approaches:
+
+1. **Semantic Search**: Understands meaning and context using vector embeddings
+2. **Keyword Search**: Exact term matching using BM25 sparse vectors
+
+The results are merged using **Reciprocal Rank Fusion (RRF)**, which combines rankings from both methods to produce the best overall results.
+
+## When to Use Hybrid Search
+
+Hybrid search is ideal for:
+
+- **Technical documentation**: Users search for exact function names + concepts
+- **Product search**: Match SKUs/model numbers + descriptions
+- **Legal documents**: Exact citations + semantic context
+- **Code search**: Function names + natural language descriptions
+- **Mixed queries**: "authentication JWT" (semantic + exact keyword)
+
+## Benefits
+
+- **Best of both worlds**: Precision (keyword) + recall (semantic)
+- **Better results for ambiguous queries**
+- **Handles typos** (semantic) and **exact matches** (keyword)
+- **More control** over result relevance
+
+## Workflow
+
+### 1. Create a Collection with Hybrid Search Enabled
+
+```
+Create a collection named "technical_docs" with Cosine distance and enableHybrid set to true
+```
+
+**Important**: Set `enableHybrid: true` to enable hybrid search capabilities.
+
+### 2. Add Documents
+
+Documents are automatically indexed for both semantic and keyword search:
+
+```
+Add these documents to technical_docs:
+- id: 1, text: "The authenticateUser function validates JWT tokens for user sessions",
+  metadata: {"category": "authentication", "type": "function"}
+- id: 2, text: "JWT (JSON Web Token) is a compact URL-safe means of representing claims",
+  metadata: {"category": "authentication", "type": "definition"}
+- id: 3, text: "OAuth2 provides authorization framework for third-party applications",
+  metadata: {"category": "authentication", "type": "protocol"}
+- id: 4, text: "The login endpoint requires username and password credentials",
+  metadata: {"category": "authentication", "type": "endpoint"}
+```
+
+### 3. Perform Hybrid Search
+
+Search using both semantic understanding and keyword matching:
+
+```
+Search technical_docs for "JWT authentication function" with limit 3 using hybrid_search
+```
+
+**Result**: Documents are ranked by combining:
+
+- Semantic similarity to "authentication function"
+- Exact keyword matches for "JWT"
+
+### 4. Hybrid Search with Filters
+
+Combine hybrid search with metadata filtering:
+
+```
+Search technical_docs for "JWT token validation" with limit 2 and filter {"type": "function"} using hybrid_search
+```
+
+## Comparison: Semantic vs Hybrid Search
+
+### Semantic Search Only
+
+```
+Search technical_docs for "JWT authentication" with limit 3 using semantic_search
+```
+
+**Result**: May miss documents with exact "JWT" match if they're not semantically similar.
+
+### Hybrid Search
+
+```
+Search technical_docs for "JWT authentication" with limit 3 using hybrid_search
+```
+
+**Result**: Finds both:
+
+- Documents semantically related to authentication
+- Documents with exact "JWT" keyword match
+- Best combination ranked by RRF
+
+## Example Scenarios
+
+### Scenario 1: Exact Term + Context
+
+**Query**: "authenticateUser JWT"
+
+**Hybrid Search finds**:
+
+1. Documents with `authenticateUser` function name (keyword match)
+2. Documents about JWT authentication (semantic match)
+3. Best combination of both
+
+**Pure semantic search might miss**: Exact function name if using different terminology.
+
+### Scenario 2: Acronym + Description
+
+**Query**: "API rate limiting"
+
+**Hybrid Search finds**:
+
+1. Documents with "API" acronym (keyword match)
+2. Documents about rate limiting concepts (semantic match)
+3. Documents mentioning "API rate limiting" get highest score
+
+### Scenario 3: Typos + Exact Terms
+
+**Query**: "OAuth2 authentification"
+
+**Hybrid Search finds**:
+
+1. "OAuth2" exact matches (keyword - ignores typo in other term)
+2. Authentication concepts (semantic - understands "authentification" ≈ "authentication")
+
+## Technical Details
+
+### How It Works
+
+1. **Dense Vector Generation**: Your query is embedded using the configured embedding provider (Ollama, OpenAI, etc.)
+2. **Sparse Vector Generation**: Query is tokenized and BM25 scores are calculated
+3. **Parallel Search**: Both vectors are searched simultaneously
+4. **Result Fusion**: RRF combines rankings from both searches
+5. **Final Ranking**: Merged results with combined relevance scores
+
+### BM25 Sparse Vectors
+
+The server uses a lightweight BM25 implementation for sparse vectors:
+
+- Tokenization: Lowercase + whitespace splitting
+- IDF scoring: Inverse document frequency
+- Configurable parameters: k1=1.2, b=0.75
+
+### Reciprocal Rank Fusion (RRF)
+
+RRF formula: `score = Σ(1 / (k + rank))` where k=60 (default)
+
+Benefits:
+
+- No score normalization needed
+- Robust to differences in score scales
+- Works well for combining different ranking methods
+
+## Best Practices
+
+1. **Enable hybrid for technical content**: Use when exact terms matter
+2. **Use semantic for general content**: Natural language queries without technical terms
+3. **Combine with filters**: Narrow down results by category or type
+4. **Test both approaches**: Compare semantic vs hybrid for your use case
+5. **Monitor performance**: Hybrid search requires more computation
+
+## Performance Considerations
+
+- **Storage**: Hybrid collections require more space (dense + sparse vectors)
+- **Indexing**: Document indexing is slightly slower
+- **Query time**: Hybrid search performs two searches and fusion
+- **Scalability**: Qdrant optimizes both vector types efficiently
+
+## Troubleshooting
+
+### "Collection does not have hybrid search enabled"
+
+**Solution**: Create a new collection with `enableHybrid: true`. Existing collections cannot be converted.
+
+### Poor results with hybrid search
+
+**Try**:
+
+1. Adjust query phrasing to include key terms
+2. Use metadata filters to narrow scope
+3. Increase `limit` to see more results
+4. Compare with pure semantic search
+
+### Slow query performance
+
+**Solutions**:
+
+1. Reduce prefetch limit (contact support for tuning)
+2. Add filters to narrow search space
+3. Use fewer documents or partition data