@mhalder/qdrant-mcp-server 1.1.0 → 1.1.1

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/knowledge-base/README.md

@@ -1,33 +1,24 @@
-# Knowledge Base Example
+# Knowledge Base
 
-This example shows how to build a searchable documentation system with rich metadata for organization and filtering.
+Build a searchable documentation system with rich metadata for filtering and organization.
+
+**Time:** 15-20 minutes | **Difficulty:** Intermediate
 
 ## Use Case
 
-You're building a company knowledge base with:
+Company knowledge base with:
 
 - Documentation from multiple teams
-- Articles with different topics and difficulty levels
-- Content that needs to be searchable and filterable
-
-## What You'll Learn
-
-- Organizing documents with metadata
-- Using metadata for categorization
-- Filtering searches by metadata fields
-- Building a scalable knowledge base structure
+- Content with varying topics and difficulty levels
+- Searchable and filterable articles
 
 ## Setup
 
-### 1. Create the Collection
-
 ```
+# Create collection
 Create a collection named "company-kb"
-```
-
-### 2. Add Structured Documents
 
-```
+# Add structured documents
 Add these documents to company-kb:
 - id: "eng-001", text: "Our API uses REST principles with JSON payloads. Authentication is handled via JWT tokens in the Authorization header.", metadata: {"team": "engineering", "topic": "api", "difficulty": "intermediate", "category": "technical"}
 - id: "eng-002", text: "To deploy to production, merge your PR to main. The CI/CD pipeline automatically runs tests and deploys if all checks pass.", metadata: {"team": "engineering", "topic": "deployment", "difficulty": "beginner", "category": "process"}
@@ -39,51 +30,26 @@ Add these documents to company-kb:
 
 ## Search Examples
 
-### Basic Search (No Filters)
-
 ```
+# Basic search
 Search company-kb for "how do I deploy code"
-```
-
-Expected: Returns deployment-related docs (eng-002 likely ranks highest)
-
-### Filter by Team
 
-```
+# Filter by team
 Search company-kb for "process documentation" with filter {"must": [{"key": "team", "match": {"value": "engineering"}}]}
-```
-
-Returns only engineering team documents.
 
-### Filter by Difficulty
-
-```
+# Filter by difficulty
 Search company-kb for "getting started" with filter {"must": [{"key": "difficulty", "match": {"value": "beginner"}}]}
-```
 
-Returns beginner-friendly documentation.
-
-### Multiple Filters (AND)
-
-```
+# Multiple filters (AND)
 Search company-kb for "company procedures" with filter {"must": [{"key": "category", "match": {"value": "process"}}, {"key": "difficulty", "match": {"value": "beginner"}}]}
-```
-
-Returns beginner process documents only.
 
-### Filter by Topic
-
-```
+# Filter by topic
 Search company-kb for "pricing information" with filter {"must": [{"key": "team", "match": {"value": "sales"}}]}
 ```
 
-Restricts search to sales team content.
-
-## Metadata Design Best Practices
+## Metadata Design
 
-### 1. Consistent Schema
-
-Use the same metadata fields across all documents:
+### Schema Pattern
 
 ```json
 {
@@ -94,9 +60,9 @@ Use the same metadata fields across all documents:
 }
 ```
 
-### 2. Hierarchical Organization
+### Advanced Patterns
 
-Consider nesting metadata for complex taxonomies:
+**Hierarchical:**
 
 ```json
 {
@@ -107,9 +73,7 @@ Consider nesting metadata for complex taxonomies:
 }
 ```
 
-### 3. Multiple Tags
-
-Use arrays for multi-category documents:
+**Multi-category:**
 
 ```json
 {
@@ -118,9 +82,7 @@ Use arrays for multi-category documents:
 }
 ```
 
-### 4. Timestamps and Versioning
-
-Track freshness and versions:
+**Versioned:**
 
 ```json
 {
@@ -131,18 +93,7 @@ Track freshness and versions:
 }
 ```
 
-## Scaling Your Knowledge Base
-
-### Add More Content Types
-
-- Code examples with language tags
-- Video transcripts with duration metadata
-- Meeting notes with attendees and dates
-- Product specs with version numbers
-
-### Implement Access Control
-
-Use metadata for permissions:
+**Access Control:**
 
 ```json
 {
@@ -151,51 +102,38 @@ Use metadata for permissions:
 }
 ```
 
-Then filter searches based on user permissions.
+## Scaling
 
-### Track Usage
+### Content Types
 
-Add metadata for analytics:
-
-```json
-{
-  "views": 0,
-  "last_accessed": null,
-  "author": "user@company.com"
-}
-```
-
-## Maintenance
+- Code examples with language tags
+- Video transcripts with duration
+- Meeting notes with attendees/dates
+- Product specs with versions
 
-### Update Documents
+### Maintenance
 
-To update content, delete and re-add:
+**Update documents:**
 
 ```
 Delete documents ["eng-001"] from company-kb
-
 Add these documents to company-kb:
-- id: "eng-001", text: "Updated API documentation...", metadata: {...}
+- id: "eng-001", text: "Updated content...", metadata: {...}
 ```
 
-### Archive Old Content
-
-Use status metadata to hide outdated docs:
+**Archive old content:**
 
 ```json
-{
-  "status": "archived",
-  "archived_date": "2024-12-01"
-}
+{ "status": "archived", "archived_date": "2024-12-01" }
 ```
 
-Then filter searches to exclude archived content:
+Then filter searches:
 
 ```
 Search company-kb for "deployment" with filter {"must_not": [{"key": "status", "match": {"value": "archived"}}]}
 ```
 
-## Clean Up
+## Cleanup
 
 ```
 Delete collection "company-kb"
@@ -203,5 +141,5 @@ Delete collection "company-kb"
 
 ## Next Steps
 
-- [Advanced Filtering Examples](../filters/) - Learn complex filter patterns
-- See the main README for information on batch document operations
+- Explore [Advanced Filtering](../filters/) for complex filter patterns
+- Review [main README](../../README.md) for batch operations and advanced features