sema-qdrant

Store and search vector embeddings in a Qdrant vector database over its REST API.

Install

sema pkg add sema-qdrant

Quick start

(import "sema-qdrant")

(define c (qdrant/client {:url "https://xyz.qdrant.io"}))  ; key from QDRANT_API_KEY

(qdrant/create-collection! c "docs" {:size 4 :distance "Cosine"})

(qdrant/upsert! c "docs"
  (list {:id 1 :vector (list 0.1 0.2 0.3 0.4) :payload {:title "Intro"}}
        {:id 2 :vector (list 0.9 0.8 0.7 0.6) :payload {:title "Guide"}}))

(qdrant/search c "docs" (list 0.1 0.2 0.3 0.4) {:limit 1})
;; => ({:id 1 :version 0 :score 1.0 :payload {:title "Intro"}})

Authentication

The client reads your API key from the QDRANT_API_KEY environment variable, or you can pass it explicitly. The cluster URL is always required — pass it as :url.

(qdrant/client {:url "https://xyz.qdrant.io"})                       ; key from env
(qdrant/client {:url "https://xyz.qdrant.io" :api-key "your-key"})   ; key inline

The key is sent in the api-key request header and is never logged.

API

qdrant/client

(qdrant/client opts?) — opts: :url (required, your cluster URL), :api-key (default QDRANT_API_KEY), :timeout ms (default 30000).

(qdrant/client {:url "https://xyz.qdrant.io" :timeout 10000})

qdrant/create-collection!

(qdrant/create-collection! client name opts) — opts must include :size (vector dimensions); may set :distance (default "Cosine"; also "Euclid", "Dot", "Manhattan") and :on-disk (default #f).

(qdrant/create-collection! c "docs" {:size 384 :distance "Cosine"})

qdrant/upsert!

(qdrant/upsert! client name points opts?) — points is a list of maps with :id, :vector, and optional :payload. opts: :wait (default #t), :ordering ("weak"/"medium"/"strong").

(qdrant/upsert! c "docs"
  (list {:id 1 :vector (list 0.1 0.2 0.3 0.4) :payload {:title "Intro"}}))

qdrant/search

(qdrant/search client name vector opts?) — vector is a list of numbers. opts: :limit (default 10), :filter (a Qdrant filter map), :with-payload (default #t), :with-vector (default #f), :offset, :score-threshold.

(qdrant/search c "docs" (list 0.1 0.2 0.3 0.4)
  {:limit 5
   :filter {:must (list {:key "title" :match {:value "Intro"}})}})

qdrant/delete-collection!

(qdrant/delete-collection! client name) — deletes the collection and its points.

(qdrant/delete-collection! c "docs")

qdrant/request

(qdrant/request client method path body) — raw call for endpoints the wrappers don't cover. method is "GET"/"PUT"/"POST"/"DELETE"; path may include a query string; body is a map or nil. Returns the full decoded response map ({:result ... :status ... :time ...}) and raises on non-2xx.

(qdrant/request c "GET" "/collections/docs" nil)

Testing

sema tests.sema

Offline tests cover client construction, argument validation, and error handling. Live tests run only when both QDRANT_API_KEY and QDRANT_URL are set; they create a throwaway collection, upsert, search, and delete it.

License

MIT