diff --git a/website/docs/components/data-accelerators/duckdb/deployment.md b/website/docs/components/data-accelerators/duckdb/deployment.md index 61a890e42..78bbeb31a 100644 --- a/website/docs/components/data-accelerators/duckdb/deployment.md +++ b/website/docs/components/data-accelerators/duckdb/deployment.md @@ -61,7 +61,7 @@ For any dataset of **10 GB or larger**, deploy [Spice Cayenne](../cayenne/index. ::: -DuckDB self-tunes its memory limit from **host** memory, not the cgroup limit, so in a container each instance's own default over-states what the process may use. When `duckdb_memory_limit` is unset, Spice caps each un-limited DuckDB instance from a cgroup-aware [coordinated memory budget](./index.md#coordinated-memory-budget) shared with the query pool, and warns when it does so. +DuckDB self-tunes its memory limit from **host** memory, not the cgroup limit, so under any cgroup memory cap — a container, a `systemd` unit's `MemoryMax=`, a capped parent slice, or a Kubernetes pod cgroup — each instance's own default over-states what the process may use. When `duckdb_memory_limit` is unset, Spice caps each un-limited DuckDB instance from a cgroup-aware [coordinated memory budget](./index.md#coordinated-memory-budget) shared with the query pool, and warns when it does so. Set the `duckdb_memory_limit` acceleration parameter to replace that automatic split with a deliberate ceiling. Plan for the DuckDB working set plus ~2× for query execution headroom. diff --git a/website/docs/components/data-accelerators/duckdb/index.md b/website/docs/components/data-accelerators/duckdb/index.md index bab844686..67360dd49 100644 --- a/website/docs/components/data-accelerators/duckdb/index.md +++ b/website/docs/components/data-accelerators/duckdb/index.md @@ -158,7 +158,7 @@ Allocate at least 30% more container/machine memory for the runtime process. Because those per-instance ceilings do not know about each other, a Spicepod with several DuckDB files declares several independent 80%-of-RAM ceilings, stacked on top of the [`runtime.query.memory_limit`](../../reference/spicepod/runtime#runtimequerymemory_limit) pool (90% of RAM by default, 70% when Cayenne acceleration is also active) — an over-commit that risks an OOM kill under load. -At startup, and again on hot-reload, Spice computes a coordinated budget so the **sum** of those ceilings fits within the memory the process can actually use (the cgroup limit in a container). It is always on and has no configuration parameter: +At startup, and again on hot-reload, Spice computes a coordinated budget so the **sum** of those ceilings fits within the memory the process can actually use — its cgroup memory limit when one binds, otherwise host RAM. The limit is read from the process's own cgroup path, taking the smallest limit at any level, so a container limit, a `systemd` unit's `MemoryMax=`, a capped parent slice, and a Kubernetes pod cgroup are all honored. Coordination is always on and has no configuration parameter: - Each distinct DuckDB instance with **no** `duckdb_memory_limit` is capped at an equal share of what the query pool and any explicit ceilings leave, with a floor of 128 MiB per instance. - The query pool is reduced by the same amount, taking roughly half of the contested region and never dropping below a quarter of its uncoordinated default (or 256 MiB when every instance has an explicit ceiling). diff --git a/website/docs/reference/memory.md b/website/docs/reference/memory.md index 513e4aa8e..9a40d481b 100644 --- a/website/docs/reference/memory.md +++ b/website/docs/reference/memory.md @@ -147,11 +147,11 @@ Refresh modes affect memory usage as follows: ## DataFusion Query Memory Management -Spice uses DataFusion as its query execution engine. By default, Spice limits query engine memory to **90% of total system memory** (container-aware; reduced to **70%** when Cayenne acceleration is active, to leave headroom for Cayenne's compaction memory pool and in-memory CDC tier). This can be tuned through the `runtime.query.memory_limit` configuration. +Spice uses DataFusion as its query execution engine. By default, Spice limits query engine memory to **90% of the memory the process may use** (its cgroup memory limit when one binds — a container, a `systemd` unit's `MemoryMax=`, a capped parent slice, or a Kubernetes pod cgroup — otherwise total system memory; reduced to **70%** when Cayenne acceleration is active, to leave headroom for Cayenne's compaction memory pool and in-memory CDC tier). This can be tuned through the `runtime.query.memory_limit` configuration. ### Memory Limit Configuration -The `runtime.query.memory_limit` parameter defines the maximum memory available for query execution. If not specified, it defaults to 90% of total system memory (70% when Cayenne acceleration is active). Once the memory limit is reached, supported query operations spill data to disk. +The `runtime.query.memory_limit` parameter defines the maximum memory available for query execution. If not specified, it defaults to 90% of the memory the process may use — its cgroup memory limit when one binds, otherwise total system memory (70% when Cayenne acceleration is active). Once the memory limit is reached, supported query operations spill data to disk. ```yaml runtime: diff --git a/website/docs/reference/performance-tuning.md b/website/docs/reference/performance-tuning.md index 1a3d54fbf..d52f4e704 100644 --- a/website/docs/reference/performance-tuning.md +++ b/website/docs/reference/performance-tuning.md @@ -389,7 +389,7 @@ runtime: ### Memory Limit -If not specified, `memory_limit` defaults to 90% of total system memory (container-aware); when Cayenne acceleration is active, the default is 70% instead, reserving headroom for Cayenne's compaction memory pool and in-memory CDC tier. For deployments with co-located accelerators, set an explicit limit based on available memory: +If not specified, `memory_limit` defaults to 90% of the memory the process may use — its cgroup memory limit when one binds (a container, a `systemd` unit's `MemoryMax=`, a capped parent slice, or a Kubernetes pod cgroup), otherwise total system memory; when Cayenne acceleration is active, the default is 70% instead, reserving headroom for Cayenne's compaction memory pool and in-memory CDC tier. For deployments with co-located accelerators, set an explicit limit based on available memory: ```text runtime memory_limit = Total Memory - Accelerator Memory - OS/Runtime Overhead (30%) diff --git a/website/docs/reference/spicepod/runtime.md b/website/docs/reference/spicepod/runtime.md index 7f5a300a5..7ad22afc3 100644 --- a/website/docs/reference/spicepod/runtime.md +++ b/website/docs/reference/spicepod/runtime.md @@ -444,7 +444,7 @@ This configuration permits requests only from the `https://example.com` origin. The `memory_limit` parameter sets a memory usage cap for the Spice runtime query engine. This limit applies **only** to the query engine and should be used in addition to other memory configuration options, such as `duckdb_memory_limit`. When the limit is reached, DataFusion spills intermediate data to disk using the directory configured in `runtime.query.temp_directory`. -If not specified, defaults to **90% of total system memory** (container-aware). When Cayenne acceleration is active, the default is reduced to **70%** to reserve headroom for Cayenne's dedicated compaction memory pool and its in-memory CDC tier. When DuckDB accelerators are configured, that default is reduced further so the query pool and the DuckDB instance ceilings together fit within available memory — see [Coordinated memory budget](../../components/data-accelerators/duckdb#coordinated-memory-budget). An explicitly configured `memory_limit` is always honored verbatim and is never reduced. +If not specified, defaults to **90% of the memory the process may use** — its cgroup memory limit when one binds, otherwise total system memory. The limit is read from the process's own cgroup path (cgroup v2 `memory.max`, cgroup v1 `memory.limit_in_bytes`), taking the smallest limit found at any level of that path, so a container limit, a `systemd` unit's `MemoryMax=`, a capped parent slice, and a Kubernetes pod cgroup all size the default. When a cgroup limit binds, the runtime logs the figure it sized from at startup. When Cayenne acceleration is active, the default is reduced to **70%** to reserve headroom for Cayenne's dedicated compaction memory pool and its in-memory CDC tier. When DuckDB accelerators are configured, that default is reduced further so the query pool and the DuckDB instance ceilings together fit within available memory — see [Coordinated memory budget](../../components/data-accelerators/duckdb#coordinated-memory-budget). An explicitly configured `memory_limit` is always honored verbatim and is never reduced. ```yaml runtime: