milvus-clj.client — io.github.hive-agi/milvus-clj 0.2.3

Transport-abstract Milvus client.

Defines the IMilvusCore, IMilvusAdmin, IMilvusExtras protocols, the make factory dispatching on :transport, the with-client macro for ephemeral lifetimes, and classify-error for transport- specific failure classification.

Caller picks the transport:

(require '[milvus-clj.client :as client])

(client/with-client [c {:transport :grpc
                        :host "milvus.prod" :port 19530
                        :token "root:pw"}]
  (client/-query c "memories" {:vector [...] :limit 10}))

(client/with-client [c {:transport :http
                        :host "milvus.prod" :port 9091
                        :token "root:pw"}]
  (client/-query c "memories" {:vector [...] :limit 10}))

Adding a third transport is a new file under milvus-clj.transport.* plus one extra case arm in make. Nothing else changes — OCP.

classify-error clj

(classify-error ex)

Classify an exception thrown from a protocol method into one of: :connection-failure — transport-level, safe to retry after reconnect :retryable — transient (5xx, throttle), safe to retry in place :fatal — caller bug / schema mismatch / auth failure

Each transport attaches ::transport in the ex-data. This dispatches on that key so the classification logic lives in the transport ns (only the transport knows which of its exception shapes are transient).

Callers (e.g. hive-milvus.store/with-auto-reconnect) should use this predicate rather than pattern-matching on exception classes directly.

ILivenessProbe clj protocol

Single-method seam for transport-agnostic liveness verification.

Distinct from IMilvusCore on purpose (ISP): the resilience layer (hive-milvus.resilience.*) probes connections without coupling to data-plane operations it does not need. Each transport implements -probe! with the cheapest RPC it can: HTTP HEAD, gRPC unary, etc.

Contract:

• Return truthy iff the server-side endpoint is reachable.
• Throw on transport-fatal failure so callers can classify via client/classify-error. IO-class throws -> :connection-failure (the resilience layer interprets this as 'still dead, keep retrying'); fatal throws bubble up unchanged.
• MUST be idempotent and side-effect-free at the application level (no writes, no state mutation in milvus). The only allowed side effect is a single read-shaped RPC.

Default impl: callers fall back to (-has-collection client "__probe__") for any IMilvusCore that does not extend ILivenessProbe.

-probe! clj

(-probe! client)

Issue a minimal liveness RPC. Truthy on success; throws on IO.

IMilvusAdmin clj protocol

Collection admin operations. Implemented by gRPC and HTTP transports; optional for future specialized transports.

-create-collection clj

(-create-collection client collection-name opts)

Create a collection with schema + optional index config in one call. Returns {:collection-name name :status :created}.

-describe clj

(-describe client collection-name)

Describe schema and load state. Doubles as a health probe.

-drop-collection clj

(-drop-collection client collection-name)

Destructively drop the collection. Returns {:collection-name name :status :dropped}.

IMilvusCore clj protocol

Core data-plane operations. Required for every transport. All methods are synchronous; the caller wraps in future if async is needed (the legacy milvus-clj.api shim does this for backward compat with hive-milvus's @(milvus/...) pattern).

-delete clj

(-delete client collection-name ids opts)

Delete rows by ID list. Returns {:deleted n}.

-has-collection clj

(-has-collection client collection-name)

Return boolean — does the collection exist?

-get clj

(-get client collection-name ids opts)

Fetch rows by ID list. Returns a vector of entry maps.

-close clj

(-close client)

Release resources. Idempotent.

-load-collection clj

(-load-collection client collection-name)

Load collection into memory for search. Idempotent. Returns {:collection-name name :status :loaded}.

-insert clj

(-insert client collection-name records opts)

Insert rows. Returns {:count n :mutation :insert}.

-upsert clj

(-upsert client collection-name records opts)

Upsert rows (replace by PK). Returns {:count n :mutation :upsert}.

-query clj

(-query client collection-name q-map)

Vector similarity search. Returns a vector of entries each with :distance attached.

-query-scalar clj

(-query-scalar client collection-name q-map)

Scalar filter query (no vector). Returns a vector of entry maps.

IMilvusExtras clj protocol

Rarely-used operations. Optional — a minimal transport implementation may leave these unimplemented. hive-milvus does not call any of these today; kept in the protocol surface for future use.

-create-index clj

(-create-index client collection-name index-opts)

-drop-index clj

(-drop-index client collection-name field-name)

-flush-collection clj

(-flush-collection client collection-name)

-list-collections clj

(-list-collections client)

-release-collection clj

(-release-collection client collection-name)

make clj

(make {:keys [transport] :as opts})

Construct an IMilvusCore implementation for the chosen transport.

opts must have :transport — one of :grpc or :http. Transport-specific keys live under (:grpc opts) or (:http opts); agnostic keys (:host, :port, :token, :database) sit at the top level of opts.

See milvus-clj.config for default merging and validation.

probe! clj

(probe! client)

Public helper. Calls -probe! if the client extends ILivenessProbe, otherwise falls back to (-has-collection client "__milvus_clj_probe__") so any transport implementing IMilvusCore can be probed.

Returns truthy on success, throws on IO/fatal.

with-client clj macro

(with-client [binding opts] & body)

Open a client, run body, close deterministically.

Example: (with-client [c {:transport :grpc :host "localhost" :port 19530}] (-query c "memories" {:vector [...] :limit 10}))