Skip to main content
POST
For query-level reranking, see Native reranking for default and custom criteria, candidate depth, final scores, and fallback behavior. LambdaDB manages provider credentials.

Authorizations

x-api-key
string
header
required

Project API Key.

Path Parameters

collectionName
string
required

Collection name.

Body

application/json
size
integer | null
default:10

Number of documents to return, from 0 to 1000. Defaults to 10 when omitted or null. Zero requires at least one facet; facet counts cover all matching documents regardless of this size. Rerank requires a positive size; this remains the final returned-document limit, distinct from candidateSize and each knn.k.

Required range: 0 <= x <= 1000
query
object | null
conditionally required

Query object. For native embedding vector fields, use knn.queryText or ordered knn.queryInputs parts with explicit type (text or image) and string value. Cohere accepts mixed parts, OpenAI one text part. A raw knn.queryVector is also accepted for native fields and skips inference. Each knn query requires exactly one non-null queryText, queryInputs or queryVector and has its own k from 1 to 1000, independent of size and candidateSize. Text and multimodal inputs require a native embedding vector field. queryInputs uses the same part, image and byte limits as document inputs. All automatic query inputs are prepared before the first provider call; Cohere preparation checks inference quota before retrieving images. Query structure and per-leg bounds are validated by the server. Omit or use null to match all documents. Facets support queryString and bool queries only; vector, sparse vector, and hybrid queries cannot be combined with facets. Bayesian fusion uses a top-level bayesian array of exactly two unboosted subqueries, with no nested fusion or boosts on Boolean descendants. See the Hybrid query guide for candidate budgets.

consistentRead
boolean
default:false

Overlay eligible pending writes on the selected branch's committed data. Defaults to false. Allowed when ref selects a branch directly or an alias that currently targets a branch; the alias is resolved to its branch when the request is admitted. Tag reads and an alias that targets a tag reject true with 400. Pending bulk imports are excluded. Returns 429 if the pending payload exceeds the consistent-read limit.

includeVectors
boolean
default:false

If your application need to include vector values in the response, set includeVectors to true.

sort
object[] | null

List of field name, sort direction pairs. Omitted or null means no explicit sort. A non-null sort list, including an empty list, cannot be combined with rerank.

fields
object

An object to specify a list of field names to include and/or exclude in the result.

partitionFilter
PartitionFilter · object
ref
RefContext · object

Read ref selector. A ref that does not exist returns 404 ResourceNotFound; an alias whose target is dangling returns 400 BadRequest.

facets
object | null
required if size = 0

Exact document counts by indexed keyword value. Keys are keyword field names, including dotted paths. Applies all query and partition filters and the selected ref. At most 10,000 distinct (field, value) buckets and 262,144 UTF-8 value bytes across requested fields; exceeding either bound returns 400 instead of partial counts. Separate memory admission limits return 400 when one request exceeds its estimated budget, or 429 when concurrent requests temporarily exhaust a budget. Request fewer fields or partitions for memory-limit errors; retry temporary 429 errors with backoff.

rerank
object | null

Optional native reranking for this query, not a collection setting. Omitted or null preserves existing search behavior. LambdaDB manages provider credentials; no provider API key is supplied by the caller. Request validation, field types, UTF-8 byte limits, and size <= candidateSize are checked by the server.

candidateSize
integer | null

Required for top-level Bayesian fusion without rerank: 1 <= size <= candidateSize <= 1000. Controls retrieval and calibration depth per signal, independently of final size and each knn.k. With rerank, omit this field and use rerank.candidateSize. Other query types must omit it. Null is treated as omitted; query semantics and the cross-field size bound are validated by the server.

Required range: 1 <= x <= 1000

Response

Documents selected by query.

took
integer
required

Complete request elapsed time in milliseconds, including reranking when requested.

total
integer
required

Total number of documents returned.

docs
object[]
required

List of documents.

isDocsInline
boolean
required

Whether docs are included inline. When false, docs is empty and the result items must be downloaded from docsUrl.

maxScore
number

Maximum final score among returned documents. Applied reranking uses the final evaluation scores; fallback keeps search scores. Omitted for empty results or when no score is computed. Numeric zero is a valid maximum.

docsUrl
string

Presigned download URL when isDocsInline is false. GET the complete URL without forwarding the LambdaDB API key. Returns a JSON array of result items, not an object with a docs field. Applied reranking preserves score and retrievalScore in each downloaded envelope; rerank metadata stays in the top-level response.

facets
object

Present when facets were requested, including empty buckets for fields without matching values. Remains inline when documents are served through docsUrl. total remains the number of returned documents, not the facet population.

rerank
object

Present only when rerank was requested. Whole-stage metadata remains inline even when documents are downloaded through docsUrl.