Skip to main content
Learn

Semantic Search

db.records.vectorSearch() / POST /api/v1/ai/search performs semantic vector search across records that have an associated embedding index. Candidates are narrowed by label and where filters first, then ranked by cosine or euclidean similarity.

The search needs a ready embedding index, named by index or found from labels and propertyName. See Manage Embedding Indexes.

RushDB CloudSelf-hosted engine (direct mode)
Search by queryVector (an external index, or a managed one)✓✓
Search by text query (managed embeddings)✓—

On a self-hosted engine, embed the query with your own model and pass queryVector; a text query throws CloudOnlyError before anything is sent. The Shell examples call the RushDB Cloud REST API.

To combine meaning with exact keywords, add a text leg and the search becomes hybrid. For keywords alone, use keyword search. To have RushDB Cloud turn a natural-language request into a SearchQuery, use Smart Search.

Managed Search (Query Text) [Cloud]​

For a managed index, pass a natural-language query string. RushDB Cloud embeds it with the same model that built the index.

response = db.records.vector_search({
    "propertyName": "description",
    "query": "machine learning for beginners",
    "labels": ["Article"],
    "limit": 5,
})

for result in response.data:
    print(f"[{result.score:.3f}] {result.get('title')}")

External Search (Query Vector)​

For an external index, pass queryVector — a pre-computed embedding from your own model. No text is sent to any embedding model.

vec = my_embedder.embed("machine learning for beginners")

response = db.records.vector_search({
    "propertyName": "body",
    "queryVector": vec,
    "labels": ["Article"],
    "limit": 10,
})
  • query is not allowed with external indexes — the server has no model to embed it.
  • queryVector is accepted for managed indexes (bypasses server embedding).
  • When queryVector is supplied, dimensions can be omitted — the server infers it from vector length.

Filter + Semantic Search​

The where clause acts as a prefilter — only records satisfying the filter are candidates for similarity ranking. All operators from Where Operators are available.

response = db.records.vector_search({
    "propertyName": "description",
    "query": "wireless headphones",
    "labels": ["Product"],
    "where": {
        "category": {"$eq": "electronics"},
        "inStock":  {"$eq": True},
        "price":    {"$lt": 100},
    },
    "limit": 20,
})

Search across multiple entity types simultaneously. All listed labels must have an embedding index on the same propertyName.

response = db.records.vector_search({
    "propertyName": "body",
    "query": "machine learning trends",
    "labels": ["Article", "Post", "Comment"],
    "limit": 10,
})

for result in response.data:
    print(result.get("__label"), f"{result.score:.3f}", result.get("title") or result.get("text"))

Result Shape​

Results are ordered by __score descending — closest match first.

# Sample result object (response.data[0]):
# {
#   "__id":          "rec_abc123",
#   "__label":       "Product",
#   "__score":       0.9214,
#   "name":          "ANC Wireless Headphones",
#   "description":   "Same-day shipping with hassle-free returns policy",
#   "price":         89.99
# }

for result in response.data:
    result.id                  # "rec_abc123"  — RushDB record ID
    result.get("__label")      # "Product"     — record label
    result.score      # 0.9214        — similarity score 0–1 (higher = more similar)
    result.get("name")         # your fields via .get()
    result["price"]            # or via [] — raises KeyError if missing

Parameters Reference​

ParameterTypeRequiredDescription
indexstringnoThe index to search, by name (or id). propertyName and labels then default to the index's own.
propertyNamestringunless indexThe indexed property to search against (e.g. "description")
labelsstring[]unless indexLabel(s) to search within (min 1)
querystringconditionallyFree-text query. Required for managed indexes; not allowed for external indexes.
queryVectornumber[]conditionallyPre-computed query vector. Required for external indexes. Also accepted for managed indexes.
similarityFunction"cosine" | "euclidean"noRequired when multiple indexes target the same (label, propertyName).
dimensionsnumbernoDisambiguates when multiple indexes match. Inferred from queryVector.length when queryVector given.
whereobjectnoPrefilter — applied before similarity scoring.
skipnumbernoPagination offset (default 0)
limitnumbernoMaximum results to return (default 20)
mode"auto" | "exact" | "ann"noauto (default) scores a small index exactly and uses the ANN graph for a large one; exact and ann force a path (ann needs a cosine index).
efnumbernoANN gather breadth, when the search runs on the ANN graph.
scoreThresholdnumbernoKeep only results scoring at least this much. Scores depend on the model, so a page may hold fewer than limit results.
textobjectnoAdds a keyword leg, making the search hybrid.

How the search ran​

The result reports the path the engine took: TypeScript result.vectorSearch, Python result.meta["vectorSearch"], REST meta.vectorSearch.

FieldMeaning
modeexact or ann: the path that produced the results.
efGather breadth, for an ANN search.
fallbackWhy a search that would use the ANN graph was answered exactly: metric, budget, lowConfidence, or annWarming (the graph is still being built).
poolVectors in the index.

Disambiguation​

When two indexes exist for the same (label, propertyName), name the one you want with index, or specify similarityFunction to select it:

response = db.records.vector_search({
    "labels": ["Product"],
    "propertyName": "embedding",
    "queryVector": vec,
    "similarityFunction": "cosine",   # required — otherwise 422
})

Pagination​

PAGE = 20

page1 = db.records.vector_search({
    "propertyName": "description",
    "query": "sustainable packaging",
    "labels": ["Product"],
    "limit": PAGE,
    "skip": 0,
})

page2 = db.records.vector_search({
    "propertyName": "description",
    "query": "sustainable packaging",
    "labels": ["Product"],
    "limit": PAGE,
    "skip": PAGE,
})

Error Reference​

HTTPCause
404 Not FoundNo enabled embedding index found for (label, propertyName)
422 Unprocessable EntityMultiple indexes match and similarityFunction was not specified
422 Unprocessable Entityquery text supplied for an external index
422 Unprocessable EntityVector length does not match index dimensions
503 Service UnavailableEmbedding model unavailable (managed indexes only)

In direct mode the SDKs raise the engine's error instead of an HTTP status: not_found for a missing index, invalid_request for a vector of the wrong length.

See also​