Performance Benchmarks

This document provides comprehensive performance benchmarks for ParqueDB operations across different scales and environments.

Table of Contents

• Overview
• Running Benchmarks
• CRUD Operations
• Query Performance
• Scalability
• Index Performance
• Cloudflare Workers Performance
• Storage Comparisons
• Performance Targets

Overview

ParqueDB is designed for efficient read-heavy workloads with the following performance characteristics:

• Sub-millisecond reads for indexed lookups in Cloudflare Workers
• Columnar storage enables reading only necessary columns
• Row-group statistics enable predicate pushdown
• Secondary indexes (Hash, SST, FTS) for accelerated queries
• Variant shredding reduces I/O by 2-10x for common queries

Test Environment

• Node.js: v20.x or later
• Cloudflare Workers: workerd runtime via vitest-pool-workers
• Datasets: Synthetic + real-world (IMDB, O*NET, UNSPSC)

Running Benchmarks

Quick Start

# Run all benchmarks
npm run bench

# Run specific benchmark suites
npm run bench:crud        # CRUD operations
npm run bench:queries     # Query patterns
npm run bench:parquet     # Parquet I/O
npm run bench:relationships  # Graph traversal
npm run bench:examples    # Real-world examples

# Run the unified benchmark script
npm run benchmark         # Comprehensive benchmark report

E2E Benchmarks (Deployed Worker)

# Test against deployed worker
node scripts/e2e-benchmark.mjs --url=https://parquedb.workers.do

# Local development
node scripts/e2e-benchmark.mjs --url=http://localhost:8787 --verbose

CRUD Operations

Single Operations

Batch Operations

Update Operators

Query Performance

Filter Operations

Indexed Queries

With secondary indexes, query performance improves significantly:

Sort Performance

Pagination

Recommendation: Use cursor-based pagination for deep pagination.

Scalability

Scale Tests

Performance across different dataset sizes:

Memory Usage

Tip: Use projections to reduce memory usage for large result sets.

Index Performance

Secondary Index Types

ParqueDB supports three types of secondary indexes:

1. Hash Index: O(1) equality lookups
2. SST Index: Range queries with sorted structure
3. FTS Index: Full-text search with TF-IDF scoring

Index Build Time

Index Lookup Performance

Full-Text Search

Cloudflare Workers Performance

R2 Storage Operations

Durable Objects

End-to-End Operations

Key Observations

1. R2 local operations are extremely fast (<1ms for most ops)
2. DO cold start adds ~3ms overhead vs warm operations (~1ms)
3. Batched operations (Promise.all) are ~2x faster than sequential
4. Payload size has minimal impact on DO create latency

Storage Comparisons

Parquet vs JSON

Storage Savings: Parquet provides 8-10x compression vs raw JSON.

Variant Shredding Benefits

The V3 "dual variant" architecture shreds hot fields for efficient column projection:

Compression Comparison

Recommendation: Use Snappy for best balance of speed and compression.

Performance Targets

ParqueDB targets the following SLAs:

Benchmark Architecture

Test Files

tests/benchmarks/
  crud.bench.ts         # CRUD operations
  queries.bench.ts      # Query patterns
  scalability.bench.ts  # Scale tests (100-100K)
  parquet.bench.ts      # Parquet I/O
  relationships.bench.ts # Graph traversal
  setup.ts              # Utilities

scripts/
  benchmark.mjs         # Unified benchmark runner
  benchmark-indexes.mjs # Index benchmarks
  benchmark-v3.mjs      # V3 architecture tests
  e2e-benchmark.mjs     # Deployed worker tests

Datasets Used

1. Synthetic: Generated entities with varied field types
2. IMDB: 100K titles, 50K people, 200K cast relationships
3. O*NET: 1,000 occupations, skills, and relationships
4. UNSPSC: Product classification hierarchy

Running Custom Benchmarks

import { benchmark, calculateStats, formatStats } from './tests/benchmarks/setup'

const stats = await benchmark('my operation', async () => {
  // Your code here
}, { iterations: 100, warmupIterations: 10 })

console.log(formatStats(stats))

Continuous Benchmarking

Benchmarks run automatically on:

• Every push to main branch
• Manual workflow dispatch

Results are stored as GitHub artifacts and tracked over time via github-action-benchmark.

Viewing Results

1. Go to Actions > Benchmark workflow
2. Download the benchmark-results artifact
3. Or view trends on the gh-pages branch at /dev/bench

Contributing

When adding new benchmarks:

1. Add test file to tests/benchmarks/
2. Follow naming convention: *.bench.ts
3. Use provided utilities from setup.ts
4. Document expected performance in this file
5. Add to CI workflow if needed

Last updated: February 2026