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`
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: A currently supported Node.js LTS release

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

Check Compatibility:
- Verify your Milvus version supports the new SDK version
- Review breaking changes in release notes
Update Package:

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

Test Thoroughly:
- Test all critical operations
- Verify data integrity
- Check performance

Upgrading Milvus Version

Backup Data: Always backup before upgrading
Check SDK Compatibility: Ensure SDK version supports new Milvus version
Update Milvus: Follow Milvus upgrade guide
Update SDK: Update SDK to compatible version
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. 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.

SDK 3.0.4–3.0.5 additions

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

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

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

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

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

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

Update SDK:

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

Update code (if needed):
- Review API changes
- Update deprecated methods
- Test thoroughly

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

Update SDK:

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

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

Check deprecation warnings
Update to new methods
Test functionality
Remove old code

Best Practices for Migration

Test in Development: Always test upgrades in development first
Gradual Rollout: Roll out upgrades gradually in production
Monitor: Monitor for errors after upgrade
Rollback Plan: Have a rollback plan ready
Documentation: Keep track of changes and configurations

Getting Help

If you encounter issues during migration: