kdrant-core/dev.kdrant.dsl/SearchBuilder

SearchBuilder

DSL for search (/points/query). Provide a query (vector, id, fusion, order-by, sample) and/or one or more prefetch sub-requests, plus a positive limit.

Constructors

SearchBuilder

constructor()

Properties

limit

var limit: Int

Maximum number of hits to return.

offset

var offset: Int?

Number of hits to skip (paging; costly for large offsets).

routeAffinity

var routeAffinity: String?

Stable token sent as X-Qdrant-Route-Affinity, so reads carrying the same one are served by the same replica: a user id, a session id, a hashed api key. The thing that should be sticky is one reader's session rather than the whole application, which is why this is per request and not on the client.

scoreThreshold

var scoreThreshold: Double?

Drop hits scoring below this threshold.

shardKey

var shardKey: ShardKey?

Search only the shards holding this key. null (default) searches every shard.

using

var using: String?

Name of the vector to search when the collection has named vectors.

withPayload

var withPayload: WithPayload?

Which payload to return (defaults to the server's behavior).

withVector

var withVector: Boolean?

Whether to return the stored vectors.

Functions

context

fun context(configure: ContextBuilder.() -> Unit)

Context search: steer results by positive/negative example pairs, without a target.

dbsf

fun dbsf()

Distribution-Based Score Fusion over the prefetch sources.

discover

fun discover(configure: DiscoverBuilder.() -> Unit)

Guided (discovery) search: rank by a target, constrained by context example pairs.

filter

fun filter(filter: Filter)

Restrict the search to points matching an already-built Filter — for filters produced by a translator.

fun filter(configure: FilterBuilder.() -> Unit)

Restrict the search to points matching this filter.

formula

fun formula(expression: Expression, defaults: Map<String, JsonPrimitive> = emptyMap())

Rescore the candidates with an arithmetic formula rather than by distance. Pair it with prefetch to narrow the candidates first: a formula over the whole collection is a full scan.

lookupFrom

fun lookupFrom(collection: String, vector: String? = null)

Look up query-by-id vectors from another collection.

mmr

fun mmr(diversity: Float? = null, candidatesLimit: Int? = null)

Rerank with Maximal Marginal Relevance, trading some relevance for variety. Applies to a vector query and is rejected on any other kind, because MMR needs the query vector to measure dissimilarity against.

orderBy

fun orderBy(key: String, direction: Direction? = null)

Order points by a payload key.

params

fun params(configure: SearchParamsBuilder.() -> Unit)

Tune the accuracy/speed trade-off.

prefetch

fun prefetch(configure: PrefetchBuilder.() -> Unit)

Add a prefetch sub-request (repeatable; prefetches may nest for multi-stage retrieval).

query

fun query(id: PointId)

Search by the stored vector of an existing point (a "more like this" query).

fun query(query: QueryInterface)

Set the query directly (e.g. a prebuilt QueryInterface).

fun query(values: List<Float>)

fun query(vararg values: Float)

Search by an explicit dense query vector.

queryDocument

fun queryDocument(text: String, model: String, options: Map<String, JsonElement>? = null)

Search by text the server embeds with model, instead of by a vector the caller computed. Needs a Qdrant with an inference provider configured. See InferenceInput.

queryMulti