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

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	❌	❌	❌	❌	❌	✅
Advanced StructArray	❌	❌	❌	❌	❌	✅
Query Aggregation	❌	❌	❌	❌	❌	✅
Search Aggregation	❌	❌	❌	❌	❌	✅
Schema Field Drop	❌	❌	❌	❌	❌	✅
MinHash Function	❌	❌	❌	❌	❌	✅
Analyzer File Resources	❌	❌	❌	❌	❌	✅

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