Skip to content
MilvusNode SDK
Sections

Migration & Compatibility

Markdown

Copy for agent

SDK 3.0.10 is tested with Milvus 3.0.6. SDK 3.x supports core operations on compatible Milvus 2.x deployments and Zilliz Cloud. Check your server version before relying on features introduced in Milvus 3.0.

Milvus version Node SDK version Installation
v3.0.0+ 3.0.x (3.0.10 tested with Milvus 3.0.6) yarn add @zilliz/milvus2-sdk-node@3
v2.6.0+ v2.6.x yarn add @zilliz/milvus2-sdk-node@2.6
v2.5.0+ v2.5.x yarn add @zilliz/milvus2-sdk-node@2.5.12
v2.4.0+ v2.4.9 yarn add @zilliz/milvus2-sdk-node@2.4.9
v2.3.0+ v2.3.5 yarn add @zilliz/milvus2-sdk-node@2.3.5
v2.2.0+ v2.3.5 yarn add @zilliz/milvus2-sdk-node@2.3.5
  • Minimum: Node.js 18+
  • Recommended: A currently supported Node.js LTS release
import { MilvusClient } from '@zilliz/milvus2-sdk-node';
console.log('SDK Version:', MilvusClient.sdkInfo.version);
console.log('Recommended Milvus:', MilvusClient.sdkInfo.recommendMilvus);
// Use Milvus API to check server version
const info = await client.getMetric({
request: {
metric_type: 'system_info',
},
});
  1. Check Compatibility:

    • Verify your Milvus version supports the new SDK version
    • Review breaking changes in release notes
  2. Update Package:

Terminal window
yarn add @zilliz/milvus2-sdk-node@latest
# or specific version
yarn add @zilliz/milvus2-sdk-node@2.6
  1. Test Thoroughly:
    • Test all critical operations
    • Verify data integrity
    • Check performance
  1. Backup Data: Always backup before upgrading

  2. Check SDK Compatibility: Ensure SDK version supports new Milvus version

  3. Update Milvus: Follow Milvus upgrade guide

  4. Update SDK: Update SDK to compatible version

  5. Test: Verify all operations work correctly

The following SDK features require a Milvus 3.0 server. They are marked with the Milvus 3.0 tag in the relevant guides and API reference pages.

Area SDK surface Docs
External collections external_source, external_spec, do_physical_backfill, file_resource_ids, field-level external_field, refreshExternalCollection(), getRefreshExternalCollectionProgress(), listRefreshExternalCollectionJobs() Collection Management, Collection Operations
Collection snapshots createSnapshot(), dropSnapshot(), listSnapshots(), describeSnapshot(), restoreSnapshot(), getRestoreSnapshotState(), listRestoreSnapshotJobs(), pinSnapshotData(), unpinSnapshotData() Collection Management, Collection Operations
Advanced StructArray Struct child schemas, nullable rows, dynamic nullable fields, child-field indexes, element_filter, element-level query/search/iterator offsets Data Types & Schemas, Query & Search
Query aggregation group_by_fields, aggregation expressions count, min, max, sum, and avg in output_fields Query & Search, Data Operations
Search aggregation search_aggregation, bucket metrics, ordering, top hits, nested aggregation, typed agg_buckets Query & Search, Data Operations
Partial array upsert upsert({ field_ops }), FieldPartialUpdateOpType.REPLACE, ARRAY_APPEND, ARRAY_REMOVE Insert & Update, Data Operations
Element-level result metadata Query/search result offset; grouped search group_by_field_values Query & Search, Data Operations
Schema and function management addCollectionField(), addCollectionFields(), dropCollectionField(), alterCollectionSchema(), addFunctionField(), dropFunctionField() Collection Management, Collection Operations
MinHash function and index FunctionType.MINHASH, IndexType.MINHASH_LSH, MetricType.MHJACCARD, atomic function-field/index creation Collection Management, Index Management
Analyzer file resources addFileResource(), listFileResources(), removeFileResource() Full-Text Search, System Operations
  • SDK 3.0.6 aligns membership filter expressions with Milvus. SDK 3.0.7 fixes core client behavior and moves CI to Milvus 3.0.6. SDK 3.0.8 adds StructArray support for nested Array sub-fields.
  • SDK 3.0.9 adds path replacement in partial upserts, function chains for gRPC search and query, and REST search aggregation alongside gRPC search aggregation. Use exportSnapshot(), getExportSnapshotState(), and restoreExternalSnapshot() for portable snapshots.
  • The public MilvusClient methods for replication and WAL on Milvus 3.0.6 are updateReplicateConfiguration(), getReplicateConfiguration(), getReplicateInfo(), createReplicateStream(), and dumpMessages(). The SDK also exposes computePhraseMatchSlop() and batchUpdateManifest().
  • The gRPC system reference documents the proxy APIs allocTimestamp(), getComponentStates(), registerLink(), and dummy() and the telemetry APIs getClientTelemetry(), pushClientCommand(), and deleteClientCommand().
  • The REST reference covers all Milvus 3.0.6 v2 server routes. HttpClient exposes the canonical SDK operations for collection changes, external refresh, snapshots, imports, access control, resource groups, text analysis, and diagnostics. Use the atomic addFunctionField() and dropFunctionField() methods for function and output-field changes.

See Release Notes for Text fields, asynchronous function-field backfill, membership-filter builders, additional index enums and public client telemetry.

  • SDK 3.x targets the Milvus 3.0 proto line while keeping the public package name @zilliz/milvus2-sdk-node.
  • Milvus 3.0-only APIs require a Milvus 3.0 server; older servers may return unimplemented or unknown-field errors.
  • Legacy replicate/CDC proto fields are deprecated upstream. Avoid building new integrations on them.
  • Enhanced type safety
  • Improved error handling
  • New index types support
  • Updated connection pooling
  • Improved retry mechanisms
  • Enhanced logging
  • Schema validation improvements
  • Better error messages
  • Performance optimizations
Feature Milvus 2.2 Milvus 2.3 Milvus 2.4 Milvus 2.5 Milvus 2.6 Milvus 3.0
Basic CRUD ✅ ✅ ✅ ✅ ✅ ✅
Index Types ✅ ✅ ✅ ✅ ✅ ✅
Dynamic Schema ✅ ✅ ✅ ✅ ✅ ✅
RBAC v2 ❌ ❌ ✅ ✅ ✅ ✅
Sparse Vectors ❌ ❌ ✅ ✅ ✅ ✅
Float16/BFloat16 ❌ ❌ ❌ ✅ ✅ ✅
External Collections ❌ ❌ ❌ ❌ ❌ ✅
Collection Snapshots ❌ ❌ ❌ ❌ ❌ ✅
Partial Array Upsert ❌ ❌ ❌ ❌ ❌ ✅
Element-Level Result Metadata ❌ ❌ ❌ ❌ ❌ ✅
Advanced StructArray ❌ ❌ ❌ ❌ ❌ ✅
Query Aggregation ❌ ❌ ❌ ❌ ❌ ✅
Search Aggregation ❌ ❌ ❌ ❌ ❌ ✅
Schema Field Drop ❌ ❌ ❌ ❌ ❌ ✅
MinHash Function ❌ ❌ ❌ ❌ ❌ ✅
Analyzer File Resources ❌ ❌ ❌ ❌ ❌ ✅
  1. Upgrade Milvus to 3.0 following the Milvus server upgrade guide.
  2. Update the Node SDK:
Terminal window
yarn add @zilliz/milvus2-sdk-node@latest
  1. If you use new 3.0 APIs, ensure your deployment is actually connected to a Milvus 3.0 server.
  2. Test collection management, write paths, and query/search result parsing before production rollout.
  1. Update SDK:
Terminal window
yarn add @zilliz/milvus2-sdk-node@2.6
  1. Update code (if needed):
    • Review API changes
    • Update deprecated methods
    • Test thoroughly
  1. Update SDK:
Terminal window
yarn add @zilliz/milvus2-sdk-node@2.6
  1. Test new features:
    • Try new index types
    • Test performance improvements

Some methods may be deprecated in newer versions:

// Old method (deprecated)
await client.alterCollection({
collection_name: 'my_collection',
properties: { 'collection.ttl.seconds': 7200 },
});
// New method
await client.alterCollectionProperties({
collection_name: 'my_collection',
properties: { 'collection.ttl.seconds': 7200 },
});
  1. Check deprecation warnings
  2. Update to new methods
  3. Test functionality
  4. Remove old code
  1. Test in Development: Always test upgrades in development first

  2. Gradual Rollout: Roll out upgrades gradually in production

  3. Monitor: Monitor for errors after upgrade

  4. Rollback Plan: Have a rollback plan ready

  5. Documentation: Keep track of changes and configurations

If you encounter issues during migration:

  1. Check Troubleshooting
  2. Review GitHub Issues
  3. Consult Milvus Documentation