# Best Practices

Run the Milvus Node.js SDK in production with connection reuse, batch writes, appropriate indexes, and retry handling.

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

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/

## Section links

- [Connection Management](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#connection-management)
- [Reuse Client Instances](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#reuse-client-instances)
- [Proper Cleanup](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#proper-cleanup)
- [Connection Pooling](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#connection-pooling)
- [Error Handling Strategies](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#error-handling-strategies)
- [Comprehensive Error Handling](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#comprehensive-error-handling)
- [Retry Logic](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#retry-logic)
- [Performance Optimization](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#performance-optimization)
- [Batch Operations](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#batch-operations)
- [Load Collections Before Search](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#load-collections-before-search)
- [Use Appropriate Index Types](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#use-appropriate-index-types)
- [Tune Search Parameters](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#tune-search-parameters)
- [Data Modeling Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#data-modeling-best-practices)
- [Schema Design](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#schema-design)
- [Use AutoID](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#use-autoid)
- [Appropriate Field Types](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#appropriate-field-types)
- [Index Selection Guidelines](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#index-selection-guidelines)
- [Index Type Selection](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#index-type-selection)
- [Metric Type Selection](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#metric-type-selection)
- [Query Optimization](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#query-optimization)
- [Use Filters](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#use-filters)
- [Limit Result Sets](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#limit-result-sets)
- [Use Iterators for Large Results](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#use-iterators-for-large-results)
- [Memory Management](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#memory-management)
- [Release Collections](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#release-collections)
- [Monitor Memory Usage](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#monitor-memory-usage)
- [Production Deployment Considerations](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#production-deployment-considerations)
- [Environment Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#environment-configuration)
- [Logging Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#logging-configuration)
- [SSL/TLS Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#ssltls-configuration)
- [Health Checks](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#health-checks)
- [Monitoring and Observability](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#monitoring-and-observability)
- [Metrics Collection](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#metrics-collection)
- [Error Tracking](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#error-tracking)
- [Security Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#security-best-practices)
- [Authentication](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#authentication)
- [RBAC](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#rbac)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/#next-steps)

This guide covers best practices for using the Milvus Node.js SDK in production environments.

## Connection Management

### Reuse Client Instances

Create one client instance and reuse it:

```javascript
// Good: Create once, reuse
const client = new MilvusClient({
  address: 'localhost:19530',
});

// Use the same client throughout your application
```

### Proper Cleanup

Close connections when done:

```javascript
// At application shutdown
await client.closeConnection();
```

### Connection Pooling

Configure appropriate pool sizes:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  pool: {
    min: 2,
    max: 10, // Adjust based on your workload
  },
});
```

## Error Handling Strategies

### Comprehensive Error Handling

```javascript
try {
  const { status } = await client.describeCollection({
    collection_name: 'my_collection',
  });
  if (status.error_code === 'CollectionNotExists') {
    console.error('Collection does not exist');
  } else if (status.error_code !== 'Success') {
    console.error(status.reason);
  }
} catch (error) {
  console.error('Transport or SDK error:', error);
}
```

### Retry Logic

Configure automatic retries:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  maxRetries: 3,
  retryDelay: 1000,
});
```

## Performance Optimization

### Batch Operations

Insert data in batches:

```javascript
const batchSize = 1000;
for (let i = 0; i < data.length; i += batchSize) {
  const batch = data.slice(i, i + batchSize);
  await client.insert({
    collection_name: 'my_collection',
    data: batch,
  });
}
```

### Load Collections Before Search

Always load collections before searching:

```javascript
await client.loadCollectionSync({
  collection_name: 'my_collection',
});

// Now search
const results = await client.search({
  collection_name: 'my_collection',
  data: [queryVector],
  limit: 10,
});
```

### Use Appropriate Index Types

Choose indexes based on your use case:

```javascript
// Small dataset: FLAT
// Medium dataset: HNSW
// Large dataset: IVF_PQ
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW', // Choose based on dataset size
  metric_type: 'L2',
});
```

### Tune Search Parameters

Optimize search parameters:

```javascript
// For IVF indexes
const results = await client.search({
  collection_name: 'my_collection',
  data: [/* vector */],
  params: {
    nprobe: 64, // Adjust based on recall/performance needs
  },
  limit: 10,
});
```

## Data Modeling Best Practices

### Schema Design

Design schemas carefully:

```javascript
// Good: Clear field names, appropriate types
const schema = [
  {
    name: 'id',
    data_type: DataType.Int64,
    is_primary_key: true,
    autoID: true,
  },
  {
    name: 'embedding',
    data_type: DataType.FloatVector,
    dim: 128,
  },
  {
    name: 'metadata',
    data_type: DataType.JSON, // Use JSON for flexible data
  },
];
```

### Use AutoID

Let Milvus generate IDs unless you have specific requirements:

```javascript
{
  name: 'id',
  data_type: DataType.Int64,
  is_primary_key: true,
  autoID: true, // Recommended
}
```

### Appropriate Field Types

Choose appropriate data types:

```javascript
// Use Int64 for IDs
// Use FloatVector for embeddings
// Use VarChar for text (with appropriate max_length)
// Use JSON for flexible metadata
```

## Index Selection Guidelines

### Index Type Selection

- **FLAT**: < 1M vectors, exact search
- **HNSW**: 1M - 10M vectors, high recall
- **IVF_FLAT**: Balanced performance
- **IVF_SQ8**: Memory-efficient
- **IVF_PQ**: > 10M vectors, most memory-efficient

### Metric Type Selection

- **L2**: Most common, for embeddings trained with L2
- **IP**: For embeddings trained with inner product
- **COSINE**: For normalized embeddings
- **HAMMING/JACCARD**: For binary vectors

## Query Optimization

### Use Filters

Apply filters to narrow results:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [/* vector */],
  expr: 'category == "tech" AND age > 25', // Filter before search
  limit: 10,
});
```

### Limit Result Sets

Set appropriate limits:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [/* vector */],
  limit: 10, // Don't request more than needed
});
```

### Use Iterators for Large Results

Use iterators for large result sets:

```javascript
const iterator = await client.queryIterator({
  collection_name: 'my_collection',
  expr: 'age > 25',
  batchSize: 100,
});
```

## Memory Management

### Release Collections

Release collections when not in use:

```javascript
await client.releaseCollection({
  collection_name: 'my_collection',
});
```

### Monitor Memory Usage

Check collection loading status:

```javascript
const state = await client.getLoadState({
  collection_name: 'my_collection',
});

console.log('Load state:', state.state);
```

## Production Deployment Considerations

### Environment Configuration

Use environment variables:

```javascript
const client = new MilvusClient({
  address: process.env.MILVUS_ADDRESS,
  username: process.env.MILVUS_USERNAME,
  password: process.env.MILVUS_PASSWORD,
  ssl: process.env.NODE_ENV === 'production',
});
```

### Logging Configuration

Use appropriate log levels:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  logLevel: process.env.NODE_ENV === 'production' ? 'warn' : 'debug',
});
```

### SSL/TLS Configuration

Enable SSL in production:

```javascript
const client = new MilvusClient({
  address: 'milvus.example.com:443',
  ssl: true,
  tls: {
    rootCertPath: '/path/to/ca.pem',
    serverName: 'milvus.example.com',
  },
});
```

### Health Checks

Implement health checks:

```javascript
async function healthCheck() {
  try {
    await client.listCollections();
    return true;
  } catch (error) {
    return false;
  }
}
```

## Monitoring and Observability

### Metrics Collection

Collect and monitor metrics:

```javascript
const metrics = await client.getMetric({
  request: {
    metric_type: 'system_info',
  },
});
```

### Error Tracking

Track errors appropriately:

```javascript
try {
  const { status } = await client.search({
    collection_name: 'my_collection',
    data: [queryVector],
    limit: 10,
  });
  if (status.error_code !== 'Success') throw new Error(status.reason);
} catch (error) {
  // Log to your error tracking service
  errorTracker.captureException(error);
}
```

## Security Best Practices

### Authentication

Always use authentication:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  username: 'root',
  password: 'securepassword',
});
```

### RBAC

Use role-based access control:

```javascript
// Create roles with minimal privileges
await client.createRole({
  roleName: 'readonly',
});

// Grant only necessary privileges
import { RbacObjects } from '@zilliz/milvus2-sdk-node';

await client.grantPrivilege({
  roleName: 'readonly',
  object: RbacObjects.Collection,
  objectName: '*',
  privilegeName: 'DescribeCollection',
});
```

## Next Steps

- Explore [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)
- Check out [Troubleshooting](https://milvus-io.github.io/milvus-sdk-node/reference/troubleshooting/)
- Review [API Reference](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
