Caching

This guide covers caching configuration and optimization for Deephaven clusters, focusing on the Table Data Cache Proxy (TDCP) and related caching mechanisms.

Overview

Deephaven uses multiple caching layers to optimize data access:

Table Data Cache Proxy (TDCP)

The TDCP is the primary caching layer for intraday data, sitting between workers and Data Import Servers.

When TDCP benefits performance

TDCP provides the most benefit when:

• Multiple workers access the same data: Shared cache serves all workers from one DIS fetch.
• Repeated queries on the same tables: Subsequent requests served from cache.
• High worker-to-DIS ratio: Reduces connection load on DIS instances.
• Network-constrained environments: Reduces cross-network data transfer.

TDCP architecture

Key characteristics:

• Runs on every query node as db_tdcp.
• Workers connect to local TDCP only (low latency).
• TDCP maintains connections to DIS instances (local or remote).
• Caches data blocks in JVM heap.

TDCP sizing

A typical starting point is 4 GB heap. Larger deployments may require 8-16 GB or more, depending on:

• Number of concurrent workers accessing data.
• Volume of column data being cached (TDCP caches at column/chunk granularity, not whole tables).
• Average query complexity and data access patterns.

TDCP heap size is configured via hostconfig or startup scripts. See TDCP resource sizing for detailed sizing guidance.

TDCP configuration

TDCP routing is configured via the data routing YAML. See Data routing overview.

Key properties:

Monitoring TDCP

Check status:

Log location: /var/log/deephaven/tdcp/ — primary log is TableDataCacheProxy.log.current.

Key metrics to monitor:

• Heap usage and GC activity
• Active connections (workers and DIS)
• Cache hit/miss patterns in logs

Local Table Data Service (LTDS)

The LTDS is an optional process that exposes local intraday data over the Table Data Protocol (TDP). It is not started by default in current deployments.

When to use LTDS

LTDS is beneficial for:

• Serving static local intraday data not managed by DIS (e.g., "yesterday" data that is no longer being appended).
• Reducing load on DIS by offloading read traffic.
• Publishing local test data to other Deephaven processes.
• Legacy deployments that already use LTDS.

LTDS vs. TDCP

LTDS configuration

LTDS is configured in the data routing YAML under tableDataServices.

See LTDS configuration for details.

OS page cache

The operating system's page cache provides filesystem-level caching for historical data reads.

Optimizing page cache

For historical queries:

• Ensure adequate free RAM for page cache (beyond application heap).
• Monitor page cache hit rates with vmstat or sar.
• Consider dedicated storage for hot partitions.

RAM allocation guideline:

As a general guideline, leave at least 10-20% of RAM available for page cache on query nodes. Actual requirements depend on your historical query patterns.

Table location caching

Workers cache table location metadata to avoid repeated lookups. This can cause issues when partitions are replaced.

Disable caching globally:

Clear cache programmatically:

See Table location caching FAQ for more details.

Quick reference

Cache sizing summary

Common caching issues

Cache tuning checklist

1. ✅ TDCP heap sized for workload
2. ✅ Adequate RAM for OS page cache
3. ✅ Table location cache behavior understood
4. ✅ Cache metrics monitored

Related documentation

• Table Data Cache Proxy
• Local Table Data Service
• Data routing overview
• Memory management
• Table location caching FAQ
• Performance tuning overview