Semantic Search

Semantic search matches by meaning: a question about “time off” finds a document about “annual leave.” Keyword search matches the words themselves, which is what you need for an error code such as E_AUTH_429. POST /query runs both together by default, a combination called hybrid search, so one request handles paraphrases and exact identifiers. BM25 is the keyword-ranking method it uses. In this guide:

Choose the matching method: query_by, and the three signals a query can use.
Balance meaning and keywords: the alpha value.
Where meaning alone falls short: why HydraDB has no pure vector mode.

1. Choose the matching method

query_by picks how the query text is matched:

"hybrid" (the default): matching by meaning and BM25 keyword matching, blended by alpha. Use it unless you have a reason not to.
"text": BM25 only. Use it when the literal wording is the point, such as a legal clause, a SKU, or a function name. operator says how the terms must match: "or" (the default), "and", or "phrase". "and" and "phrase" are valid only with query_by: "text".

A hybrid query can also draw on a third signal, the context graph, which is returned with the results when graph_context is on (the default):

Signal	Finds	Best for
Semantic	Text with similar meaning	Natural-language questions, paraphrases, conceptual lookup
BM25 keyword	Text with matching tokens	Error codes, identifiers, names, SKUs, exact phrases
Graph	Related entities and relationships	Multi-hop questions, dependencies, ownership, project context

Hybrid query and exact phrase query: Python, TypeScript, or cURL

The first request is a hybrid search kept inside the phoenix project with a metadata filter. The second returns only passages that contain the exact phrase “mechanical engineer”.

result = client.query(
    database="acme",
    collection="team-mobile",
    query="How do we rotate API keys?",
    type="knowledge",
    query_by="hybrid",
    max_results=8,
    alpha=0.8,
    recency_bias=0.2,
    graph_context=True,
    metadata_filters={"project": "phoenix"},
)

const result = await client.query({
  database: "acme",
  collection: "team-mobile",
  query: "How do we rotate API keys?",
  type: "knowledge",
  queryBy: "hybrid",
  maxResults: 8,
  alpha: 0.8,
  recencyBias: 0.2,
  graphContext: true,
  metadataFilters: { project: "phoenix" },
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme",
    "collection": "team-mobile",
    "query": "How do we rotate API keys?",
    "type": "knowledge",
    "query_by": "hybrid",
    "max_results": 8,
    "alpha": 0.8,
    "recency_bias": 0.2,
    "graph_context": true,
    "metadata_filters": {
      "project": "phoenix"
    }
  }'

metadata_filters are exact constraints. They run before ranking and are re-checked after the matching passages load, so use them for any scope the query must not cross. Top-level keys match metadata and support equals, contains, and contains_any; there is no range or fuzzy match. Nest free-form per-document fields under additional_metadata. See Metadata.

result = client.query(
    database="acme",
    query="mechanical engineer",
    type="knowledge",
    query_by="text",
    operator="phrase",
    max_results=10,
)

const result = await client.query({
  database: "acme",
  query: "mechanical engineer",
  type: "knowledge",
  queryBy: "text",
  operator: "phrase",
  maxResults: 10,
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme",
    "query": "mechanical engineer",
    "type": "knowledge",
    "query_by": "text",
    "operator": "phrase",
    "max_results": 10
  }'

2. Balance meaning and keywords with `alpha`

alpha sets the blend in a hybrid query. Higher values lean on meaning; lower values lean on keywords.

`alpha`	Behavior	Use when
`1.0`	Semantic-heavy	Conceptual questions and paraphrases
`0.8`	Default semantic-leaning hybrid	Most agent query workflows
`0.5`	Balanced	Mixed natural language and exact terms
`0.2`	Keyword-leaning	Queries with product names, error strings, or IDs
`0.0`	Keyword only	Debugging exact-match behavior

Start with the default and tune from observed results. "auto" also resolves to 0.8. If users query for exact IDs and get loosely related results, lower alpha. If they ask broad conceptual questions and get sparse results, raise it. alpha applies only to query_by: "hybrid"; it is ignored for "text".

Technical lookup with a low alpha: Python, TypeScript, or cURL

Lower alpha when names, IDs, and literal strings matter but the query still has a natural-language part.

result = client.query(
    database="acme",
    query="TimeoutError in payments-worker v4.2.1",
    type="knowledge",
    query_by="hybrid",
    max_results=5,
    alpha=0.3,
    recency_bias=0.4,
)

const result = await client.query({
  database: "acme",
  query: "TimeoutError in payments-worker v4.2.1",
  type: "knowledge",
  queryBy: "hybrid",
  maxResults: 5,
  alpha: 0.3,
  recencyBias: 0.4,
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme",
    "query": "TimeoutError in payments-worker v4.2.1",
    "type": "knowledge",
    "query_by": "hybrid",
    "max_results": 5,
    "alpha": 0.3,
    "recency_bias": 0.4
  }'

3. Where meaning alone falls short

Pure vector search misses things that matter in production:

Exact identifiers such as E_AUTH_429 or payments-worker-v4 may be generalized away.
A project name can collide with a normal word, like strawberry the project and strawberry the fruit.
Old and new documents can look equally relevant without recency or metadata signals.
Different users can need different context for the same query.
Relationship questions need graph context, not only similar text chunks.

That is why HydraDB exposes semantic retrieval through query_by: "hybrid" inside the one /query endpoint rather than as a separate pure-vector mode. The keyword, recency, metadata, scope, and graph signals ride along with it.

Query: the request, the recipes, and the full parameter reference
Context Graphs: the third signal, and how to read it
Metadata: designing filterable schemas
How to Use API Results: turning the response into a model prompt

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Choose the matching method

2. Balance meaning and keywords with `alpha`

3. Where meaning alone falls short

​1. Choose the matching method

​2. Balance meaning and keywords with alpha

​3. Where meaning alone falls short

​Related

1. Choose the matching method

2. Balance meaning and keywords with `alpha`

3. Where meaning alone falls short

Related