#yuzhiblue/moon-qdrant

#Why

#Install

moon add yuzhiblue/moon-qdrant

#Quick start

docker run -p 6333:6333 qdrant/qdrant

let client = QdrantClient::new("http://localhost:6333")

// health check
let ok = client.health()

// create a collection with 4-dimensional cosine vectors
client.create_collection(
  "demo",
  CollectionConfig::new(VectorParams::new(4, Distance::Cosine)),
)

// list collections
let names = client.list_collections()

// inspect a collection
let info = client.collection_info("demo")

// does it exist?
let exists = client.collection_exists("demo")

// write some points
client.upsert_points("demo", [
  PointStruct::new(1, [0.1, 0.2, 0.3, 0.4], { "tag": "alpha" }),
  PointStruct::new(2, [0.5, 0.6, 0.7, 0.8], { "tag": "beta" }),
])

// ids are Int64, matching Qdrant's u64 point ids. Even ids above 2^53,
// where a Double can no longer hold every integer, round-trip exactly:
client.upsert_points("demo", [
  PointStruct::new(
    9007199254740993L,
    [0.2, 0.3, 0.4, 0.5],
    { "tag": "big" },
  ),
])

// read one back
let point = client.get_point("demo", 1)

// search for the most similar points
let hits = client.search_points("demo", [0.1, 0.2, 0.3, 0.4], limit=2)

// search with a payload filter
let filtered = client.search_points(
  "demo",
  [0.1, 0.2, 0.3, 0.4],
  limit=2,
  filter={ "must": [{ "key": "tag", "match": { "value": "alpha" } }] },
)

// delete points by id
client.delete_points("demo", [2])

// drop the collection
client.delete_collection("demo")

#Advanced search

// only hits scoring 0.9 or better, skipping the first hit

///|
let hits = client.search_points(
  "demo",
  [0.1, 0.2, 0.3, 0.4],
  2,
  score_threshold=Some(0.9),
  offset=Some(1),
  search_params=Some(SearchParams::new(exact=Some(true))),
)

// several searches in one round trip

///|
let batch = client.search_points_batch("demo", [
  { "vector": [0.1, 0.2, 0.3, 0.4], "limit": 2 },
  { "vector": [0.9, 0.8, 0.7, 0.6], "limit": 2 },
])

#Named vectors

let named : Map[String, VectorParams] = Map([])
named["text"] = VectorParams::new(4, Distance::Cosine)
named["image"] = VectorParams::new(8, Distance::Dot)
client.create_collection("multi", CollectionConfig::new_named(named))

let vectors : Map[String, Array[Double]] = Map([])
vectors["text"] = [0.1, 0.2, 0.3, 0.4]
vectors["image"] = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
client.upsert_points("multi", [PointStruct::new_named(1, vectors, { "tag": "a" })])

// search against the "text" vector
let hits = client.search_points(
  "multi",
  [0.1, 0.2, 0.3, 0.4],
  1,
  using_vector=Some("text"),
)
// or via a NamedVector input
let hits = client.search_points_named(
  "multi",
  NamedVector::new("image", [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]),
  1,
)

#Payload management

// merge fields into the payload of points 1 and 2
client.set_payload("demo", { "active": true }, ids=Some([1, 2]))
// replace the whole payload of points matching a filter
client.overwrite_payload(
  "demo",
  { "state": "new" },
  filter=Some(Filter::new().must(Condition::match_keyword("tag", "alpha"))),
)
// drop selected keys from point 1
client.delete_payload_by_keys("demo", ["active"], ids=Some([1]))
// drop the whole payload of all points matching a filter
client.delete_payload("demo", filter=Some(Filter::new()))

#Query API and facets

// nearest neighbor
let hits = client.query_nearest("demo", [0.1, 0.2, 0.3, 0.4], 2)

// recommendation: like the positive vectors, unlike the negative ones
let positive : Array[Json] = [
  Json::array([0.1, 0.2, 0.3, 0.4]),
  Json::number(3), // point ids are accepted too
]
let negative : Array[Json] = [Json::array([0.9, 0.8, 0.7, 0.6])]
let recs = client.query_recommend(
  "demo",
  positive,
  negative=Some(negative),
  limit=5,
)

// facet: how many points carry each distinct value of a payload field
let facet = client.facet_points("demo", "tag", 10)
for hit in facet.hits {
  println(hit.value.stringify() + ": " + hit.count.to_string())
}

// grouped search: top hits per distinct payload value
let groups = client.search_points_groups(
  "demo",
  [0.1, 0.2, 0.3, 0.4],
  2,     // hits per group
  "tag", // group-by field
  10,    // max groups
)
for group in groups {
  println(
    "group " + group.id.stringify() + " -> " +
    group.hits.length().to_string() + " hits",
  )
}

#Cluster, locks and server info

// cluster state (works on single-node deployments too)
let cluster = client.cluster_info()
println("cluster status: " + cluster.status)
println("peers: " + cluster.peers.length().to_string())

// per-collection shard / replica layout
let layout = client.collection_cluster_info("demo")
for shard in layout.local_shards {
  println(
    "shard " + shard.shard_id.to_string() + ": " +
    shard.state + " (" + shard.points_count.to_string() + " points)",
  )
}

// shard lifecycle (multi-node clusters). Qdrant's cluster API takes a
// single-key operation object; `create_shard_replica` maps to the
// `replicate_shard` operation and `delete_shard_replica` to `drop_replica`,
// the operation names Qdrant actually accepts. The source peer is looked up
// automatically; pass `from_peer_id=...` to override. A single-node server
// answers any cluster operation with "Distributed mode disabled" — that is a
// server limit, not a malformed request.
client.replicate_shard("demo", 0L, 1L, 2L)
client.create_shard_replica("demo", 0L, 2L)
client.delete_shard_replica("demo", 0L, 2L)

// write lock + server version
client.set_locks(true, error_message=Some("maintenance"))
let lock = client.get_locks()
println("writes locked: " + lock.write.to_string())
let info = client.service_info()
match info.version {
  Some(v) => println("qdrant version: " + v)
  None => ()
}

#Collection updates, payload indexes and snapshots

// update replication settings
client.update_collection(
  "demo",
  CollectionUpdate::new(replication_factor=Some(2)),
)

// index a payload field for fast filtered access
client.create_payload_index("demo", "tag", "keyword")
let indexes = client.list_payload_indexes("demo")
client.delete_payload_index("demo", "tag")

// snapshot the collection for backup / migration
let snap = client.create_snapshot("demo")
let snapshots = client.list_snapshots("demo")
client.delete_snapshot("demo", snap.name)

#Examples

moon run cmd/main -- http://localhost:6333

docker run -p 6333:6333 qdrant/qdrant
moon run examples/demo -- http://localhost:6333

#Status / roadmap

• GET /healthz health check
• GET /collections list collections
• PUT /collections/{name} create collection (single or named vectors)
• PATCH /collections/{name} update collection settings
• GET /collections/{name} collection info
• DELETE /collections/{name} delete collection
• GET /collections/{name}/exists collection existence check
• PUT /collections/{name}/points upsert points (dense or named vectors)
• GET /collections/{name}/points/{id} get a point
• POST /collections/{name}/points/delete delete points by id or filter
• POST /collections/{name}/points/search vector search with payload filters, score_threshold, offset, named-vector using and search params
• POST /collections/{name}/points/search/batch batch search
• POST /collections/{name}/points/search/groups grouped search
• typed filter DSL (Condition / Filter builder over must/should/must_not)
• PUT /collections/{name}/points/batch batch upsert
• POST /collections/{name}/points/scroll paginated point scrolling
• POST /collections/{name}/points/count point count (exact or estimated)
• POST /collections/{name}/points batch retrieve by ids
• PUT|POST /collections/{name}/points/payload set / overwrite payload
• POST /collections/{name}/points/payload/delete delete payload (whole payload or selected keys)
• PUT|GET /collections/{name}/index / DELETE /collections/{name}/index/{field} payload indexes
• POST /collections/{name}/points/query query API (query_nearest / query_recommend / raw query_points)
• POST /collections/{name}/facet facet counts
• POST /collections/aliases / GET /aliases collection aliases
• GET|POST|DELETE /collections/{name}/snapshots snapshot management
• GET|POST /locks service write lock
• GET / server info (version / commit)
• GET /cluster cluster state (status, peers, raft info)
• GET /collections/{name}/cluster per-collection shard / replica layout
• POST /collections/{name}/cluster shard operations (replicate_shard, create_shard_replica, delete_shard_replica)
• unified VectorProvider trait (extensible to other vector services)

• cluster telemetry (GET /cluster/telemetry)

#Development

moon check --deny-warn
moon test
moon fmt

#Integration testing against a real Qdrant

docker run -p 6333:6333 qdrant/qdrant
moon run examples/integration_check -- http://localhost:6333
moon run examples/demo -- http://localhost:6333

#Reproducibility

#License