Skip to main content
skill CX Codex

qdrant-edge — Claude Code skill: features and installation

This Claude Code skill guides development with Qdrant Edge. It covers local shard sync, BM25 search, and index maintenance.

Apache-2.0 328 installs ★ 271 updated 2026-11-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add qdrant/skills --skill qdrant-edge -a claude-code
Open on GitHub

What qdrant-edge does

The skill explains Qdrant Edge as an embedded shard and covers built-in features such as BM25, snapshot application, faceting, and counting. There is no ready-made .sync() call for server sync, so you must provide the transport and handle pushing local changes.

The guide covers snapshot refreshes, partial snapshots, and combining vector results with text search. Dense embeddings require the separate fastembed package; Edge itself supports Python and Rust. After bulk writes, call optimize or new points are searched by brute force. Edge is in beta, and its API changes between releases, so pinning a version matters.

It also shows how to apply snapshots with unpack_snapshot and update_from_snapshot instead of manipulating segments by hand. Edge runs on a single node; distributed search calls for a different setup.

What it helps with

  • sync a local shard from a server snapshot
  • set up BM25 search on payload fields
  • combine vector and text search results
  • run optimize after bulk writes
  • refresh a shard with a partial snapshot

Example prompts for the agent

  • Explain how to refresh a local Qdrant Edge shard from a server snapshot.
  • Show how to configure BM25 search on a payload field in Edge.
  • How do I combine dense vector search with a text query in Edge?

How to install qdrant-edge

1Skills CLI (Vercel)

npx skills add qdrant/skills --skill qdrant-edge -a claude-code

2Manually: put the files in place

~/.claude/skills/qdrant-edge/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/qdrant-edge/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about qdrant-edge

How do I install qdrant-edge in Claude Code?

Run npx skills add qdrant/skills --skill qdrant-edge -a claude-code. The skill is available at ~/.claude/skills/qdrant-edge/SKILL.md.

What does qdrant-edge do?

It guides development with Qdrant Edge, covering snapshot-based sync, BM25 and hybrid search, and shard operations.

How do I sync Edge with a server?

Edge has no built-in .sync() call, so you provide the transport and snapshot download. Partial refreshes can use snapshot_manifest, unpack_snapshot, and update_from_snapshot.

Source text

SKILL.md · Apache-2.0
---
name: qdrant-edge
description: "Guides building on Qdrant Edge, the embedded in-process shard. Use when someone asks 'how to sync Edge with the server', 'keep a local shard in sync with Qdrant Cloud', 'BM25 or keyword search on Edge', 'hybrid search on Edge', 'embeddings on device', 'Edge snapshots', 'apply a partial snapshot', 'why is my Edge search slow after inserts', or is writing custom sync, BM25, or fusion code against qdrant-edge. Also use when deciding what Edge ships built-in versus what you must implement."
---

# 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](https://skills.qdrant.tech/md/documentation/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](https://skills.qdrant.tech/md/documentation/edge/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](https://skills.qdrant.tech/md/documentation/edge/edge-data-synchronization-patterns/).
- Refresh incrementally with a partial snapshot built from `snapshot_manifest`, not a full snapshot every cycle [Synchronization patterns](https://skills.qdrant.tech/md/documentation/edge/edge-data-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](https://skills.qdrant.tech/md/documentation/edge/edge-data-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 `scoring` enabled on the payload field (with the stemmer and stopwords for your language) and rank with a `TextQuery`. It needs no embedding model and derives document lengths from your data. Do not ship a second BM25 library [Edge BM25](https://skills.qdrant.tech/md/documentation/edge/edge-bm25/)
- Need sparse BM25 vectors instead, for example to match a server collection that uses sparse vector BM25? Edge's BM25 embedder (`Bm25` in Python, `EdgeBm25` in Rust) produces server-compatible sparse vectors: `embed_document` for documents, `embed_query` for queries [Edge BM25](https://skills.qdrant.tech/md/documentation/edge/edge-bm25/)
- Dense embeddings are NOT in Edge: generate them on device with the separate `fastembed` package [FastEmbed embeddings](https://skills.qdrant.tech/md/documentation/edge/edge-fastembed-embeddings/)
- For hybrid search, run the dense and keyword legs as `prefetches` (a `TextQuery`, or a sparse vector query) and fuse them with a `Fusion` query in a single `query` call, instead of combining rankings in application code [Reading data](https://skills.qdrant.tech/md/documentation/edge/edge-api/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 `optimize` after bulk writes: it builds indexes and reclaims deleted points. Until then, new points are searched by brute force [Edge quickstart](https://skills.qdrant.tech/md/documentation/edge/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](https://skills.qdrant.tech/md/documentation/edge/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](https://skills.qdrant.tech/md/documentation/edge/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
- Run a `TextQuery` on a full-text index created without `scoring`: BM25 ranking needs it enabled
- Use the BM25 embedder's `embed_document` for queries or `embed_query` for documents: the weighting differs and results go wrong
- Combine dense and keyword 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](https://skills.qdrant.tech/md/documentation/edge/)
- Claim support for a language beyond Python and Rust, or an OS or accelerator the Edge docs do not state

© qdrant · Apache-2.0 · qdrant/skills

Similar skills

All skills for Data and databases →

From the same set12

The whole set →
qdrant-monitoring This Claude Code skill guides Qdrant monitoring setup and troubleshooting. It routes health, metrics, and performance questions to the relevant instructions. CX Codex +1 1,600installs qdrant-version-upgrade The qdrant-version-upgrade Claude Code skill guides Qdrant server and SDK upgrades with version compatibility in mind. It covers upgrade sequencing, multi-version jumps, and behavior changes after a release. CX Codex +1 1,400installs qdrant-performance-optimization qdrant-performance-optimization — a routing skill for Qdrant tuning: it matches your symptom to the right sub-skill for search speed, indexing or memory. CX Codex +1 1,700installs qdrant-advisor qdrant-advisor fetches official troubleshooting guidance live from skills.qdrant.tech to diagnose vector search latency, memory spikes, and sharding issues. CX Codex +1 782installs qdrant-multitenancy qdrant-multitenancy — a skill for Claude Code, Codex, and Cursor. Guides tenant isolation architecture across users in Qdrant vector databases. CX Codex +1 298installs qdrant-sizing qdrant-sizing calculates RAM, disk space, CPU cores, and node count for a Qdrant deployment before hardware or cloud instances are provisioned. CX Codex +1 222installs qdrant-migration-tool The qdrant-migration-tool skill facilitates migrating vector data and metadata from various databases into Qdrant. It orchestrates the migration process, handles data streaming, and manages resume capabilities. CX Codex +1 137installs qdrant-hybrid-cloud-setup The qdrant-hybrid-cloud-setup Claude Code skill guides Qdrant Hybrid Cloud deployment on a self-managed Kubernetes cluster. It activates for agent and operator setup, storage and backups, or cluster access configuration. CX Codex +1 121installs

Project sponsors

Companies that keep this analytics open