Skip to main content
Learn

Semantic Search

db.ai.search() / 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 property referenced by propertyName must have a ready embedding index. See Manage Embedding Indexes.

Managed Search (Query Text)​

For a managed index, pass a natural-language query string. The server embeds it using the same model that built the index.

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

for result in response.data:
    print(f"[{result.get('__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.ai.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.ai.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.ai.search({
    "propertyName": "body",
    "query": "machine learning trends",
    "labels": ["Article", "Post", "Comment"],
    "limit": 10,
})

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

Result Shape​

Results are ordered by __score descending — closest match first.

for result in response.data:
    result.id                  # RushDB record ID (str)
    result.get("__label")      # Record label (str)
    result.get("__score")      # Similarity score, 0–1 (float)
    result.get("title")        # Your fields via .get()
    result["description"]      # Or via [] — raises KeyError if missing

Parameters Reference​

ParameterTypeRequiredDescription
propertyNamestringyesThe indexed property to search against (e.g. "description")
labelsstring | string[]yesLabel(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)

Disambiguation​

When two indexes exist for the same (label, propertyName), specify similarityFunction to select the target index:

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

Pagination​

PAGE = 20

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

page2 = db.ai.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)

See also​