sema-upstash-vector

Store and search vector embeddings in an Upstash Vector database over its REST API.

Install

sema pkg add sema-upstash-vector

Quick start

(import "sema-upstash-vector")

(define c (upstash-vector/client))  ; url + token from env

(upstash-vector/upsert! c
  (list {:id "a" :vector (list 0.1 0.2 0.3 0.4) :metadata {:title "Intro"}}
        {:id "b" :vector (list 0.9 0.8 0.7 0.6) :metadata {:title "Guide"}}))

(upstash-vector/query c (list 0.1 0.2 0.3 0.4) {:top-k 1})
;; => ({:id "a" :score 1.0 :metadata {:title "Intro"}})

Authentication

The client reads your index URL and token from the UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables, or you can pass them explicitly. You'll find both in the Upstash console for your index.

(upstash-vector/client)                                                   ; from env
(upstash-vector/client {:url "https://xxx.upstash.io" :token "your-tok"}) ; inline

The token is sent in the Authorization: Bearer header and is never logged.

API

Every option map accepts :namespace (default "", the default namespace).

upstash-vector/client

(upstash-vector/client opts?) — opts: :url (default UPSTASH_VECTOR_REST_URL), :token (default UPSTASH_VECTOR_REST_TOKEN), :timeout ms (default 30000).

(upstash-vector/client {:timeout 10000})

upstash-vector/upsert!

(upstash-vector/upsert! client vectors opts?) — vectors is a map or a list of maps, each with :id, :vector, and optional :metadata / :data.

(upstash-vector/upsert! c
  (list {:id "a" :vector (list 0.1 0.2 0.3 0.4) :metadata {:title "Intro"}}))

upstash-vector/query

(upstash-vector/query client vector opts?) — vector is a list of numbers. opts: :top-k (default 10), :include-metadata (default #t), :include-vectors (default #f), :include-data (default #f), :filter (a metadata filter string).

(upstash-vector/query c (list 0.1 0.2 0.3 0.4)
  {:top-k 5 :filter "title = 'Intro'"})

upstash-vector/fetch

(upstash-vector/fetch client ids opts?) — ids is a list of ids. opts: :include-metadata (default #t), :include-vectors (default #f), :include-data (default #f).

(upstash-vector/fetch c (list "a" "b") {:include-vectors #t})

upstash-vector/delete!

(upstash-vector/delete! client ids opts?) — deletes vectors by id. Returns {:deleted N}.

(upstash-vector/delete! c (list "a" "b"))

upstash-vector/info

(upstash-vector/info client) — returns index stats (vector count, pending count, dimension, similarity function, namespaces).

(upstash-vector/info c)

upstash-vector/reset!

(upstash-vector/reset! client opts?) — deletes every vector in a namespace. Irreversible.

(upstash-vector/reset! c {:namespace "staging"})

upstash-vector/request

(upstash-vector/request client method path body) — raw call for endpoints the wrappers don't cover. method is "GET"/"POST"/"DELETE"; path is an API path (e.g. "/query/my-namespace"); body is a map/list or nil. Returns the full decoded response map ({:result ...}) and raises on non-2xx.

(upstash-vector/request c "GET" "/info" nil)

Testing

sema tests.sema

Offline tests cover client construction, argument validation, and error handling. Live tests run only when both UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN are set; they upsert into a throwaway namespace, query, and reset it.

License

MIT