# Migration & Compatibility

Check Milvus Node.js SDK and server compatibility, review breaking changes, and plan upgrades.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/

## Section links

- [Version Compatibility](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#version-compatibility)
- [SDK and Milvus Compatibility](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#sdk-and-milvus-compatibility)
- [Node.js Compatibility](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#nodejs-compatibility)
- [Checking Versions](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#checking-versions)
- [Check SDK Version](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#check-sdk-version)
- [Check Milvus Version](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#check-milvus-version)
- [Migration Guides](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#migration-guides)
- [Upgrading SDK Version](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#upgrading-sdk-version)
- [Upgrading Milvus Version](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#upgrading-milvus-version)
- [Milvus 3.0 feature coverage Milvus 3.0](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#milvus-30-feature-coverage-milvus-30)
- [SDK 3.0.6–3.0.9 additions](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#sdk-306309-additions)
- [SDK 3.0.4–3.0.5 additions](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#sdk-304305-additions)
- [Breaking Changes](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#breaking-changes)
- [Version 3.0.x Milvus 3.0](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#version-30x-milvus-30)
- [Version 2.6.x](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#version-26x)
- [Version 2.5.x](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#version-25x)
- [Version 2.4.x](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#version-24x)
- [Compatibility Matrix](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#compatibility-matrix)
- [Feature Compatibility](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#feature-compatibility)
- [Upgrade Paths](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#upgrade-paths)
- [From v2.6.x to v3.0.x Milvus 3.0](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#from-v26x-to-v30x-milvus-30)
- [From v2.3.x to v2.6.x](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#from-v23x-to-v26x)
- [From v2.4.x to v2.6.x](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#from-v24x-to-v26x)
- [Deprecated Features](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#deprecated-features)
- [Deprecated Methods](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#deprecated-methods)
- [Migration Steps](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#migration-steps)
- [Best Practices for Migration](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#best-practices-for-migration)
- [Getting Help](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#getting-help)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/reference/migration-compatibility/#next-steps)

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

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

- **Minimum**: Node.js 18+
- **Recommended**: A currently supported Node.js LTS release

## Checking Versions

### Check SDK Version

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

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

### Check Milvus Version

```javascript
// 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**:

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

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](https://milvus-io.github.io/milvus-sdk-node/management/collection-management/), [Collection Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/collections/) |
| Collection snapshots | `createSnapshot()`, `dropSnapshot()`, `listSnapshots()`, `describeSnapshot()`, `restoreSnapshot()`, `getRestoreSnapshotState()`, `listRestoreSnapshotJobs()`, `pinSnapshotData()`, `unpinSnapshotData()` | [Collection Management](https://milvus-io.github.io/milvus-sdk-node/management/collection-management/), [Collection Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/collections/) |
| Advanced StructArray | Struct child schemas, nullable rows, dynamic nullable fields, child-field indexes, `element_filter`, element-level query/search/iterator offsets | [Data Types & Schemas](https://milvus-io.github.io/milvus-sdk-node/core-concepts/data-types-schemas/#structarray), [Query & Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#structarray-element-filters) |
| Query aggregation | `group_by_fields`, aggregation expressions `count`, `min`, `max`, `sum`, and `avg` in `output_fields` | [Query & Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-aggregation), [Data Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#query-aggregation) |
| Search aggregation | `search_aggregation`, bucket metrics, ordering, top hits, nested aggregation, typed `agg_buckets` | [Query & Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-aggregation), [Data Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/#search-aggregation) |
| Partial array upsert | `upsert({ field_ops })`, `FieldPartialUpdateOpType.REPLACE`, `ARRAY_APPEND`, `ARRAY_REMOVE` | [Insert & Update](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-insert/), [Data Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/) |
| Element-level result metadata | Query/search result `offset`; grouped search `group_by_field_values` | [Query & Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/), [Data Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/data/) |
| Schema and function management | `addCollectionField()`, `addCollectionFields()`, `dropCollectionField()`, `alterCollectionSchema()`, `addFunctionField()`, `dropFunctionField()` | [Collection Management](https://milvus-io.github.io/milvus-sdk-node/management/collection-management/#dynamic-schema), [Collection Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/collections/#schema-mutation) |
| MinHash function and index | `FunctionType.MINHASH`, `IndexType.MINHASH_LSH`, `MetricType.MHJACCARD`, atomic function-field/index creation | [Collection Management](https://milvus-io.github.io/milvus-sdk-node/management/collection-management/#add-a-function-output-field-and-index), [Index Management](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#minhash_lsh) |
| Analyzer file resources | `addFileResource()`, `listFileResources()`, `removeFileResource()` | [Full-Text Search](https://milvus-io.github.io/milvus-sdk-node/advanced/full-text-search/#custom-dictionary-files), [System Operations](https://milvus-io.github.io/milvus-sdk-node/api-reference/system/#file-resources) |

## SDK 3.0.6–3.0.9 additions

- SDK 3.0.6 aligns [membership filter expressions](https://milvus-io.github.io/milvus-sdk-node/advanced/membership-filters/) 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](https://milvus-io.github.io/milvus-sdk-node/api-reference/system/) documents the proxy APIs `allocTimestamp()`, `getComponentStates()`, `registerLink()`, and `dummy()` and the telemetry APIs `getClientTelemetry()`, `pushClientCommand()`, and `deleteClientCommand()`.
- The [REST reference](https://milvus-io.github.io/milvus-sdk-node/rest-api/) covers all Milvus 3.0.6 v2 server routes. [`HttpClient`](https://milvus-io.github.io/milvus-sdk-node/api-reference/http-client/) 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.

## SDK 3.0.4–3.0.5 additions

See [Release Notes](https://milvus-io.github.io/milvus-sdk-node/reference/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

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

```bash
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:

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

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

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

1. Update SDK:

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

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

## Deprecated Features

### Deprecated Methods

Some methods may be deprecated in newer versions:

```javascript
// 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 },
});
```

### 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](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/)
2. Review [GitHub Issues](https://github.com/milvus-io/milvus-sdk-node/issues)
3. Consult [Milvus Documentation](https://milvus.io/docs)

## Next Steps

- Review [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)
- Check [API Reference](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- Explore [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)
