qdrant-edge

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 mutable shard for local writes plus an immutable shard 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_snapshot and update_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 (Bm25, Bm25Config, embed_document, embed_query) with the IDF Modifier on EdgeSparseVectorParams, and is wire-compatible with the server's sparse vector BM25 model (Edge BM25 docs cover only the sparse vector variant): a shard seeded from a server snapshot answers local BM25 queries without re-indexing. Do not ship a second BM25 library Edge BM25
• Dense embeddings are NOT in Edge: generate them on device with the separate fastembed package FastEmbed embeddings
• For hybrid search, run the dense and sparse legs as prefetches and fuse them with a Fusion query in a single query call, instead of combining rankings in application code Reading data

Operating the Shard

Use when: writes have accumulated, search looks stale after inserts, or a backup is larger than the data.

• Edge has NO background optimizer. Call optimize after bulk writes: it builds indexes (including the sparse index) and reclaims deleted points. Skip it and that data stays unindexed Edge quickstart
• Faceting, counting, and enumeration are built in (facet, count, scroll); index the fields you filter or facet with create_field_index rather 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_snapshot and update_from_snapshot
• Ship a custom or third-party BM25 when Edge has one built in
• Use embed_document for queries or embed_query for documents: the weighting differs and results go wrong
• Combine dense and sparse rankings in application code: Edge query accepts prefetches and fuses them with a Fusion query
• 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