Qdrant.jl

Qdrant

A Julian client for the Qdrant vector database.

Supports both HTTP/REST and gRPC transports. Every endpoint returns a QdrantResponse{T} carrying the typed .result, the server .status, and the server-side .time.

Quick Start — HTTP (default)

using Qdrant

client = QdrantClient()
create_collection(client, "demo", CollectionConfig(vectors=VectorParams(size=4, distance=Dot)))
upsert_points(client, "demo", [Point(id=1, vector=Float32[1,0,0,0])])
resp = query_points(client, "demo"; query=Float32[1,0,0,0], limit=5)
resp.result.points   # Vector{ScoredPoint}

Quick Start — gRPC

client = QdrantClient(GRPCTransport(host="localhost", port=6334))
# Same API — transport is selected via dispatch

QdrantClient{T<:AbstractTransport}

Connection to a Qdrant server. The type parameter T selects the transport, enabling zero-cost dispatch to HTTP or gRPC code paths.

Constructors

QdrantClient()                                        # HTTP localhost:6333
QdrantClient(host="myhost", port=6333, api_key="k")  # HTTP with options
QdrantClient(GRPCTransport(host="h", port=6334))      # gRPC

AbstractTransport

Base type for transport backends. Subtype to add new protocols.

HTTPTransport <: AbstractTransport

HTTP/REST transport using HTTP.jl with connection pooling.

GRPCTransport <: AbstractTransport

gRPC transport using gRPCClient.jl with HTTP/2 and Protocol Buffers. Provides ~2-10x faster throughput than REST for bulk operations.

Fields

• host: Server hostname (default: "localhost")
• port: gRPC port (default: 6334)
• api_key: Optional API key for authentication
• timeout: Request deadline in seconds (default: 30)
• tls: Use TLS/gRPCS (default: false)
• keepalive: TCP keepalive interval in seconds (default: 60)
• max_message_size: Max message size in bytes (default: 64MB)

QdrantResponse{T}

Standard envelope wrapping every API return value.

Fields

• result::T — the typed payload
• status::String — server status (e.g. "ok")
• time::Float64 — server-side processing time in seconds

Examples

resp = upsert_points(client, "demo", points)
resp.result   # UpdateResult(operation_id=0, status="completed")
resp.status   # "ok"
resp.time     # 0.001

QdrantError <: Exception

Error from the Qdrant API.

Fields

• status::Int: HTTP status code (0 for non-HTTP errors)
• message::String: Human-readable error description
• detail::Any: Parsed error details from the API response

set_client!(client) -> QdrantClient

Set the global default connection.

get_client() -> QdrantClient

Return the global default connection, creating one if needed.

serialize_body(x) -> String

Serialize to JSON, stripping nothing fields and empty collections.

AbstractQdrantType

Root of the Qdrant type hierarchy. All Qdrant structs subtype this.

AbstractConfig <: AbstractQdrantType

Configuration types for creating/updating resources.

AbstractCondition <: AbstractQdrantType

Filter condition types.

AbstractResponse <: AbstractQdrantType

Typed response types returned from API calls.

Optional{T}

Alias for Union{Nothing, T}. Used throughout for optional fields.

PointId

A unique point identifier — integer or UUID. Qdrant accepts uint64 or uuid format strings.

Distance

Vector distance metric.

Values: Cosine, Euclid, Dot, Manhattan

list_collections(client) -> QdrantResponse{Vector{CollectionDescription}}

List all collections on the server.

create_collection(client, name, config) -> QdrantResponse{Bool}
create_collection(client, name; vectors, kwargs...) -> QdrantResponse{Bool}

Create a new collection.

Examples

create_collection(client, "demo", CollectionConfig(vectors=VectorParams(size=4, distance=Dot)))
create_collection(client, "demo"; vectors=VectorParams(size=4, distance=Dot))

delete_collection(client, name) -> QdrantResponse{Bool}

Delete a collection.

collection_exists(client, name) -> QdrantResponse{Bool}

Check if a collection exists.

get_collection(client, name) -> QdrantResponse{CollectionInfo}

Get detailed collection information.

update_collection(client, name, config) -> QdrantResponse{Bool}
update_collection(client, name; kwargs...) -> QdrantResponse{Bool}

Update collection parameters.

get_collection_optimizations(client, name) -> QdrantResponse{OptimizationsStatus}

Get optimization progress for a collection.

create_alias(client, alias, collection) -> QdrantResponse{Bool}

delete_alias(client, alias) -> QdrantResponse{Bool}

rename_alias(client, old, new_name) -> QdrantResponse{Bool}

list_aliases(client) -> QdrantResponse{Vector{AliasDescription}}

List all aliases across collections.

list_collection_aliases(client, collection) -> QdrantResponse{Vector{AliasDescription}}

List aliases for a specific collection.

upsert_points(client, collection, points; wait=true, ordering="weak") -> QdrantResponse{UpdateResult}

Insert or update points.

get_points(client, collection, ids; with_vectors=false, with_payload=true) -> QdrantResponse{Vector{Record}}

Retrieve multiple points by IDs.

get_point(client, collection, id) -> QdrantResponse{Record}

Retrieve a single point by ID (HTTP only — uses GET endpoint).

delete_points(client, collection, selector; wait=true) -> QdrantResponse{UpdateResult}

Delete points by IDs or filter.

scroll_points(client, collection; filter, limit, offset, with_vectors, with_payload) -> QdrantResponse{ScrollResult}

Scroll through points with optional filtering.

count_points(client, collection; filter, exact) -> QdrantResponse{CountResult}

Count points in a collection.

batch_points(client, collection, operations; wait=true) -> QdrantResponse{Vector{UpdateResult}}

Execute multiple point operations in a single batch call.

set_payload(client, collection, payload, selector; wait=true) -> QdrantResponse{UpdateResult}

Set payload fields on selected points.

overwrite_payload(client, collection, payload, selector; wait=true) -> QdrantResponse{UpdateResult}

Replace the entire payload on selected points (removes unlisted keys).

delete_payload(client, collection, keys, selector; wait=true) -> QdrantResponse{UpdateResult}

Delete payload keys from selected points.

clear_payload(client, collection, selector; wait=true) -> QdrantResponse{UpdateResult}

Remove all payload from selected points.

update_vectors(client, collection, points; wait=true) -> QdrantResponse{UpdateResult}

Update vectors for existing points.

delete_vectors(client, collection, vector_names, selector; wait=true) -> QdrantResponse{UpdateResult}

Delete named vector fields from selected points.

query_points(client, collection, request) -> QdrantResponse{QueryResult}
query_points(client, collection; query, limit, kwargs...) -> QdrantResponse{QueryResult}

Universal query API — replaces the deprecated search/recommend/discover endpoints.

Examples

query_points(client, "demo", QueryRequest(query=Float32[1,0,0,0], limit=5))
query_points(client, "demo"; query=Float32[1,0,0,0], limit=5, with_payload=true)

query_batch(client, collection, requests) -> QdrantResponse{Vector{QueryResult}}

Execute multiple queries in one call.

query_groups(client, collection, request) -> QdrantResponse{GroupsResult}

Query with result grouping.

Examples

query_groups(client, "demo", QueryRequest(
    query=Float32[1,0,0,0], limit=10, group_by="category", group_size=3))

search_matrix_pairs(client, collection; filter, sample, limit) -> QdrantResponse{SearchMatrixPairsResponse}

Compute pairwise distance matrix in pair format.

search_matrix_offsets(client, collection; filter, sample, limit) -> QdrantResponse{SearchMatrixOffsetsResponse}

Compute pairwise distance matrix in offset format.

facet(client, collection, key; filter, limit, exact) -> QdrantResponse{FacetResult}

Get value counts for a payload field (faceted search).

create_snapshot(client, collection) -> QdrantResponse{SnapshotInfo}

list_snapshots(client, collection) -> QdrantResponse{Vector{SnapshotInfo}}

delete_snapshot(client, collection, snapshot_name) -> QdrantResponse{Bool}

create_full_snapshot(client) -> QdrantResponse{SnapshotInfo}

list_full_snapshots(client) -> QdrantResponse{Vector{SnapshotInfo}}

delete_full_snapshot(client, snapshot_name) -> QdrantResponse{Bool}

recover_from_snapshot(client, collection; location, priority) -> QdrantResponse{Bool}

Recover a collection from a snapshot URL or local path.

Examples

recover_from_snapshot(client, "demo"; location="http://host/snapshot.tar")
recover_from_snapshot(client, "demo"; location="file:///data/snapshot.tar")

health_check(client) -> QdrantResponse{HealthInfo}

Check server health.

get_version(client) -> QdrantResponse{HealthInfo}

Get Qdrant server version and title.

get_metrics(client) -> QdrantResponse{String}

Retrieve Prometheus-format metrics (plain text response).

get_telemetry(client) -> QdrantResponse{Dict{String,Any}}

Retrieve telemetry data.

healthz(client) -> QdrantResponse{String}

Kubernetes health check endpoint (plain text response).

livez(client) -> QdrantResponse{String}

Kubernetes liveness probe (plain text response).

readyz(client) -> QdrantResponse{String}

Kubernetes readiness probe (plain text response).

get_issues(client) -> QdrantResponse{Dict{String,Any}}

Get performance issues and configuration suggestions.

clear_issues(client) -> QdrantResponse{Bool}

Clear all reported issues.

cluster_status(client) -> QdrantResponse{ClusterStatus}

Get cluster status information.

cluster_telemetry(client) -> QdrantResponse{Dict{String,Any}}

Get cluster-wide telemetry (peers, collections, shard transfers).

recover_current_peer(client) -> QdrantResponse{Bool}

Attempt to recover the current peer.

remove_peer(client, peer_id; force=false) -> QdrantResponse{Bool}

Remove a peer from the cluster. Fails if peer still has shards.

collection_cluster_info(client, collection) -> QdrantResponse{CollectionClusterInfo}

Get cluster information for a collection.

update_collection_cluster(client, collection, operations) -> QdrantResponse{Bool}

Update collection cluster configuration (move/replicate shards).

list_shard_keys(client, collection) -> QdrantResponse{ShardKeysResult}

List shard keys for a collection.

create_shard_key(client, collection, request) -> QdrantResponse{Bool}

Create a shard key for a collection.

delete_shard_key(client, collection, request) -> QdrantResponse{Bool}

Delete a shard key from a collection.

create_shard_snapshot(client, collection, shard_id) -> QdrantResponse{SnapshotInfo}

Create a snapshot for a specific shard.

list_shard_snapshots(client, collection, shard_id) -> QdrantResponse{Vector{SnapshotInfo}}

List snapshots for a specific shard.

delete_shard_snapshot(client, collection, shard_id, snapshot_name) -> QdrantResponse{Bool}

Delete a snapshot for a specific shard.

create_payload_index(client, collection, field_name; field_schema, wait=true) -> QdrantResponse{UpdateResult}

Create an index on a payload field.

delete_payload_index(client, collection, field_name; wait=true) -> QdrantResponse{UpdateResult}

Delete an index on a payload field.

CollectionConfig <: AbstractConfig

Configuration for creating a collection.

Examples

CollectionConfig(vectors=VectorParams(size=128, distance=Cosine))
CollectionConfig(
    vectors=VectorParams(size=4, distance=Dot),
    hnsw_config=HnswConfig(m=32),
    optimizers_config=OptimizersConfig(indexing_threshold=10000),
)
# Named vectors:
CollectionConfig(vectors=Dict{String,VectorParams}(
    "image" => VectorParams(size=512, distance=Cosine),
    "text" => VectorParams(size=768, distance=Dot),
))

CollectionUpdate <: AbstractConfig

Patch payload for updating collection parameters.

Examples

CollectionUpdate(optimizers_config=OptimizersConfig(indexing_threshold=10000))
CollectionUpdate(params=CollectionParamsDiff(replication_factor=2))

VectorParams <: AbstractConfig

Configuration for a vector field in a collection.

Examples

VectorParams(size=128, distance=Cosine)
VectorParams(size=4, distance=Dot, on_disk=true)
VectorParams(size=4, distance=Euclid, hnsw_config=HnswConfig(m=32, ef_construct=200))

SparseVectorParams <: AbstractConfig

Configuration for sparse vector fields.

HnswConfig <: AbstractConfig

HNSW index configuration parameters.

Fields

• m: Number of edges per node in the index graph
• ef_construct: Number of neighbours to consider during index building
• full_scan_threshold: Size (KB) below which full-scan is preferred
• max_indexing_threads: Parallel threads for background index building
• on_disk: Store HNSW index on disk (default: false)
• payload_m: Custom M param for payload-aware HNSW links
• inline_storage: Store vector copies within the HNSW index file

WalConfig <: AbstractConfig

Write-Ahead Log configuration.

Fields

• wal_capacity_mb: Size of a single WAL segment in MB
• wal_segments_ahead: Number of WAL segments to create ahead
• wal_retain_closed: Number of closed WAL segments to retain

OptimizersConfig <: AbstractConfig

Segment optimizer configuration.

Fields

• deleted_threshold: Minimal fraction of deleted vectors to trigger optimization
• vacuum_min_vector_number: Minimal vectors in a segment for optimization
• default_segment_number: Target number of segments
• max_segment_size: Max segment size in KB
• memmap_threshold: Max in-memory vectors per segment (KB)
• indexing_threshold: Max vectors for plain index (KB)
• flush_interval_sec: Minimum interval between forced flushes
• max_optimization_threads: Max threads for optimizations per shard
• prevent_unoptimized: Prevent creation of large unoptimized segments

CollectionParamsDiff <: AbstractConfig

Mutable collection parameters (used in update operations).

SearchParams <: AbstractConfig

Parameters controlling the search process.

Fields

• hnsw_ef: Size of the beam in beam-search (larger = more accurate, slower)
• exact: If true, search without approximation (exact but slow)
• quantization: Quantization parameters for search
• indexed_only: Only search among indexed/small segments

QuantizationSearchParams <: AbstractConfig

Parameters for quantization during search.

ScalarQuantization <: AbstractConfig

Scalar quantization wrapper.

ScalarQuantizationConfig <: AbstractConfig

Scalar quantization parameters.

ProductQuantization <: AbstractConfig

Product quantization wrapper.

ProductQuantizationConfig <: AbstractConfig

Product quantization parameters.

BinaryQuantization <: AbstractConfig

Binary quantization wrapper.

BinaryQuantizationConfig <: AbstractConfig

Binary quantization parameters.

QuantizationConfig

Union of all quantization configuration types.

LookupLocation <: AbstractConfig

Location to look up vectors in a different collection.

TextIndexParams <: AbstractConfig

Configuration for full-text index on a payload field.

Examples

TextIndexParams(tokenizer="word", lowercase=true)

Point <: AbstractQdrantType

A point with id, vector(s), and optional payload.

Examples

Point(id=1, vector=Float32[0.1, 0.2, 0.3, 0.4])
Point(id=uuid4(), vector=Float32[0.1, 0.2, 0.3, 0.4], payload=Dict("label" => "cat"))
Point(id=1, vector=NamedVector(name="image", vector=Float32[1.0, 0.0, 0.0, 0.0]))
Point(id=1, vector=Dict{String,Vector{Float32}}("image" => Float32[...], "text" => Float32[...]))

NamedVector <: AbstractQdrantType

A vector with an associated name, for collections with multiple named vectors.

Examples

NamedVector(name="image", vector=Float32[1.0, 0.0, 0.0, 0.0])

Filter <: AbstractCondition

Compound filter with must, should, must_not clauses.

Examples

Filter(must=[Dict("key" => "color", "match" => Dict("value" => "red"))])

FieldCondition <: AbstractCondition

Condition on a specific payload field.

MatchValue <: AbstractCondition

Match a specific value.

MatchAny <: AbstractCondition

Match any of the given values.

MatchText <: AbstractCondition

Full-text match.

RangeCondition <: AbstractCondition

Range comparison filter.

HasIdCondition <: AbstractCondition

Filter points by ID.

IsEmptyCondition <: AbstractCondition

Filter for empty fields.

IsNullCondition <: AbstractCondition

Filter for null fields.

QueryRequest <: AbstractRequest

Advanced query request (Qdrant universal query API). Replaces the deprecated search_points, recommend_points, and discover_points endpoints.

Examples

# Nearest-neighbor search
QueryRequest(query=Float32[1,0,0,0], limit=5)

# With named vector
QueryRequest(query=Float32[1,0,0,0], limit=10, using_="image", with_payload=true)

# Recommendation via query API
QueryRequest(query=Dict("recommend" => Dict("positive" => [1], "negative" => [3])), limit=5)

# Prefetch + re-rank
QueryRequest(query=Float32[1,0,0,0], limit=5,
    prefetch=[Dict("query" => Float32[1,0,0,0], "limit" => 50)])

UpdateResponse <: AbstractResponse

Result of a mutating operation (upsert, delete, set_payload, etc.).

Fields

• operation_id::Int: Server-assigned operation ID
• status::String: Operation status ("completed" or "acknowledged")

CountResult <: AbstractResponse

Result of count_points.

Fields

• count::Int: Number of matching points

ScoredPoint <: AbstractResponse

A point returned from a search/query, with a similarity score.

Fields

• id::PointId: Point identifier
• version::Int: Point version
• score::Float64: Similarity score
• payload::Optional{Dict{String,Any}}: Payload data
• vector::Any: Vector data (Float32[], Dict, etc.)

Record <: AbstractResponse

A stored point record (from get_points, scroll_points).

Fields

• id::PointId: Point identifier
• payload::Optional{Dict{String,Any}}: Payload data
• vector::Any: Vector data

ScrollResult <: AbstractResponse

Result of scroll_points.

Fields

• points::Vector{Record}: Page of records
• next_page_offset::Optional{PointId}: Offset for the next page (nothing if last page)

QueryResult <: AbstractResponse

Result of query_points.

Fields

• points::Vector{ScoredPoint}: Matching points with scores

GroupResult <: AbstractResponse

A single group within a grouped query result.

Fields

• id::Any: Group key value
• hits::Vector{ScoredPoint}: Points in this group

GroupsResult <: AbstractResponse

Result of query_groups.

Fields

• groups::Vector{GroupResult}: Groups of matching points

SnapshotInfo <: AbstractResponse

Description of a snapshot.

Fields

• name::String: Snapshot filename
• creation_time::Optional{String}: ISO timestamp of creation
• size::Int: Snapshot size in bytes
• checksum::Optional{String}: Checksum if available

HealthInfo <: AbstractResponse

Health check result.

Fields

• title::String: Service title
• version::String: Server version

CollectionDescription <: AbstractResponse

Brief collection info from list_collections.

Fields

• name::String: Collection name

AliasDescription <: AbstractResponse

Alias mapping from list_aliases.

Fields

• alias_name::String
• collection_name::String

CollectionInfo <: AbstractResponse

Detailed collection information from get_collection.

Fields

• status::String: Collection status (e.g. "green", "yellow", "red")
• optimizer_status::String: Optimizer status ("ok" or error message)
• points_count::Optional{Int}: Total number of points
• indexed_vectors_count::Optional{Int}: Number of indexed vectors
• segments_count::Int: Number of segments
• config::Dict{String,Any}: Collection configuration (vectors, HNSW, WAL, etc.)
• payload_schema::Dict{String,Any}: Indexed payload field schemas

OptimizationsStatus <: AbstractResponse

Optimization progress for a collection from get_collection_optimizations.

Fields

• running::Vector{Dict{String,Any}}: Currently running optimizations
• summary::Dict{String,Any}: Aggregated optimization statistics
• queued::Optional{Vector{Dict{String,Any}}}: Pending optimizations (requires ?with=queued)
• completed::Optional{Vector{Dict{String,Any}}}: Completed optimizations (requires ?with=completed)

ClusterStatus <: AbstractResponse

Cluster status from cluster_status.

Fields

• status::String: "disabled" or "enabled"
• peer_id::Optional{Int}: This node's peer ID (only when enabled)
• peers::Dict{String,Any}: Peer ID → peer info map (only when enabled)
• raft_info::Dict{String,Any}: Raft consensus state (only when enabled)
• message_send_failures::Dict{String,Any}: Consecutive send failures per peer (only when enabled)

LocalShardInfo <: AbstractResponse

Information about a locally-hosted shard.

Fields

• shard_id::Int: Shard identifier
• points_count::Optional{Int}: Number of points in the shard
• state::String: Shard state (e.g. "Active", "Partial")
• shard_key::Optional{Any}: Shard key if using custom sharding

RemoteShardInfo <: AbstractResponse

Information about a remotely-hosted shard replica.

Fields

• shard_id::Int: Shard identifier
• peer_id::Int: Peer hosting this shard
• state::String: Shard state
• shard_key::Optional{Any}: Shard key if using custom sharding

ShardTransferInfo <: AbstractResponse

Information about an in-progress shard transfer.

Fields

• shard_id::Int: Shard being transferred
• from::Int: Source peer ID
• to::Int: Destination peer ID
• sync::Bool: Whether this is a synchronous transfer
• to_shard_id::Optional{Int}: Target shard ID (for resharding)
• method::Optional{String}: Transfer method
• comment::Optional{String}: Human-readable description

CollectionClusterInfo <: AbstractResponse

Cluster information for a specific collection from collection_cluster_info.

Fields

• peer_id::Int: This node's peer ID
• shard_count::Int: Total number of shards
• local_shards::Vector{LocalShardInfo}: Shards hosted on this node
• remote_shards::Vector{RemoteShardInfo}: Shards hosted on remote nodes
• shard_transfers::Vector{ShardTransferInfo}: In-progress shard transfers

ShardKeysResult <: AbstractResponse

Result of list_shard_keys.

Fields

• shard_keys::Vector{Any}: List of shard keys (strings, integers, or key objects)

FacetHit <: AbstractResponse

A single facet count.

Fields

• value::Any: The facet value
• count::Int: Number of points with this value

FacetResult <: AbstractResponse

Result of facet.

Fields

• hits::Vector{FacetHit}: Facet value counts

SearchMatrixPairsResponse <: AbstractResponse

Distance matrix in pair format.

Fields

• pairs::Vector{Dict{String,Any}}: Distance pairs

SearchMatrixOffsetsResponse <: AbstractResponse

Distance matrix in offset format.

Fields

• offsets_row::Vector{Int}: Row offsets
• offsets_col::Vector{Int}: Column offsets
• scores::Vector{Float64}: Distance scores
• ids::Vector{PointId}: Point IDs

to_proto_point(p::Point) -> qdrant.PointStruct

from_proto_scored_point(sp::qdrant.ScoredPoint) -> Dict{String,Any}

from_proto_retrieved_point(rp::qdrant.RetrievedPoint) -> Dict{String,Any}

julia_value_to_proto(val) -> qdrant.Value

Convert a Julia value to a protobuf Value (jsonwithint).

proto_value_to_julia(val::qdrant.Value) -> Any

Convert a protobuf Value back to a native Julia value.