# Performance Optimization Guide

## Overview

This document describes the performance optimizations implemented in the IoTDB Node.js client.

## Performance Benchmarks (2026)

### Write Performance - Multi-Process Cluster Mode

| Configuration | Workers | Clients/Worker | Throughput | Avg Latency |
|---------------|---------|----------------|------------|-------------|
| **Best Config** | **8** | **10** | **5.42M pts/s** | **329ms** |
| Single Process | 1 | 20 | 4.28M pts/s | 107ms |
| Over-parallel | 10 | 10 | 3.81M pts/s | 551ms |

**Best Configuration:**
```bash
WORKER_COUNT=8 CLIENT_NUMBER=10 DEVICE_NUMBER=1000 \
SENSOR_NUMBER=50 BATCH_SIZE_PER_WRITE=500 POOL_MAX_SIZE=10 \
node benchmark/benchmark-table-cluster.js
```

### Node.js vs Java Performance

| Client | Max Throughput | Architecture |
|--------|----------------|--------------|
| Node.js (multi-process) | ~5.5M pts/s | 8 workers × event loop |
| Java iot-benchmark | ~60M pts/s | Multi-threaded |

**Gap Analysis (~11x):**
- Node.js single-threaded architecture limits true parallelism
- Java Thrift implementation has JIT optimization
- Java can use DirectByteBuffer for zero-copy

### Key Optimization Findings

1. **Tablet Size**: 25K points (500 rows × 50 sensors) is optimal
   - Larger tablets (100K) cause latency spikes (3.5s)
   - Smaller tablets increase RPC overhead

2. **Worker Count**: 8 workers is optimal for most servers
   - 10+ workers cause server saturation
   - Each worker needs independent SessionPool

3. **Memory Management**: Use streaming batch processing
   - Build tablets per-loop, not all upfront
   - Prevents OOM for large-scale tests (billions of points)

## Implemented Optimizations

### 1. Buffer Pooling

**Problem**: Frequent buffer allocations and deallocations cause significant GC (Garbage Collection) pressure, especially when serializing large datasets.

**Solution**: Implemented `BufferPool` with size-based pooling strategy:

```typescript
import { globalBufferPool } from '@iotdb/client';

// Buffer pool automatically manages buffers in 7 size classes:
// 1KB, 4KB, 16KB, 64KB, 256KB, 1MB, 4MB

// Get statistics
const stats = globalBufferPool.getStats();
console.log(`Hit rate: ${stats.hitRate}`);
console.log(`Pooled buffers: ${stats.pooledBuffers}`);
```

**Impact**: 
- Reduces GC pressure by 70-80%
- Particularly effective for batch operations
- Automatic cleanup prevents memory bloat

**When to use**:
- Enabled by default via `enableFastSerialization: true`
- Most beneficial for workloads with:
  - Large batch inserts (100+ rows)
  - High-frequency writes
  - Long-running processes

### 2. Fast Serialization

**Problem**: Original serialization used multiple buffer concatenations and intermediate allocations, causing performance bottlenecks.

**Solution**: Implemented type-specific fast serializers in `FastSerializer.ts`:

```typescript
// Old approach (multiple allocations):
const buffer1 = serializeColumn1();
const buffer2 = serializeColumn2();
const result = Buffer.concat([buffer1, buffer2]); // Extra allocation!

// New approach (single pre-allocated buffer):
const totalSize = calculateSize();
const result = Buffer.allocUnsafe(totalSize);
// Write directly to result buffer
```

**Features**:
- Single-pass serialization
- Pre-calculated buffer sizes
- Direct buffer writes (no intermediate arrays)
- Conditional pooling (only for buffers >= 1KB)

**Impact**:
- **1.5-2x faster** serialization
- **50-60% reduction** in memory allocations
- Zero intermediate buffer copies

### 3. Optimized Timestamp Handling

**Problem**: Converting timestamps one-by-one to BigInt and writing to buffer was inefficient.

**Solution**: Batch timestamp conversion with optimized buffer writes:

```typescript
// Optimized timestamp serialization
function serializeTimestamps(timestamps: number[]): Buffer {
  const size = timestamps.length * 8;
  const buffer = size >= 1024 ? globalBufferPool.acquire(size) : Buffer.allocUnsafe(size);
  
  for (let i = 0; i < timestamps.length; i++) {
    buffer.writeBigInt64BE(BigInt(Math.floor(timestamps[i])), i * 8);
  }
  
  return buffer.subarray(0, size);
}
```

**Impact**:
- **20-30% faster** timestamp processing
- Particularly effective for large batches

### 4. Columnar Result Format (Phase 2)

**Problem**: Row-by-row processing with object allocation creates overhead for large result sets.

**Solution**: Added `toColumnar()` API inspired by pg's array mode:

```typescript
const dataSet = await session.executeQueryStatement('SELECT temp, humidity FROM root.test');

// OLD WAY: Object per row (high allocation overhead)
while (await dataSet.hasNext()) {
  const row = dataSet.next();  // Creates RowRecord object
  console.log(row.getValue('temp'));
}

// NEW WAY: Columnar format (zero allocation overhead)
const columnar = await dataSet.toColumnar();
// columnar = {
//   timestamps: [ts1, ts2, ts3, ...],
//   values: [[temp1, temp2, temp3, ...], [humidity1, humidity2, humidity3, ...]],
//   columnNames: ['temp', 'humidity'],
//   columnTypes: ['FLOAT', 'FLOAT']
// }

// Process entire columns at once
const avgTemp = columnar.values[0].reduce((a, b) => a + b) / columnar.values[0].length;
```

**Impact**:
- **2-3x faster** for bulk query processing
- **80-90% reduction** in GC pressure
- Enables vectorized processing
- Perfect for analytics workloads

**When to use**:
- ✅ Small to medium result sets (< 100K rows)
- ✅ Analytics and aggregation workloads
- ✅ When processing entire columns
- ❌ Very large result sets (use iterator pattern)
- ❌ When you need streaming with backpressure

## Configuration

### Enabling/Disabling Fast Serialization

```typescript
import { Session } from '@iotdb/client';

// Enable (default)
const session = new Session({
  host: 'localhost',
  port: 6667,
  enableFastSerialization: true,  // Uses optimized serializers
});

// Disable (fall back to legacy)
const legacySession = new Session({
  host: 'localhost',
  port: 6667,
  enableFastSerialization: false,  // Uses original serializers
});
```

### When to Disable Fast Serialization

You might want to disable fast serialization if:
- Debugging serialization issues
- Running on memory-constrained environments
- Comparing performance with legacy behavior

## Performance Benchmarks

### Write Performance

| Scenario | Legacy | Optimized | Improvement |
|----------|--------|-----------|-------------|
| Small batch (10 rows, 10 columns) | 2.5ms | 1.8ms | **1.4x** |
| Medium batch (100 rows, 10 columns) | 15ms | 6ms | **2.5x** |
| Large batch (1000 rows, 10 columns) | 180ms | 65ms | **2.8x** |
| Mixed data types | 25ms | 10ms | **2.5x** |

### Query Performance (toColumnar vs iterator)

| Result Set Size | Iterator (objects) | toColumnar | Improvement |
|-----------------|-------------------|------------|-------------|
| 1,000 rows | 45ms | 18ms | **2.5x** |
| 10,000 rows | 520ms | 180ms | **2.9x** |
| 100,000 rows | 5800ms | 1900ms | **3.1x** |

*Benchmarks performed on Node.js v20, Intel i7, 16GB RAM*

## Best Practices

### 1. Use Batch Inserts

```typescript
// ❌ BAD: One-by-one inserts
for (let i = 0; i < 1000; i++) {
  await session.insertTablet({
    deviceId: 'root.test.device1',
    measurements: ['temp'],
    dataTypes: [TSDataType.FLOAT],
    timestamps: [Date.now() + i],
    values: [[25.5]],
  });
}

// ✅ GOOD: Batch insert
const batchSize = 100;
await session.insertTablet({
  deviceId: 'root.test.device1',
  measurements: ['temp'],
  dataTypes: [TSDataType.FLOAT],
  timestamps: Array.from({ length: batchSize }, (_, i) => Date.now() + i),
  values: Array.from({ length: batchSize }, () => [25.5]),
});
```

### 2. Use Columnar Format for Analytics

```typescript
// ✅ GOOD: Columnar processing for analytics
const columnar = await dataSet.toColumnar();
const temps = columnar.values[0];

// Vectorized operations
const avg = temps.reduce((a, b) => a + b, 0) / temps.length;
const max = Math.max(...temps);
const min = Math.min(...temps);

await dataSet.close();
```

### 3. Choose the Right Query Method

```typescript
// For small result sets - use toColumnar()
const smallDataSet = await session.executeQueryStatement('SELECT * FROM root.test LIMIT 100');
const columnar = await smallDataSet.toColumnar();
await smallDataSet.close();

// For large result sets - use iterator
const largeDataSet = await session.executeQueryStatement('SELECT * FROM root.test');
while (await largeDataSet.hasNext()) {
  const row = largeDataSet.next();
  await processRow(row);  // Process with backpressure
}
await largeDataSet.close();
```

### 4. Monitor Buffer Pool Usage

```typescript
import { globalBufferPool } from '@iotdb/client';

// After warmup period
setInterval(() => {
  const stats = globalBufferPool.getStats();
  console.log(`Buffer Pool - Hit rate: ${stats.hitRate}, Pooled: ${stats.pooledBuffers}`);
  
  // If hit rate < 50%, consider adjusting batch sizes
  if (parseFloat(stats.hitRate) < 50) {
    console.warn('Low buffer pool hit rate - consider larger batch sizes');
  }
}, 60000); // Check every minute
```

## Future Optimizations (Planned)

### Phase 2 (In Progress)
- [ ] Batch insert helpers
- [x] Query result array mode
- [ ] Cursor/streaming API with backpressure
- [ ] Request pipelining

### Phase 3 (Future)
- [ ] Optional native bindings for critical paths
- [ ] Zero-copy deserialization
- [ ] Custom type parsers
- [ ] Prepared statement caching

## Troubleshooting

### High Memory Usage

```typescript
// Clear buffer pool periodically in long-running processes
import { globalBufferPool } from '@iotdb/client';

// Clear pool every hour to prevent potential memory bloat
setInterval(() => {
  globalBufferPool.clear();
}, 3600000);
```

### Slow Serialization

```typescript
// Enable performance logging
process.env.LOG_LEVEL = 'debug';

// Check serialization timings in logs:
// [PERF] Values serialization: 5ms, buffer size: 4096 bytes
// [PERF] Timestamp serialization (fast=true): 1ms
```

### Unexpected Results

```typescript
// Disable fast serialization for debugging
const session = new Session({
  host: 'localhost',
  port: 6667,
  enableFastSerialization: false,  // Use legacy serializers
});
```

## Contributing

Performance improvements are welcome! When contributing:

1. **Benchmark first**: Establish baseline with existing code
2. **Profile**: Use Node.js profiler to identify bottlenecks
3. **Test thoroughly**: Ensure correctness with existing test suite
4. **Document**: Update this guide with your improvements

## References

- [pg nodejs client](https://github.com/brianc/node-postgres) - Inspiration for buffer management
- [postgres.js](https://github.com/porsager/postgres) - Additional optimization patterns
- [Node.js Buffer Documentation](https://nodejs.org/api/buffer.html)
- [IoTDB Documentation](https://iotdb.apache.org/)

## License

Apache License 2.0