client/v3.0.0

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