Edge capabilities

Edge implements the same plan path as remote Qdrant and shares its response envelope, but it is a single-process engine. This page is the definitive boundary: what runs offline, what fails, and with which stable error code.

The rule is simple: unsupported is a loud, stable error, never a silent no-op. Every rejection carries a reason and, when applicable, a "use remote Qdrant" hint.

Capability matrix

Capability	Edge	Notes
Parser, planner, explain	yes	identical to remote
Dense nearest search	yes	HNSW, single-threaded per shard
Sparse search (BM25)	yes	default, Qdrant qdrant/bm25-compatible; real ONNX with sparse_model
Hybrid dense + sparse	yes	front-form or tail-form USING HYBRID
Fusion RRF / DBSF	yes	plain FUSION RRF uses k = 2; parameterized form honors PARAMS (rrf_k, rrf_weights)
MMR	yes	dense only
Recommend	partial	best_score and sum_scores only
Context / Discover	yes	requires embeddable inputs
Formula scoring	yes	full operator set including geo and decay
Relevance feedback	yes	naive strategy
QUERY POINTS	yes	integers or UUIDs
Scroll	yes	cursor via AFTER / next_page_offset
Count	yes	exact by default
Order-by queries	yes	QUERY ORDER BY field ASC/DESC
Random sample	yes	QUERY SAMPLE RANDOM
CTEs / prefetch	yes	WITH … PREFETCH
Cross rerank	yes	client-side, host cross-encoder model
Score threshold, offset/limit	yes
PARAMS (hnsw_ef, exact, acorn, quantization, indexed_only, idf)	yes	including per-query sparse IDF corpora and ACORN filtered search
Payload filters	yes	comparisons, IN, BETWEEN, MATCH / MATCH PREFIX, SLICE, geo, NESTED, …
UPSERT with auto-embedding	yes	dense, sparse, multi, image
DELETE / payload / vector operations	yes	by id or filter
CREATE/DROP COLLECTION	yes
Create-time per-vector engine config	yes	WITH VECTOR (storage/datatype), WITH HNSW, WITH QUANTIZATION, WITH SPARSE all lower onto the engine config; memory tiers map to the engine's RAM/mmap switch
Background optimization	no	qql edge optimize runs the blocking optimizer loop; prevent_unoptimized defers point visibility until it runs
Remote → edge snapshot seed	yes	qql edge bootstrap streams a server shard snapshot (config + built HNSW + quantized data); snapshot creation is remote-side only
WAL capacity tuning	yes	Rust (LocalExecutorOptions::wal_segment_capacity), CLI (--wal-segment-mb), Python (wal_segment_mb), Node (walSegmentMb); qdrant-edge 0.8's own Python binding cannot set it
CREATE/DROP INDEX	yes	keyword (incl. prefix), integer, float, bool, geo, text, datetime, uuid
SHOW COLLECTIONS / SHOW COLLECTION	yes
Query/update batching	partial	BATCH { ... } fans out, not a native batch RPC
GROUP BY	yes	qdrant-edge grouping driver; LIMIT/OFFSET map to groups/group_offset
GROUP BY … LOOKUP FROM	no	QQL-EDGE-UNSUPPORTED-GROUP-LOOKUP (no lookup collection)
SHARD routing / custom sharding	no	QQL-EDGE-UNSUPPORTED-SHARD
CREATE/DROP SHARD KEY	no	QQL-EDGE-UNSUPPORTED-SHARD-KEY
ALTER COLLECTION	partial	HNSW + optimizer config apply; WITH PARAMS / QUANTIZATION reject per field
Collection WITH PARAMS	partial	only on_disk_payload; other keys → QQL-EDGE-UNSUPPORTED-COLLECTION-PARAMS
OPTIMIZERS (memmap_threshold, flush_interval_sec, max_optimization_threads)	no	QQL-EDGE-UNSUPPORTED-OPTIMIZER-KEY (engine excludes them)
SHOW QUOTAS / SET QUOTA	no	QQL-EDGE-UNSUPPORTED-QUOTA (cluster REST only)
RECOMMEND STRATEGY average_vector	no	QQL-EDGE-UNSUPPORTED-RECOMMEND-STRATEGY
Point-id query inputs	no	QQL-EDGE-UNSUPPORTED-POINT-REF
String point IDs (non-UUID)	no	QQL-EDGE-INVALID-POINT-ID
gRPC transport	no	edge has no protobuf dependency
PARAMS (timeout, consistency)	no	QQL-EDGE-UNSUPPORTED-TIMEOUT / QQL-EDGE-UNSUPPORTED-CONSISTENCY
Remote image URLs	partial	local ONNX embedder: local file paths only; the HTTP embedder forwards the source string verbatim, so endpoints that accept HTTP(S) image URLs can back CLIP vision

What works

Schema and mutations

QQLCollections and indexesTry in playground↗Copy

CREATE COLLECTION docs HYBRID;

CREATE INDEX ON COLLECTION docs FOR category TYPE keyword;

SHOW COLLECTIONS;

DROP COLLECTION docs;

QQLUpsert with auto-embeddingTry in playground↗Copy

UPSERT INTO docs VALUES
  {id: 1, text: 'runs locally', category: 'edge'},
  {id: 2, text: 'shipped to production', category: 'qql'} USING HYBRID;

Upserts embed text on-device (or via the configured HTTP endpoint) into the schema's dense and sparse vectors. Explicit vectors work too:

QQLExplicit dense vectorTry in playground↗Copy

UPSERT INTO docs VALUES {id: 1, vector: {dense: [0.1, 0.2, 0.3]}, text: 'precomputed'};

Point and payload operations

QQLDelete and payload updatesTry in playground↗Copy

DELETE FROM docs WHERE status = 'expired';

UPDATE docs SET PAYLOAD = {status: 'reviewed'} WHERE id = 42;

UPDATE docs SET VECTOR = [0.1, 0.2, 0.3] WHERE id = 42;

CLEAR PAYLOAD FROM docs WHERE status = 'archived';

DELETE PAYLOAD draft FROM docs WHERE id = 42;

DELETE VECTOR colbert FROM docs WHERE id = 42;

Search

QQLDense, sparse, and hybrid searchTry in playground↗Copy

QUERY 'edge vector search' FROM docs USING dense LIMIT 10;

QUERY 'keyword style' FROM docs USING sparse LIMIT 10;

QUERY HYBRID TEXT 'hybrid' FUSION RRF FROM docs LIMIT 10;

QUERY HYBRID TEXT 'hybrid' DENSE dense SPARSE sparse FUSION RRF
FROM docs
LIMIT 10;

QQLFusion, MMR, and recommendationTry in playground↗Copy

WITH
  candidates AS (QUERY 'x' USING dense LIMIT 100)
QUERY FUSION RRF
FROM docs
PREFETCH (candidates)
LIMIT 10;

QUERY MMR TEXT 'x' DIVERSITY 0.7 CANDIDATES 100 FROM docs USING dense LIMIT 10;

QUERY RECOMMEND POSITIVE (1, 2) NEGATIVE (3) STRATEGY best_score
FROM docs
USING dense
LIMIT 10;

QQLAdvanced query formsTry in playground↗Copy

QUERY FORMULA $score * 0.8 DEFAULTS (score = 0.0) FROM docs LIMIT 10;

QUERY CONTEXT (POSITIVE 'good' NEGATIVE 'bad') FROM docs LIMIT 10;

QUERY SAMPLE RANDOM FROM docs LIMIT 10;

QUERY ORDER BY year DESC FROM docs LIMIT 10;

QQLGrouped searchTry in playground↗Copy

QUERY 'x' FROM docs USING dense GROUP BY category LIMIT 5;

QUERY 'x' FROM docs USING dense GROUP BY category SIZE 3 LIMIT 10 OFFSET 5;

Group ids come back typed (keyword / unsigned / signed) with fully hydrated hits; SIZE maps to the per-group hit count and OFFSET trims groups client-side via group_offset.

Cross-encoder reranking runs client-side: candidate stages execute against local storage and the host cross-encoder model scores the pairs.

Params and pagination

QQLSearch params, threshold, and offsetTry in playground↗Copy

QUERY 'x'
FROM docs
USING dense
PARAMS (hnsw_ef = 64, exact = true)
SCORE THRESHOLD 0.5
LIMIT 10
OFFSET 20;

Batching is fan-out

execute with a list of statements, a semicolon-delimited string, or a BATCH { ... } block is executed statement-by-statement against the edge backend. There is no native batch RPC — results are returned per operation with cardinality matching the input.

Optimization and snapshot seeding

qdrant-edge indexes nothing in the background. qql edge optimize <collection> calls the engine's blocking optimizer loop (merge, index, vacuum, config-mismatch) and qql --edge doctor / qql check --edge surface the indexed_vectors_count vs points_count lag with the same nudge. A segment below the collection's indexing_threshold (10 MB by default offline, versus 20 MB on a 1.19 server) stays brute-force by design.

For the initial load, qql edge bootstrap <collection> --from <url> seeds the local directory from a remote Qdrant shard snapshot (unpack_snapshot + load), preserving the source collection's config, built HNSW indexes and quantized data. A single-shard collection is auto-discovered; multi-shard collections require --shard-id and fail closed otherwise (QQL-SNAPSHOT-SHARD).

What fails — and how

Every unsupported feature returns a stable error code. The message includes the feature, the reason, and a remediation hint.

Code	Feature
QQL-EDGE-UNSUPPORTED-SHARD	SHARD routing or collection sharding options
QQL-EDGE-UNSUPPORTED-SHARD-KEY	CREATE / DROP SHARD KEY
QQL-EDGE-UNSUPPORTED-GROUP-LOOKUP	GROUP BY … LOOKUP FROM (no lookup collection)
QQL-EDGE-UNSUPPORTED-ALTER-PARAMS	ALTER COLLECTION … WITH PARAMS
QQL-EDGE-UNSUPPORTED-ALTER-QUANTIZATION	ALTER COLLECTION … QUANTIZATION
QQL-EDGE-UNSUPPORTED-VECTOR-DIFF	Per-vector ALTER COLLECTION … WITH VECTOR (<name>) fields other than hnsw_config (quantization_config / on_disk / memory); qdrant-edge exposes set_vector_hnsw_config only
QQL-EDGE-UNSUPPORTED-SPARSE-DIFF	Per-sparse-vector ALTER COLLECTION … WITH SPARSE (<name>); qdrant-edge has no sparse vector config setter
QQL-EDGE-UNSUPPORTED-COLLECTION-PARAMS	create-time WITH PARAMS other than on_disk_payload
QQL-EDGE-UNSUPPORTED-OPTIMIZER-KEY	OPTIMIZERS keys the engine excludes
QQL-EDGE-UNSUPPORTED-QUOTA	SHOW QUOTAS / SET QUOTA (cluster REST /quotas only)
QQL-EDGE-UNSUPPORTED-RECOMMEND-STRATEGY	RECOMMEND STRATEGY average_vector
QQL-EDGE-UNSUPPORTED-POINT-REF	point-id-only inputs (need materialized vectors)
QQL-EDGE-UNSUPPORTED-FORMULA-FUNCTION	MAX / MIN / ACOSH formula functions; qdrant-edge 0.8 has no such Expression variants
QQL-EDGE-UNSUPPORTED-ROUTE	any other unmapped projection
QQL-EDGE-INVALID-POINT-ID	non-integer, non-UUID string point IDs

Example rejection:

GROUP BY … LOOKUP FROM is not supported offline: qdrant-edge groups the queried
shard only and has no lookup collection to hydrate hits from. Use remote Qdrant
(REST or gRPC) for this feature.

Point IDs: integers or UUIDs only

Edge storage represents IDs as unsigned integers or UUIDs. A string like 'doc-1' is rejected with QQL-EDGE-INVALID-POINT-ID rather than silently mapped — deleting "half a batch" because some IDs could not be represented is exactly what edge refuses to do.

Shards, quotas, and cluster admin need remote Qdrant

Custom SHARD routing, shard-key administration, GROUP BY … LOOKUP FROM, ALTER COLLECTION … WITH PARAMS / QUANTIZATION, per-vector fields other than HNSW (QQL-EDGE-UNSUPPORTED-VECTOR-DIFF), per-sparse-vector diffs (QQL-EDGE-UNSUPPORTED-SPARSE-DIFF), create-time WITH PARAMS beyond on_disk_payload, MAX / MIN / ACOSH formulas (QQL-EDGE-UNSUPPORTED-FORMULA-FUNCTION), and SHOW QUOTAS / SET QUOTA are cluster or REST-only features. Edge keeps the whole language surface and rejects at execution — switch to REST (or gRPC where supported) for those workloads. GROUP BY, ALTER COLLECTION … WITH HNSW / WITH OPTIMIZERS (including per-vector HNSW), per-query sparse idf, and ACORN params are supported offline.

Code catalog

See the complete list of fixed codes in the error codes reference.

Technical details

Recommendations and point reference inputs: QUERY POINT 42 FROM docs, QUERY RECOMMEND POSITIVE (1), and similar point-id inputs need the point's vector materialized. Text, vector, or image inputs that can be embedded by the configured model work; point-id-only inputs fail with QQL-EDGE-UNSUPPORTED-POINT-REF (or resolve to vectors first).

Request-level parameters

timeout and consistency are request-level fields for remote REST/gRPC transports and are rejected offline with QQL-EDGE-UNSUPPORTED-TIMEOUT and QQL-EDGE-UNSUPPORTED-CONSISTENCY. hnsw_ef, exact, acorn (with max_selectivity), quantization, and indexed_only are honored.

Transport

Edge has no gRPC and no protobuf dependency. The runtime executor always dispatches through the embedded QdrantOps backend. If your tooling needs gRPC, use the remote path.

For storage behavior across restarts and the data directory layout, continue to persistence.