---
title: Caching
---

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

> [!NOTE]
> For understanding how caching affects query performance, see [Monitor queries](../../performance/monitor-queries.md).

## Overview

Deephaven uses multiple caching layers to optimize data access:

| Cache layer          | Location  | Purpose                        | Data type          |
| -------------------- | --------- | ------------------------------ | ------------------ |
| TDCP                 | Each node | Block-level table data caching | Intraday (ticking) |
| OS page cache        | Each node | Filesystem read caching        | Historical         |
| Table location cache | Workers   | Table metadata caching         | All                |
| Data buffer pool     | Workers   | In-memory column data          | Active table data  |

## Table Data Cache Proxy (TDCP)

The [TDCP](../core-components/table-data-cache-proxy.md) 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

```
Workers (many) → TDCP (one per node) → DIS instances (few)
```

**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](../core-components/table-data-cache-proxy.md#resource-sizing) for detailed sizing guidance.

> [!NOTE]
> These sizing recommendations are starting points. Actual requirements vary based on workload characteristics, data volume, and access patterns. Monitor TDCP performance and adjust based on observed behavior.

> [!NOTE]
> TDCP runs as a separate process on each query node. Checking TDCP health on one host (e.g., `infra-host`) does not indicate the status of TDCP on other hosts (e.g., `query-host`). Monitor each node's TDCP independently.

### TDCP configuration

TDCP routing is configured via the data routing YAML. See [Data routing overview](../configuration/data-routing-overview.md).

**Key properties:**

| Property                                       | Purpose                     | Default                  |
| ---------------------------------------------- | --------------------------- | ------------------------ |
| `TableDataCacheProxy.routingConfigurationName` | Which routing config to use | Process name (`db_tdcp`) |

### Monitoring TDCP

**Check status:**

```bash
dh_monit status db_tdcp
```

**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](../core-components/local-table-data-service.md) 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

| Aspect      | TDCP            | LTDS                       |
| ----------- | --------------- | -------------------------- |
| Default     | Yes             | No                         |
| Purpose     | Caching proxy   | Local data server          |
| Data source | DIS instances   | Local intraday directories |
| Typical use | All deployments | Specialized scenarios      |

### LTDS configuration

LTDS is configured in the data routing YAML under `tableDataServices`.

See [LTDS configuration](../configuration/yaml.md#table-data-services) 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:**

```
Available for page cache = Total RAM - (Worker heaps + TDCP heap + OS overhead)
```

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:**

```properties
-DDatabase.useLocationCaches=false
```

**Clear cache programmatically:**

```python
db.j_db.clearLocationCache()
db.j_db.clearLocationCache("Namespace", "TableName")
```

```groovy
db.clearLocationCache()
db.clearLocationCache("Namespace", "TableName")
```

See [Table location caching FAQ](../../resources/faq/table-caching.md) for more details.

## Quick reference

### Cache sizing summary

| Cache         | Sizing basis                           | Notes                                                                                             |
| ------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| TDCP heap     | Workers, table count, query complexity | System-dependent; see [TDCP sizing](../core-components/table-data-cache-proxy.md#resource-sizing) |
| OS page cache | Historical query frequency             | RAM not used by applications                                                                      |
| Worker heap   | Query complexity                       | See [Memory management](./memory-management.md)                                                   |

### Common caching issues

| Symptom               | Likely cause               | Solution                       |
| --------------------- | -------------------------- | ------------------------------ |
| Slow repeated queries | TDCP heap too small        | Increase TDCP heap             |
| Stale data in queries | Location cache not cleared | Clear cache or disable         |
| High DIS load         | Missing TDCP               | Deploy TDCP on all query nodes |
| Memory pressure       | Over-allocated heaps       | Balance heap vs. page cache    |

### 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](../core-components/table-data-cache-proxy.md)
- [Local Table Data Service](../core-components/local-table-data-service.md)
- [Data routing overview](../configuration/data-routing-overview.md)
- [Memory management](./memory-management.md)
- [Table location caching FAQ](../../resources/faq/table-caching.md)
- [Performance tuning overview](./overview.md)