---
title: "Storage settings"
summary: "Settings for where telemetry lives, how long it is kept, and how DuckDB is sized."
description: "The data directory, retention, rollups, compaction, and the DuckDB limits."
status: preview
generated: true
read_when:
  - "You are sizing an instance for a host."
  - "Disk use or query latency is growing and you need the maintenance knobs."
---

Every setting below is read once at startup and requires a restart to change.
Built-in defaults are overridden by nonempty environment values.
For the first Pitot alpha, unset `PITOT_` variables accept `FANOUT_` equivalents with a names-only deprecation warning. Explicitly empty primary variables block fallback.
Unknown `PITOT_` names fail startup; platform-injected service names are tolerated.
Vendor credentials and endpoints keep the vendor's documented names.

| Environment variable | Type | Default |
|---|---|---|
| `PITOT_DATA_DIR` | string | `./data` |
| `PITOT_DUCKDB_MAX_CONNECTIONS` | integer | `0` |
| `PITOT_DUCKDB_MEMORY` | string | — |
| `PITOT_DUCKDB_THREADS` | integer | `0` |
| `PITOT_MAINTENANCE_INTERVAL` | duration | `1h` |
| `PITOT_RETENTION_DAYS` | integer | `30` |
| `PITOT_ROLLUP_INTERVAL` | duration | `1m` |
| `PITOT_ROLLUP_SKIP_TO_LATEST` | boolean | `false` |

## Notes

### `PITOT_DATA_DIR`

Stores telemetry, query state, and the control database.

### `PITOT_DUCKDB_MAX_CONNECTIONS`

Caps the DuckDB read connection pool. Reads scan immutable Parquet concurrently; analytical and completed-batch writes use separate gates and connections. Zero selects available Go CPUs, bounded to 2–16. Startup logs and /readyz report the resolved pool size.

### `PITOT_DUCKDB_MEMORY`

Caps DuckDB's memory (e.g. "8GB"). Empty selects 60% of detected available memory, reserving headroom for Go. If detection fails, DuckDB uses its default with a process headroom adjustment. Startup logs and /readyz report the resolved budget and detection status. Set an explicit cap when memory limit detection is incomplete.

### `PITOT_DUCKDB_THREADS`

Caps DuckDB's global query worker pool. Zero selects one worker per CPU the process may run on (the affinity mask and cgroup quota, as GOMAXPROCS resolves them) rather than DuckDB's count of the machine's hardware threads. Set it to leave cores free for ingest on a query-heavy co-tenant host.

### `PITOT_MAINTENANCE_INTERVAL`

Controls Parquet retention and compaction, and query-cache checkpointing.

### `PITOT_RETENTION_DAYS`

Sets telemetry retention in days; zero disables expiry.

### `PITOT_ROLLUP_INTERVAL`

Schedules analytical rollups; use a Go duration of at least 1s.

### `PITOT_ROLLUP_SKIP_TO_LATEST`

Set once at boot, this advances the service and edge rollup watermarks to the current max ingested timestamp. Existing history is not aggregated into those analytical rollups. Completed-batch trace caches still rebuild all retained history in bounded passes; uncached files remain immediately queryable. Useful for large pre-seeded datasets (benchmarks, restores); off in normal operation.