github milvus-io/milvus client/v3.0.0
on GitHub

6 hours ago

client/v3.0.0

This is a stable release for Milvus 3.0. It is not guaranteed to be compatible with Milvus 2.6 servers.

Highlights

  • Migrates the Go module to github.com/milvus-io/milvus/client/v3.
  • Decouples the standalone client from Milvus server-side pkg modules, substantially reducing server-only transitive dependencies.
  • Adds collection snapshot management and asynchronous restore workflows, including external snapshot export and restore.
  • Adds read-only external collections with manual refresh support.
  • Adds search aggregation, search by primary-key IDs, query ordering, and namespace-scoped operations.
  • Adds client-side telemetry and structured RPC error inspection.
  • Adds search-time FunctionScore (scoring functions with boost_mode / function_mode) and weighted RRF reranking.
  • Adds drop-field / schema-alteration support through AlterCollectionSchema.
  • Adds TEXT field support and nullable StructArray (scalar and vector) support in the Go SDK.
  • Adds client-built membership filter blobs (Bloom/SBBF and Roaring) for membership_match expressions.
  • Adds FileResource (remote file) management APIs.
  • Adds the missing index types (HNSW SQ/PQ/PRQ, AISAQ, NGRAM, FM) and preserves generic index types.

Breaking Changes and Migration

  • Module path: Update all imports from: 

    github.com/milvus-io/milvus/client/v2

    to: 

    github.com/milvus-io/milvus/client/v3

  • Proto types: Applications directly using generated Milvus messages must migrate from milvus-proto/go-api/v2 to milvus-proto/go-api/v3. Although many high-level builders retain familiar APIs, v2 and v3 protobuf types are not interchangeable.

  • Installation: 

    go get github.com/milvus-io/milvus/client/v3@v3.0.0

  • Go version: The module's go directive is Go 1.24.9. The client README recommends Go 1.24.12 or later.

  • Telemetry behavior: Client telemetry is enabled by default. Set ClientConfig.TelemetryConfig.Enabled to false to disable heartbeat and metrics reporting.

  • ExportSnapshot return type changed from a snapshot path string to a int64 export job ID. Use the new GetExportSnapshotState to poll job progress. (#52476)

  • SDK version is now the GA SemVer 3.0.0 (was 3.0.0-beta).

New Features

  • Collection snapshots: Added APIs to create, drop, list, and describe collection-scoped snapshots. Snapshots can be restored asynchronously to new collections, with APIs for querying and listing restore jobs. Snapshot data can also be pinned and unpinned to control garbage collection. (#44361, #48143)

  • External snapshot export and restore: ExportSnapshot now starts a durable asynchronous export job and returns its job ID, GetExportSnapshotState and GetRestoreSnapshotState expose job progress, and RestoreExternalSnapshot restores referenced or exported snapshot bundles. (#52476)

  • External collections: Added schema builders for external data sources and external-field mappings:

    • Schema.WithExternalSource
    • Schema.WithExternalSpec
    • Field.WithExternalField

    External collections can be searched and queried using standard client APIs and refreshed through RefreshExternalCollection, GetRefreshExternalCollectionProgress, and ListRefreshExternalCollectionJobs. (#46886, #47492, #49531)

  • Search aggregation: Added bucket aggregation builders supporting multi-field keys, nested aggregations, top hits, ordering, and avg, sum, count, min, and max metrics. Results are returned through ResultSet.AggregationBuckets. (#50448)

  • Search by primary-key IDs: Added NewSearchByIDsOption and AnnRequest.WithIDs for using existing entities as vector-search inputs. Int64 and VarChar primary keys are supported. (#47633)

  • Namespace-scoped operations: Added WithNamespace support to Search, Hybrid Search, Query, iterators, Insert, Upsert, and Delete options. (#50153)

  • Query ordering: Added QueryOption.WithOrderByFields, accepting expressions such as price:desc and name:asc. An explicit query limit is required when ordering is used. (#51173, #51220)

  • Search-time FunctionScore: Added SearchOption.WithFunctionScore and HybridSearchOption.WithFunctionScore, carrying scoring Functions together with score-option params (boost_mode / function_mode). AnnRequest.WithFunctionReranker / HybridSearchOption.WithFunctionRerankers accumulate scoring Functions per request. (#53392)

  • Weighted RRF reranking: Added NewRRFReranker().WithWeights, applying per-ANN-request reciprocal-rank coefficients while preserving classic RRF when weights are omitted. (#52818)

  • Membership filters: Added client-side builders for membership_match expression-template parameters:

    • NewBloomFilterBlob(members, fpr) builds a Split-Block Bloom Filter (MBF1) blob for type=bloom.
    • NewRoaringBitmapBlob(members) builds an exact portable Roaring64 bitmap for type=roaring.

    Blobs travel as native protobuf bytes template values (WithTemplateParam), letting large membership sets pass the proxy gRPC receive limit. New client/membership/sbbf and client/membership/roaringfilter packages power the builders. (#53019)

  • Client telemetry: Added configurable collection of request counts, errors, and latency metrics, including P99 latency, recent-error tracking, periodic server heartbeats, and server-pushed command handling. (#47523, #47542)

  • Structured RPC errors: Added public RPCError, common error sentinels, ErrorCode, and IsRetryableError. RPC errors with matching Milvus codes can now be inspected using errors.Is.

  • Dynamic StructArray fields: Added Client.AddCollectionStructField and NewAddCollectionStructFieldOption, including validation and preservation of parent nullable and max_capacity metadata. (#50276)

  • Nullable StructArray support: StructArray scalar and vector sub-fields now honor NULL versus empty-array semantics end-to-end for inserts, queries, and searches, including compact nullable insert payloads, row-dense query/search results, and restoration of nullable StructArray columns for zero-row results with sub-field selections. (#51813)

  • TEXT fields: Added FieldTypeText (DataType 25), column.NewColumnText / NewNullableColumnText, and the column-based insert option WithTextColumn, for variable-length strings without a required max_length. (#52450)

  • Drop collection fields: Added DropCollectionField (by name or by ID), AddFunctionField, and DropFunctionField, routed through AlterCollectionSchema; legacy AddCollectionField remains as a compatibility fallback. (#51770)

  • FileResource APIs: Added AddFileResource, ListFileResources, and RemoveFileResource for managing remote files registered with Milvus. (#51470)

  • RBAC descriptions: Added user and role descriptions, role-description updates through AlterRole, and force-drop support for roles. (#50184, #50186, #47071)

  • Import two-phase commit: Added REST wrappers for committing or aborting bulk-import jobs through CommitImport and AbortImport. (#50177)

  • Message salvage API: Added the high-level Client.DumpMessages streaming wrapper for replication and recovery workflows. (#50343, #50574)

  • MinHash: Added FunctionTypeMinHash support to the Go SDK function API. (#45322)

  • Index types: Added the missing vector/scalar index models — HNSW SQ/PQ/PRQ (NewHNSWSQIndex / NewHNSWPQIndex / NewHNSWPRQIndex and matching ANN params), NewAISAQIndex, NewNgramIndex, and NewFMIndex. WithExtraIndexParams merges raw build params while refusing to override index_type/metric_type, so Params() and IndexType() never disagree. (#53392)

  • Request ID correlation: Added opt-in WithClientRequestID / NewClientRequestID to correlate a request with server logs and traces. (#53392)

Improvements and Bug Fixes

  • Default gRPC keepalive, reconnect, and receive-size options are now always applied before user-provided DialOptions. (#49186)
  • Row-based Insert and Upsert builders now preserve row-based processing when chaining partition, namespace, partial-update, and Array-operation options.
  • Client-local error, retry, crypto, concurrency, property, and type helpers replace the dependency on Milvus server packages.
  • Updated the v3 protobuf, gRPC, protobuf runtime, and supporting Go dependencies.
  • Streaming RPCs (e.g. DumpMessages) now apply client metadata through a new MetadataStreamInterceptor, fixing streaming gRPCs that previously bypassed authentication on the external proxy port. (#52608)
  • Client telemetry hardening: trustworthy windows/quantiles, fractional sampling that never rounds a positive rate to off, idempotent command cursor, panic-safe command handlers, bounded history, config-reply detail, and opt-in client_request_id correlation. (#53392)
  • merr now exposes ErrServiceUnimplemented, ErrParameterMissing, and the WrapErrParameterInvalidMsg / WrapErrParameterInvalidErr / WrapErrParameterMissingMsg helpers. (#51770)
  • BloomFilterBlob and RoaringBitmapBlob are distinct Go types so the builders cannot be mixed up; wrong-domain blobs are rejected by the proxy rather than silently matching nothing. (#53019)
Check out latest releases or
releases around milvus-io/milvus client/v3.0.0

Don't miss a new milvus release

NewReleases is sending notifications on new releases.

Get notifications