Skip to main content
Semantic (vector) search captures meaning; keyword (BM25) search captures exact terms. Hybrid search blends both with one parameter, alpha, so you can tune relevance per query or per index. As with all queries, load the index first (or open a session).

​
The alpha parameter

alphaBehavior
1.0Pure semantic (embeddings only)
0.0Pure keyword (BM25 only)
betweenBlends the two; default is semantic-heavy at 0.8

​
Example

import asyncio
from moss import MossClient, QueryOptions

async def main():
    client = MossClient(MOSS_PROJECT_ID, MOSS_PROJECT_KEY)
    await client.load_index("my-index")   # required before querying

    # Blend semantic and keyword scoring (60/40)
    hybrid = await client.query("my-index", "return policy", QueryOptions(top_k=3, alpha=0.6))

    # Pure keyword
    keyword_only = await client.query("my-index", "return policy", QueryOptions(top_k=3, alpha=0.0))

    # Pure semantic (default leans here at 0.8)
    semantic_only = await client.query("my-index", "return policy", QueryOptions(top_k=3, alpha=1.0))

    for doc in hybrid.docs:
        print(f"{doc.id} score={doc.score:.3f} {doc.text}")

asyncio.run(main())

​
Choosing alpha

  • Lower alpha (toward keyword) when queries contain exact identifiers, SKUs, names, or jargon.
  • Higher alpha (toward semantic) when queries are natural-language paraphrases.
  • Tune per index and per intent (returns, billing, onboarding, etc.).

Metadata filtering

Constrain results by document metadata.

Custom embeddings

Bring your own vectors.