# Connection Pooling, Retries, and Tracing

Configure connection pools, retries, error handling, logging, request tracing, and iterators in the Milvus Node.js SDK.

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/advanced-features/

## Section links

- [Connection Pooling](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#connection-pooling)
- [Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#configuration)
- [Benefits](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#benefits)
- [Retry Mechanisms](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#retry-mechanisms)
- [Configuration](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#configuration-1)
- [Retry Behavior](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#retry-behavior)
- [Error Handling](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#error-handling)
- [Error Types](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#error-types)
- [Common Error Codes](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#common-error-codes)
- [Error Response Structure](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#error-response-structure)
- [Logging and Debugging](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#logging-and-debugging)
- [Log Levels](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#log-levels)
- [Log Levels](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#log-levels-1)
- [Debugging](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#debugging)
- [Request Tracing (TraceID)](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#request-tracing-traceid)
- [Overview](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#overview)
- [Automatic Timestamp](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#automatic-timestamp)
- [Using TraceID](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#using-traceid)
- [Supported Operations](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#supported-operations)
- [Use Cases](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#use-cases)
- [Implementation Details](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#implementation-details)
- [Iterator Patterns](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#iterator-patterns)
- [Query Iterator](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#query-iterator)
- [Search Iterator](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#search-iterator)
- [Sparse Vectors](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#sparse-vectors)
- [Binary Vectors](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#binary-vectors)
- [Float16/BFloat16 Vectors](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#float16bfloat16-vectors)
- [Dynamic Fields](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#dynamic-fields)
- [Performance Monitoring](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#performance-monitoring)
- [Get Metrics](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#get-metrics)
- [Replica Management](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#replica-management)
- [Get Replicas](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#get-replicas)
- [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#best-practices)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/advanced/advanced-features/#next-steps)

This guide covers advanced features including connection pooling, retry mechanisms, error handling, logging, and iterator patterns.

## Connection Pooling

The SDK uses connection pooling to manage gRPC connections efficiently.

### Configuration

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  pool: {
    min: 2, // Minimum pool size
    max: 10, // Maximum pool size
    idleTimeoutMillis: 30000, // Idle timeout
  },
});
```

### Benefits

- **Efficiency**: Reuses connections instead of creating new ones
- **Performance**: Reduces connection overhead
- **Resource management**: Limits concurrent connections

## Retry Mechanisms

Configure automatic retries for failed operations.

### Configuration

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  maxRetries: 3, // Maximum retry attempts
  retryDelay: 1000, // Delay between retries (ms)
});
```

### Retry Behavior

The SDK automatically retries on:

- Network errors
- Transient server errors
- Timeout errors

## Error Handling

### Error Types

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

try {
  const { status } = await client.describeCollection({
    collection_name: 'my_collection',
  });
  if (status.error_code !== ErrorCode.SUCCESS) {
    console.error(status.error_code, status.reason);
  }
} catch (error) {
  console.error('Transport or SDK error:', error);
}
```

### Common Error Codes

- `Success`: Operation succeeded
- `CollectionNotExists`: Collection not found
- `IllegalArgument`: Invalid parameter
- `IndexNotExist`: Index not found
- `UnexpectedError`: Unexpected server error
- `RateLimit`: Rate limit exceeded
- `SchemaMismatch`: Schema mismatch

### Error Response Structure

```javascript
{
  error_code: 'CollectionNotExists',
  reason: 'Collection my_collection does not exist',
  // ... other fields
}
```

## Logging and Debugging

### Log Levels

Configure logging levels:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  logLevel: 'debug', // 'error', 'warn', 'info', 'debug'
  logPrefix: 'milvus-client',
});
```

### Log Levels

- **error**: Only error messages
- **warn**: Warnings and errors
- **info**: Informational messages, warnings, and errors
- **debug**: All messages including debug information

### Debugging

Enable trace for detailed debugging:

```javascript
const client = new MilvusClient({
  address: 'localhost:19530',
  trace: true,
});
```

## Request Tracing (TraceID)

Track and trace individual requests using trace IDs for debugging and monitoring purposes.

### Overview

The SDK automatically adds a timestamp (`client-request-unixmsec`) to every request. You can optionally provide a `client_request_id` (or `client-request-id`) to track specific requests across your application.

### Automatic Timestamp

Every request automatically includes a `client-request-unixmsec` timestamp:

```javascript
// This request will have client-request-unixmsec automatically added
await client.listCollections({
  // Timestamp is added automatically, no configuration needed
});
```

### Using TraceID

Add a trace ID to track specific requests:

```javascript
// Recommended: use client_request_id (JavaScript/TypeScript convention)
const traceId = `trace-${Date.now()}`;
await client.listCollections({
  client_request_id: traceId,
});

// Alternative: use client-request-id (compatible with pymilvus)
await client.listCollections({
  'client-request-id': traceId,
});
```

**Note**: If both formats are provided, `client_request_id` takes priority (JavaScript/TypeScript convention).

### Supported Operations

All API methods that extend `GrpcTimeOut` support trace IDs:

```javascript
// Insert with trace ID
await client.insert({
  collection_name: 'my_collection',
  data: [{ id: 1, vector: [0.1, 0.2, 0.3] }],
  client_request_id: 'insert-trace-123',
});

// Search with trace ID
await client.search({
  collection_name: 'my_collection',
  vector: [0.1, 0.2, 0.3],
  limit: 10,
  client_request_id: 'search-trace-456',
});

// Query with trace ID
await client.query({
  collection_name: 'my_collection',
  expr: 'id > 100',
  client_request_id: 'query-trace-789',
});

// All other operations support trace IDs
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'IVF_FLAT',
  client_request_id: 'index-trace-101',
});
```

### Use Cases

1. **Request Tracking**: Track requests across distributed systems
2. **Debugging**: Identify specific requests in logs
3. **Performance Monitoring**: Correlate trace IDs with performance metrics
4. **Error Investigation**: Trace errors back to specific requests

### Implementation Details

- Trace IDs are passed through gRPC metadata
- Both `client_request_id` and `client-request-id` formats are supported
- Trace IDs are automatically extracted from request parameters
- The timestamp `client-request-unixmsec` is automatically added by the interceptor
- No need to modify API method implementations

## Iterator Patterns

### Query Iterator

Iterate through large query results:

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

while (true) {
  const batch = await iterator.next();
  if (batch.done) break;

  console.log('Batch:', batch.value);
}
```

### Search Iterator

Iterate through large search results:

```javascript
const iterator = await client.searchIterator({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  limit: 10000,
  batchSize: 100,
});

while (true) {
  const batch = await iterator.next();
  if (batch.done) break;

  console.log('Batch:', batch.value);
}
```

## Sparse Vectors

Work with sparse vector data:

```javascript
// Array format
const sparseVector = [1.0, undefined, undefined, 2.5, undefined];

// Dictionary format
const sparseVector = { 0: 1.0, 3: 2.5 };

// CSR format
const sparseVector = {
  indices: [0, 3],
  values: [1.0, 2.5],
};

// COO format
const sparseVector = [
  { index: 0, value: 1.0 },
  { index: 3, value: 2.5 },
];

await client.insert({
  collection_name: 'my_collection',
  data: [
    {
      sparse_vector: sparseVector,
    },
  ],
});
```

## Binary Vectors

Work with binary vector data:

```javascript
// Binary vector: length must be dim / 8
const binaryVector = [1, 0, 1, 0, 1, 0, 1, 0]; // For dim=64

await client.insert({
  collection_name: 'my_collection',
  data: [
    {
      binary_vector: binaryVector,
    },
  ],
});
```

## Float16/BFloat16 Vectors

Use transformers for Float16 and BFloat16 vectors:

```javascript
import { DataType, f32ArrayToF16Bytes } from '@zilliz/milvus2-sdk-node';

await client.insert({
  collection_name: 'my_collection',
  data: [
    {
      vector: [0.1, 0.2, 0.3, 0.4], // f32 array
    },
  ],
  transformers: {
    [DataType.Float16Vector]: f32ArrayToF16Bytes,
  },
});
```

## Dynamic Fields

Enable dynamic fields for flexible schemas:

```javascript
// Create collection with dynamic fields
await client.createCollection({
  collection_name: 'my_collection',
  fields: [
    {
      name: 'id',
      data_type: DataType.Int64,
      is_primary_key: true,
      autoID: true,
    },
    {
      name: 'vector',
      data_type: DataType.FloatVector,
      dim: 128,
    },
  ],
  enable_dynamic_field: true,
});

// Insert data with dynamic fields
await client.insert({
  collection_name: 'my_collection',
  data: [
    {
      vector: [
        /* ... */
      ],
      dynamic_field_1: 'value1', // Automatically added
      dynamic_field_2: 123, // Automatically added
    },
  ],
});
```

## Performance Monitoring

### Get Metrics

Get system metrics:

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

console.log('Metrics:', metrics);
```

## Replica Management

### Get Replicas

Get replica information:

```javascript
const { collectionID } = await client.describeCollection({
  collection_name: 'my_collection',
});
const replicas = await client.getReplicas({ collectionID });

console.log('Replicas:', replicas.replicas);
```

## Best Practices

1. **Connection pooling**: Configure appropriate pool sizes
2. **Retry configuration**: Set reasonable retry limits
3. **Error handling**: Always handle errors appropriately
4. **Logging**: Use appropriate log levels for your environment
5. **Iterators**: Use iterators for large result sets
6. **Monitoring**: Monitor metrics for performance optimization

## Next Steps

- Learn about [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)
- Explore [HTTP Client](https://milvus-io.github.io/milvus-sdk-node/advanced/http-client/)
- Check out [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)
