Node settings are runtime-tunable knobs that apply to a single node. Every setting is a transient override over the persistent pizza.yml value (or the built-in default): a change takes effect immediately via PUT and disappears at restart — set the same key in the yml for a persistent value. This is the node-scope sibling of the Raft-replicated Region Settings: routing policy is cluster-wide, while log verbosity, search lane budgets and trash retention are per-node concerns.

The setting names are their pizza.yml paths for node.search.* and log.level, so a runtime tweak can be moved into the config file verbatim. The two trash settings are the exception: their runtime names are node.trash.* but their persistent yml home is the top-level trash: section (trash.retention_secs, trash.orphan_scan_enabled).

Get Node Settings #

Returns the node-local dynamic settings in effect on this node.

Requests #

GET /_node/_local/settings

On any node, a peer’s settings can be read through the unified forward:

GET /_node/<node_id>/settings

Response #

Per setting — the effective value, its source (runtime_override, config or default) and the config_value a restart falls back to:

{
  "node.search.max_concurrent": {
    "value": 64,
    "source": "config",
    "config_value": 64
  },
  "node.search.slow_threshold_ms": {
    "value": 200,
    "source": "runtime_override",
    "config_value": 500
  },
  "log.level": {
    "value": "debug",
    "source": "runtime_override",
    "config_value": "info"
  }
}

Update Node Settings #

Retunes node-local settings at runtime.

Requests #

PUT /_node/_local/settings

Remote nodes are reached through the forward:

PUT /_node/<node_id>/settings

Request body #

A JSON object mapping pizza.yml keys to values; a null value clears that key’s override (falling back to the yml config). Unknown keys and out-of-range values are rejected with 400.

{
  "node.search.slow_threshold_ms": 200,
  "node.search.max_concurrent": 128,
  "node.trash.retention_secs": 3600,
  "node.trash.orphan_scan_enabled": false,
  "log.level": "debug"
}

Settings catalog #

Setting	Default	Type	Description
`node.search.max_concurrent`	`64`	integer 1–1024	Per-node cap on FAST-lane searches this node’s coordinator dispatches. Over the cap, an overloaded node’s shard copies are skipped during copy selection.
`node.search.heavy_concurrency`	`8`	integer 1–1024	Per-node cap for HEAVY-lane searches (aggregations, deep pagination, very large collect windows).
`node.search.slow_threshold_ms`	`500`	integer 0–3600000	Searches slower than this (milliseconds) are captured by the node’s search slowlog; `0` captures every search.
`node.search.default_timeout_ms`	`30000`	integer 1–3600000	Cooperative search deadline when the request carries no `timeout`; on expiry the collector returns partial results with `timed_out: true`.
`node.trash.retention_secs`	`86400`	integer 0–2³²	How long deleted data survives in the trash before the sweeper purges it; `0` purges on the next tick.
`node.trash.orphan_scan_enabled`	`true`	boolean	Whether the sweeper also trashes orphan directories that no live metadata references.
`log.level`	`info`	trace/debug/info/warn/error	Global log level for this node — swapped immediately, no restart. Target-specific directives from the config filter (e.g. `openraft=warn`) are preserved.

Task lane settings #

The node’s maintenance lanes have their own settings endpoint with the same transient semantics (0 or null restores the config default):

GET /_node/_local/settings/tasks
PUT /_node/_local/settings/tasks

{
  "flush_concurrency": 4,
  "flush_paused": false,
  "compaction_paused": false,
  "compaction_every_ticks": 4
}

flush_concurrency — integer 0–16, concurrent manual epoch flushes (0 resets to the node.flush_concurrency config default, 2).
flush_paused — boolean; a paused lane holds queued flushes, an in-flight shard flush always finishes.
compaction_paused — boolean; holds NEW compaction passes node-wide, in-flight merges drain. The manual compact API is not gated by this.
compaction_every_ticks — integer 0–14400 maintenance ticks (500 ms each) between compaction passes. Defaults to 120 ticks (60 s); 0 restores the default cadence.

Epoch freeze settings #

The WAL-cutting thresholds — when an active epoch exceeds either limit it is frozen and built into a segment:

GET /_node/_local/settings/epoch_freeze
PUT /_node/_local/settings/epoch_freeze

{
  "max_bytes": 33554432,
  "max_ops": 160000
}

max_bytes — unsigned integer, minimum 1 MiB; 0 clears the override.
max_ops — unsigned integer; 0 clears the override. At least one of the two limits must stay > 0.

Restart fallbacks live at wal.local.epoch_freeze_max_bytes / wal.local.epoch_freeze_max_ops in pizza.yml; the built-in defaults are 16 MiB (16777216) and 160,000 ops — the 33554432 above is an example value (32 MiB), not the default.

Epoch build settings #

The background (off-thread) segment build admission controls:

GET /_node/_local/settings/epoch_build
PUT /_node/_local/settings/epoch_build

{
  "max_concurrent_builds": 6,
  "paused": false
}

max_concurrent_builds — integer 1–64; 0 clears the override (falling back to PIZZA_MAX_NODE_BUILDS / the default of 6).
paused — boolean; pausing holds NEW builds only — in-flight builds drain and frozen epochs wait in the backlog. The manual flush API is not gated by this.

Examples #

# drop the slowlog threshold to 200ms on one node, effective immediately
curl -X PUT http://127.0.0.1:28000/_node/_local/settings \
  -H 'Content-Type: application/json' \
  -d '{"node.search.slow_threshold_ms": 200}'

# the same change on a remote node, through the gateway forward
curl -X PUT http://127.0.0.1:28000/_node/5f0c.../_node/_local/settings \
  -H 'Content-Type: application/json' \
  -d '{"node.search.slow_threshold_ms": 200}'

# clear the override — the node falls back to its pizza.yml value
curl -X PUT http://127.0.0.1:28000/_node/_local/settings \
  -H 'Content-Type: application/json' \
  -d '{"node.search.slow_threshold_ms": null}'

# make it persistent: the key doubles as the pizza.yml path
# node:
#   search:
#     slow_threshold_ms: 200