Migration & Compatibility

This guide covers version compatibility, migration paths, and breaking changes.

Version Compatibility

SDK and Milvus Compatibility

Milvus version	Node SDK version	Installation
v3.0.0+	v3.0.0+ / latest	yarn add @zilliz/milvus2-sdk-node@latest
v2.6.0+	v2.6.x	yarn add @zilliz/milvus2-sdk-node@2.6.9
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

Node.js Compatibility

• Minimum: Node.js 18+
• Recommended: Node.js 20+ (LTS)

Checking Versions

Check SDK Version

import { MilvusClient } from '@zilliz/milvus2-sdk-node';

console.log('SDK Version:', MilvusClient.sdkInfo.version);
console.log('Recommended Milvus:', MilvusClient.sdkInfo.recommendMilvus);

Check Milvus Version

// Use Milvus API to check server version
const info = await client.getMetric({
  request: {
    metric_type: 'system_info',
  },
});

Migration Guides

Upgrading SDK Version

1. Check Compatibility:

   • Verify your Milvus version supports the new SDK version
   • Review breaking changes in release notes

2. Update Package:

yarn add @zilliz/milvus2-sdk-node@latest
# or specific version
yarn add @zilliz/milvus2-sdk-node@2.6.9

3. Test Thoroughly:
   • Test all critical operations
   • Verify data integrity
   • Check performance

Upgrading Milvus Version

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

Milvus 3.0 feature coverage Milvus 3.0

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
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(), addCollectionFunction(), alterCollectionFunction(), dropCollectionFunction()	Collection Management, Collection Operations

Not all Milvus 3.0 proto additions are public Node SDK APIs yet. Client telemetry, WAL dump/data-salvage APIs, ComputePhraseMatchSlop, BatchUpdateManifest, and full molecular data helpers are currently proto-level/internal surfaces unless explicitly exposed in a later SDK release.

Breaking Changes

Version 3.0.x Milvus 3.0

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

Version 2.6.x

• Enhanced type safety
• Improved error handling
• New index types support

Version 2.5.x

• Updated connection pooling
• Improved retry mechanisms
• Enhanced logging

Version 2.4.x

• Schema validation improvements
• Better error messages
• Performance optimizations

Compatibility Matrix

Feature Compatibility

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	❌	❌	❌	❌	❌	✅

Upgrade Paths

From v2.6.x to v3.0.x Milvus 3.0

1. Upgrade Milvus to 3.0 following the Milvus server upgrade guide.
2. Update the Node SDK:

yarn add @zilliz/milvus2-sdk-node@latest

3. If you use new 3.0 APIs, ensure your deployment is actually connected to a Milvus 3.0 server.
4. Test collection management, write paths, and query/search result parsing before production rollout.

From v2.3.x to v2.6.x

1. Update SDK:

yarn add @zilliz/milvus2-sdk-node@latest

2. Update code (if needed):
   • Review API changes
   • Update deprecated methods
   • Test thoroughly

From v2.4.x to v2.6.x

1. Update SDK:

yarn add @zilliz/milvus2-sdk-node@latest

2. Test new features:
   • Try new index types
   • Test performance improvements

Deprecated Features

Deprecated Methods

Some methods may be deprecated in newer versions:

// Old method (deprecated)
client.alterCollection({
  /* ... */
});

// New method
client.alterCollectionProperties({
  /* ... */
});

Migration Steps

1. Check deprecation warnings
2. Update to new methods
3. Test functionality
4. Remove old code

Best Practices for Migration

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

Getting Help

If you encounter issues during migration:

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

Next Steps

• Review Best Practices
• Check API Reference
• Explore Examples & Tutorials