client/v3.0.0-beta

This is the first beta release of the Milvus Go SDK v3, targeting Milvus 3.0. It is compared against client/v2.6.5.

This is a beta release. APIs and protocol details may change before v3.0.0 GA.

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.
• 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.

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-beta

• 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.

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 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)

• 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)

• 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)

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.

Known Limitations

• This SDK release is intended for Milvus 3.0 beta and is not guaranteed to be compatible with Milvus 2.6 servers.
• ExportSnapshot and RestoreExternalSnapshot expose preview API contracts in this release, but the server implementation currently returns Unimplemented.
• Flush a collection before creating a snapshot if growing-segment data must be included.
• External collections are read-only; Insert, Upsert, Delete, Import, partition management, and schema alteration are not supported.
• Primary keys must remain unique across namespaces within the same collection because delete and upsert tombstones remain collection-scoped.
• Search aggregation cannot be combined with legacy group-by, offsets, or search iterators. Bracketed JSON-path expressions are not yet supported.
• Search by primary-key IDs is not supported in Hybrid Search or Search Iterator.