QdrantClient

The user-facing Kdrant API. Coroutine-first: every operation is a suspend function.

Obtain an instance from a transport factory, e.g. Kdrant(host, port) { } in kdrant-transport-rest. Implements AutoCloseable — use it with use { }.

Every operation performs network I/O and may throw a KdrantException.

Functions

Link copied to clipboard
abstract suspend fun batchUpdate(name: String, wait: Boolean = false, configure: BatchUpdateBuilder.() -> Unit)

Apply a mixed sequence of point, vector and payload changes in one request, in the order given.

Link copied to clipboard
abstract suspend fun clearIssues()

Clear the server's collected performance issues.

Link copied to clipboard
abstract suspend fun clearPayload(name: String, selector: DeleteSelector, wait: Boolean = false)

Clear all payload from the selected points.

Link copied to clipboard
expect abstract fun close()
Link copied to clipboard

How the collection's shards are spread across the cluster, as the answering peer sees it.

Link copied to clipboard
abstract suspend fun collectionExists(name: String): Boolean

Whether a collection exists. Returns false (not an error) for a missing collection.

Link copied to clipboard
abstract suspend fun count(name: String, exact: Boolean = true): Long

Count the points in a collection.

abstract suspend fun count(name: String, exact: Boolean = true, filter: FilterBuilder.() -> Unit): Long

Count the points in a collection that match a filter.

Link copied to clipboard
abstract suspend fun createCollection(name: String, configure: CreateCollectionBuilder.() -> Unit)

Create a collection.

Link copied to clipboard
suspend fun QdrantClient.createCollection(name: String, size: Long, distance: Distance = Distance.COSINE)

Create a single-vector collection from just a size and distance — the common case.

Link copied to clipboard

Create a collection unless it already exists. Returns true if it was created, false if it already existed.

Link copied to clipboard
abstract suspend fun createPayloadIndex(name: String, field: String, schema: PayloadSchemaType, wait: Boolean = false)

Create a payload field index so filtering on field scales. Without an index, filters do a full scan.

abstract suspend fun createPayloadIndex(name: String, field: String, wait: Boolean = false, configure: PayloadIndexBuilder.() -> Unit)

Create a payload field index, choosing the parameters that index type accepts.

Link copied to clipboard
abstract suspend fun createShardKey(name: String, shardKey: ShardKey, shardsNumber: Int? = null, replicationFactor: Int? = null, placement: List<Long>? = null, timeout: Int? = null)

Create a custom sharding key, so a query that names it touches only its shards.

Link copied to clipboard
abstract suspend fun createShardSnapshot(name: String, shardId: Int, wait: Boolean = true): SnapshotDescription

Create a snapshot of a single shard rather than the whole collection.

Link copied to clipboard
abstract suspend fun createSnapshot(name: String, wait: Boolean = true): SnapshotDescription

Create a snapshot of the collection name; the returned SnapshotDescription.name identifies it for later download or recover.

Link copied to clipboard
abstract suspend fun createStorageSnapshot(wait: Boolean = true): SnapshotDescription

Create a snapshot of the whole storage (all collections). See createSnapshot for the wait note.

Link copied to clipboard
abstract suspend fun delete(name: String, selector: DeleteSelector, wait: Boolean = false)

Delete the points chosen by an already-built DeleteSelector — the form the framework adapters use, where the filter comes from a translator rather than the DSL.

abstract suspend fun delete(name: String, wait: Boolean = false, filter: FilterBuilder.() -> Unit)

Delete every point matching the given filter.

abstract suspend fun delete(name: String, ids: List<PointId>, wait: Boolean = false)

Delete points by id.

Link copied to clipboard
abstract suspend fun deleteCollection(name: String)

Delete a collection. Deleting a collection that does not exist is a no-op on the server.

Link copied to clipboard
abstract suspend fun deletePayload(name: String, keys: List<String>, selector: DeleteSelector, wait: Boolean = false)

Delete keys from the selected points' payload.

Link copied to clipboard
abstract suspend fun deletePayloadIndex(name: String, field: String, wait: Boolean = false)

Delete a payload field index.

Link copied to clipboard
abstract suspend fun deleteShardKey(name: String, shardKey: ShardKey, timeout: Int? = null)

Drop a custom sharding key and the points in its shards. There is no undo.

Link copied to clipboard
abstract suspend fun deleteShardSnapshot(name: String, shardId: Int, snapshotName: String, wait: Boolean = true)

Delete a shard snapshot.

Link copied to clipboard
abstract suspend fun deleteSnapshot(name: String, snapshotName: String, wait: Boolean = true)

Delete the snapshot snapshotName of collection name.

Link copied to clipboard
abstract suspend fun deleteStorageSnapshot(snapshotName: String, wait: Boolean = true)

Delete the whole-storage snapshot snapshotName.

Link copied to clipboard
abstract suspend fun deleteVectors(name: String, vectors: List<String>, selector: DeleteSelector, wait: Boolean = false)

Delete the named vectors from the selected points.

Link copied to clipboard
abstract fun downloadShardSnapshot(name: String, shardId: Int, snapshotName: String): Flow<ByteArray>

Stream a shard snapshot's bytes as a cold Flow. See downloadSnapshot.

Link copied to clipboard
abstract fun downloadSnapshot(name: String, snapshotName: String): Flow<ByteArray>

Stream a collection snapshot's bytes as a cold Flow, to save a backup without buffering the whole (potentially multi-GB) file in memory.

Link copied to clipboard
abstract fun downloadStorageSnapshot(snapshotName: String): Flow<ByteArray>

Stream a whole-storage snapshot's bytes as a cold Flow. See downloadSnapshot.

Link copied to clipboard
abstract suspend fun ensureCollection(name: String, configure: CreateCollectionBuilder.() -> Unit): Boolean

Create the collection if it is missing, and otherwise check that the one already there is the one asked for — the primitive a rerunnable bootstrap script needs.

Link copied to clipboard
abstract suspend fun facet(name: String, key: String, limit: Int? = null, exact: Boolean = false, filter: FilterBuilder.() -> Unit = {}): List<FacetHit>

Count the distinct values of a payload key among matching points (a payload histogram).

Link copied to clipboard
abstract suspend fun getCollection(name: String): CollectionInfo

Fetch a collection's status and point counts.

Link copied to clipboard

Fetch a collection's info, or null if it does not exist — instead of throwing KdrantException.CollectionNotFound.

Link copied to clipboard
abstract suspend fun healthz(): Boolean

Kubernetes-style health probe: true when the node is healthy. Returns false (rather than throwing) when the server responds not-healthy; still throws KdrantException.Transport if the server can't be reached at all.

Link copied to clipboard
suspend fun QdrantClient.ingest(name: String, points: Flow<PointStruct>, batchSize: Int = 256, maxBatchBytes: Int = DEFAULT_INGEST_BATCH_BYTES, concurrency: Int = 4, maxRetriesPerBatch: Int = 3, retryDelay: Duration = 500.milliseconds, resumeFrom: IngestCheckpoint? = null, onCheckpoint: suspend (IngestCheckpoint) -> Unit = {}): IngestReport

Load a collection from a source larger than memory, and be able to carry on after being killed.

Link copied to clipboard
abstract suspend fun listAliases(): List<AliasDescription>

List every alias across all collections.

Link copied to clipboard
abstract suspend fun listCollectionAliases(name: String): List<AliasDescription>

List the aliases pointing at name.

Link copied to clipboard
abstract suspend fun listCollections(): List<CollectionDescription>

List all collection names on the server.

Link copied to clipboard
abstract suspend fun listIssues(): JsonElement

Detected performance issues as raw JSON (shape is server-version-specific).

Link copied to clipboard
abstract suspend fun listShardSnapshots(name: String, shardId: Int): List<SnapshotDescription>

List the snapshots of one shard.

Link copied to clipboard
abstract suspend fun listSnapshots(name: String): List<SnapshotDescription>

List the collection name's snapshots.

Link copied to clipboard

List whole-storage snapshots.

Link copied to clipboard
abstract suspend fun livez(): Boolean

Liveness probe: true when the node is alive. See healthz for the error contract.

Link copied to clipboard
abstract suspend fun metrics(): String

The server's Prometheus metrics as a text-exposition-format string.

Link copied to clipboard
abstract suspend fun overwritePayload(name: String, payload: Payload, selector: DeleteSelector, wait: Boolean = false)

Replace the selected points' payload with payload.

Link copied to clipboard
abstract suspend fun readyz(): Boolean

Readiness probe: true when the node is ready to serve. See healthz for the error contract.

Link copied to clipboard
abstract suspend fun recoverShardSnapshot(name: String, shardId: Int, location: String, priority: SnapshotPriority? = null, checksum: String? = null, wait: Boolean = true)

Recover one shard from a snapshot at location, leaving the collection's other shards alone.

Link copied to clipboard
abstract suspend fun recoverSnapshot(name: String, location: String, priority: SnapshotPriority? = null, checksum: String? = null, wait: Boolean = true)

Recover collection name from a snapshot at location — an http(s):// URL (e.g. another node's snapshot) or a file:/// path the server can read.

Link copied to clipboard
abstract suspend fun retrieve(name: String, ids: List<PointId>, withPayload: WithPayload? = null, withVector: Boolean? = null): List<Record>

Retrieve points by id.

Link copied to clipboard
abstract fun scroll(name: String, pageSize: Int = 64, configure: ScrollBuilder.() -> Unit = {}): Flow<Record>

Stream all points (optionally filtered) as a cold Flow, transparently following the server's pagination cursor. Cancellation and backpressure are cooperative.

Link copied to clipboard
abstract suspend fun search(name: String, configure: SearchBuilder.() -> Unit): List<ScoredPoint>

Nearest-vector search.

Link copied to clipboard
inline suspend fun <T> QdrantClient.searchAs(name: String, json: Json = kdrantJson, noinline configure: SearchBuilder.() -> Unit): List<Hit<T>>

Like QdrantClient.search, but decodes each hit's payload into T — the typical RAG read path.

Link copied to clipboard
abstract suspend fun searchBatch(name: String, configure: BatchSearchBuilder.() -> Unit): List<List<ScoredPoint>>

Run several searches in a single request; returns the hits for each, in the order added.

Link copied to clipboard
abstract suspend fun searchGroups(name: String, groupBy: String, groupSize: Int? = null, limit: Int? = null, configure: SearchBuilder.() -> Unit): List<PointGroup>

Grouped search: return hits grouped by the groupBy payload field.

Link copied to clipboard
abstract suspend fun searchMatrixOffsets(name: String, configure: SearchMatrixBuilder.() -> Unit = {}): SearchMatrixOffsets

As searchMatrixPairs but in sparse-coordinate (offsets) form, compact for clustering input.

Link copied to clipboard
abstract suspend fun searchMatrixPairs(name: String, configure: SearchMatrixBuilder.() -> Unit = {}): SearchMatrixPairs

Sample points and return the pairwise distance matrix in pairs form (an explicit edge list).

Link copied to clipboard
abstract suspend fun setPayload(name: String, payload: Payload, selector: DeleteSelector, key: String? = null, wait: Boolean = false)

Merge payload into the selected points' payload (existing keys are kept). Select the points with DeleteSelector.Ids(...) or DeleteSelector.ByFilter(filter { ... }).

Link copied to clipboard
abstract suspend fun telemetry(): JsonObject

The server's telemetry as a raw JSON object (shape is server-version-specific).

Link copied to clipboard
abstract suspend fun updateAliases(timeout: Int? = null, configure: UpdateAliasesBuilder.() -> Unit)

Apply alias changes as one atomic batch — the primitive behind zero-downtime reindexing.

Link copied to clipboard
abstract suspend fun updateCollection(name: String, configure: UpdateCollectionBuilder.() -> Unit)

Update an existing collection's config (optimizers, HNSW, quantization).

Link copied to clipboard
abstract suspend fun updateCollectionCluster(name: String, operation: ClusterOperation, timeout: Int? = null)

Move, replicate or drop a shard.

Link copied to clipboard
abstract suspend fun updateVectors(name: String, points: List<PointVectors>, wait: Boolean = false)

Update the vectors of existing points, keeping their payload.

Link copied to clipboard
abstract suspend fun uploadShardSnapshot(name: String, shardId: Int, data: Flow<ByteArray>, priority: SnapshotPriority? = null, checksum: String? = null, wait: Boolean = true)

Upload a shard snapshot file (streamed from data) and recover that shard from it.

Link copied to clipboard
abstract suspend fun uploadSnapshot(name: String, data: Flow<ByteArray>, priority: SnapshotPriority? = null, checksum: String? = null, wait: Boolean = true)

Upload a snapshot file (streamed from data) and recover collection name from it.

Link copied to clipboard
abstract suspend fun upsert(name: String, wait: Boolean = false, configure: UpsertBuilder.() -> Unit)

Upsert points into a collection.

abstract suspend fun upsert(name: String, points: Sequence<PointStruct>, wait: Boolean = false)

Upsert points from a lazy Sequence, chunked by the engine (see the Flow overload).

abstract suspend fun upsert(name: String, points: Flow<PointStruct>, wait: Boolean = false)

Upsert points streamed from a Flow — ingest a large or unbounded source without materializing it all in memory. The engine chunks the flow to stay under the request-size cap; as with the DSL upsert, the chunks are applied sequentially and are not atomic across chunk boundaries.