Imported from qdrant/skills (
skills/qdrant-edge/SKILL.md). Install upstream withnpx skills add qdrant/skills --skill qdrant-edge. Copyright stays with the author.
Building on Qdrant Edge
Edge is the Qdrant engine embedded in your process (Python or Rust), not a thin local vector store to wrap. The failure mode is rebuilding what the shard already ships: keyword scoring, snapshot apply, faceting, counting. Before writing any of that, check the shard API. One thing Edge does NOT give you is a one-call cloud sync, so knowing what is built in keeps you from both reinventing built-ins and expecting capabilities Edge lacks. Edge is single-node and shares the server's data format.
- Edge is in beta: pin your version, the API drifts between releases Qdrant Edge.
Syncing a Shard with a Qdrant Server
Use when: seeding a shard from a server, keeping it fresh, backing it up, or aggregating many devices into one collection.
There is no built-in .sync(). Sync is a pattern you assemble from shard helpers plus your own transport, so do not go looking for one call.
- Follow the documented dual-shard pattern: a
mutableshard for local writes plus animmutableshard restored from a server snapshot, query both, refresh on a schedule Edge synchronization guide. - You write the snapshot download (plain HTTP to the shard snapshot endpoint), then apply it with
unpack_snapshotandupdate_from_snapshot. Do not untar or merge segments by hand Synchronization patterns. - Refresh incrementally with a partial snapshot built from
snapshot_manifest, not a full snapshot every cycle Synchronization patterns. - Push is your own dual-write: on each local upsert, enqueue the point and let a background worker upsert it to the server, buffering while offline Synchronization patterns.
Keyword and Hybrid Search on Device
Use when: you need exact-term or BM25 matching, alone or alongside vectors.
- BM25 is built into Edge: create a full-text index with
scoringenabled on the payload field (with the stemmer and stopwords for your language) and rank with aTextQuery. It needs no embedding model and derives document lengths from your data. Do not ship a second BM25 library Edge BM25 - Need sparse BM25 vectors instead, for example to match a server collection that uses sparse vector BM25? Edge's BM25 embedder (
Bm25in Python,EdgeBm25in Rust) produces server-compatible sparse vectors:embed_documentfor documents,embed_queryfor queries Edge BM25 - Dense embeddings are NOT in Edge: generate them on device with the separate
fastembedpackage FastEmbed embeddings - For hybrid search, run the dense and keyword legs as
prefetches(aTextQuery, or a sparse vector query) and fuse them with aFusionquery in a singlequerycall, instead of combining rankings in application code Reading data
Operating the Shard
Use when: writes have accumulated, search is slow after inserts, or a backup is larger than the data.
- Edge has NO background optimizer. Call
optimizeafter bulk writes: it builds indexes and reclaims deleted points. Until then, new points are searched by brute force Edge quickstart - Faceting, counting, and enumeration are built in (
facet,count,scroll); index the fields you filter or facet withcreate_field_indexrather than aggregating in application code Edge quickstart - The write-ahead log is pre-allocated to 32 MB and inflates apparent disk and backup size. Shrink it with
wal_options(Rust), and do not treat raw file size as real usage Edge quickstart
What NOT to Do
- Expect a bidirectional
.sync()or a built-in push path: Edge gives you snapshot apply, you own the transport and the dual-write - Untar or merge snapshot segments by hand instead of using
unpack_snapshotandupdate_from_snapshot - Ship a custom or third-party BM25 when Edge has one built in
- Run a
TextQueryon a full-text index created withoutscoring: BM25 ranking needs it enabled - Use the BM25 embedder's
embed_documentfor queries orembed_queryfor documents: the weighting differs and results go wrong - Combine dense and keyword rankings in application code: Edge
queryacceptsprefetchesand fuses them with aFusionquery - Assume a background optimizer like the server's: nothing is indexed or compacted until you call
optimize - Reach for Edge when you need distributed or multi-node search: it is single-node Qdrant Edge
- Claim support for a language beyond Python and Rust, or an OS or accelerator the Edge docs do not state
