Migration & Compatibility
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.
Version Compatibility
Section titled “Version Compatibility”SDK and Milvus Compatibility
Section titled “SDK and Milvus Compatibility”| 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 |
Node.js Compatibility
Section titled “Node.js Compatibility”- Minimum: Node.js 18+
- Recommended: A currently supported Node.js LTS release
Checking Versions
Section titled “Checking Versions”Check SDK Version
Section titled “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
Section titled “Check Milvus Version”// Use Milvus API to check server versionconst info = await client.getMetric({ request: { metric_type: 'system_info', },});Migration Guides
Section titled “Migration Guides”Upgrading SDK Version
Section titled “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 versionyarn add @zilliz/milvus2-sdk-node@2.6- Test Thoroughly:
- Test all critical operations
- Verify data integrity
- Check performance
Upgrading Milvus Version
Section titled “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
Section titled “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 |
SDK 3.0.6–3.0.9 additions
Section titled “SDK 3.0.6–3.0.9 additions”- 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(), andrestoreExternalSnapshot()for portable snapshots. - The public
MilvusClientmethods for replication and WAL on Milvus 3.0.6 areupdateReplicateConfiguration(),getReplicateConfiguration(),getReplicateInfo(),createReplicateStream(), anddumpMessages(). The SDK also exposescomputePhraseMatchSlop()andbatchUpdateManifest(). - The gRPC system reference documents the proxy APIs
allocTimestamp(),getComponentStates(),registerLink(), anddummy()and the telemetry APIsgetClientTelemetry(),pushClientCommand(), anddeleteClientCommand(). - The REST reference covers all Milvus 3.0.6 v2 server routes.
HttpClientexposes the canonical SDK operations for collection changes, external refresh, snapshots, imports, access control, resource groups, text analysis, and diagnostics. Use the atomicaddFunctionField()anddropFunctionField()methods for function and output-field changes.
SDK 3.0.4–3.0.5 additions
Section titled “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
Section titled “Breaking Changes”Version 3.0.x Milvus 3.0
Section titled “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
Section titled “Version 2.6.x”- Enhanced type safety
- Improved error handling
- New index types support
Version 2.5.x
Section titled “Version 2.5.x”- Updated connection pooling
- Improved retry mechanisms
- Enhanced logging
Version 2.4.x
Section titled “Version 2.4.x”- Schema validation improvements
- Better error messages
- Performance optimizations
Compatibility Matrix
Section titled “Compatibility Matrix”Feature Compatibility
Section titled “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
Section titled “Upgrade Paths”From v2.6.x to v3.0.x Milvus 3.0
Section titled “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
Section titled “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
Section titled “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
Section titled “Deprecated Features”Deprecated Methods
Section titled “Deprecated Methods”Some methods may be deprecated in newer versions:
// Old method (deprecated)await client.alterCollection({ collection_name: 'my_collection', properties: { 'collection.ttl.seconds': 7200 },});
// New methodawait client.alterCollectionProperties({ collection_name: 'my_collection', properties: { 'collection.ttl.seconds': 7200 },});Migration Steps
Section titled “Migration Steps”- Check deprecation warnings
- Update to new methods
- Test functionality
- Remove old code
Best Practices for Migration
Section titled “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
Section titled “Getting Help”If you encounter issues during migration:
- Check Troubleshooting
- Review GitHub Issues
- Consult Milvus Documentation
Next Steps
Section titled “Next Steps”- Review Best Practices
- Check API Reference
- Explore Examples & Tutorials