Search Modes

Snipara offers three search modes for querying documentation. Choose the right mode based on your query type for optimal results.

Overview

Keyword Search

Keyword search uses an IDF-weighted, BM25-style scorer optimized for documentation. It is best for specific terms, function names, file paths, configuration keys, and error codes.

How It Works

1. Extract and stem significant query terms
2. Weight rarer terms with an IDF-like factor
3. Score content matches with BM25-style length normalization
4. Weight distinctive title matches 5× and generic title terms 1.5×
5. Add a section-level bonus and title-coverage boost
6. Apply a 3× multiplier when a significant query phrase matches the title
7. Apply lightweight query-intent reranking

Configuration

snipara_context_query({

  query: "handleAuthError function",

  search_mode: "keyword",

  max_tokens: 8000

})

Best Use Cases

• Exact term searches: Function names, error codes
• Technical queries: API endpoints, configuration keys
• Low latency needs: When speed is critical
• FREE plan users: Supported retrieval mode on the Free tier

Semantic Search

Semantic search uses embedding vectors to find conceptually similar content. Understands meaning, not just keywords.

How It Works

Primary semantic path:
1. Generate embedding for query using BAAI/bge-large-en-v1.5
2. Compare against pre-computed document chunk embeddings
3. Rank by cosine similarity
4. Return top N results with similarity > 0.3

Model: BAAI/bge-large-en-v1.5 (primary path)
Dimensions: 1024 (primary path)
Maximum indexed chunk budget: 768 tokens

Fallback or legacy index paths can use BAAI/bge-small-en-v1.5 at 384 dimensions and the application-level relevance filter (currently greater than 10) instead of the primary cosine threshold above. Check index metadata before comparing scores across projects or deployments.

Configuration

snipara_context_query({

  query: "How does the system handle authentication errors?",

  search_mode: "semantic",

  max_tokens: 8000

})

Best Use Cases

• Conceptual queries:"How does the system handle errors?"
• Natural language: Questions phrased conversationally
• Synonym handling:Finds "auth" when searching "login"
• Cross-reference: Finds related concepts across docs

Hybrid Search (Recommended)

Hybrid search combines keyword and semantic using Adaptive Reciprocal Rank Fusion. Automatically adjusts weights based on query type.

Adaptive Weight Profiles

Query Classification (Auto)

The system automatically classifies your query in ~0ms (no LLM call) to choose the optimal weights:

• Keyword-heavy: Query contains specific terms like pricing, schema, endpoint, api
• Semantic-heavy:Query starts with "how does", "why", "explain", "compare"
• Balanced: Everything else

Configuration

snipara_context_query({

  query: "How does the system handle authentication errors?",

  search_mode: "hybrid",  // default

  max_tokens: 8000

})

Performance and quality

Latency and retrieval quality depend on project size, cache state, embedding availability, query shape, and deployment. Use the per-project Search Analytics view for measured latency and outcome signals. Snipara does not publish fixed cross-project latency or F1 numbers here without a versioned, reproducible benchmark artifact.

When to Use Each Mode

Plan Gating

Downgrade behavior: If a FREE plan user requests semantic or hybrid, the request is automatically downgraded to keyword search with a warning in the response.

Next Steps