docs: document CubeStore query-plan concurrency throttle env vars

[keydunov]

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

Description of Changes Made

PR #11924 (feat(cubestore): Limit how many logical plans are built at once) added two new environment variables to CubeStore but never documented them:

• CUBESTORE_MAX_CONCURRENT_QUERY_PLANS — caps how many SQL queries build a logical plan at once (default auto, sized to twice the available CPU cores with a floor of 4; 0 disables the gate).
• CUBESTORE_MAX_QUEUED_QUERY_PLANS — caps how many queries may wait for a planning slot before being rejected (default 5000).

This adds both to docs-mintlify/reference/configuration/environment-variables.mdx, in alphabetical order alongside the other CUBESTORE_* variables, following the existing table format used by neighboring entries.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mmz1eJ4vNFM32PNwwcBJ4s

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cubed3	🟢 Ready	View Preview	Sep 20, 2026, 12:12 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[claude]

Claude finished @keydunov's task in 1m 47s —— View job

---

Review complete — 1 medium, 1 medium, 1 low (3 inline comments)

Details

• Read the diff and the CubeStore throttle implementation (rust/cubestore/cubestore/src/queryplanner/planning_throttle.rs, config/mod.rs, queryplanner/mod.rs)
• Verified every factual claim in the new docs against the code
• Checked prior review threads
• Posted findings inline

Findings

#	Where	Issue
1	environment-variables.mdx:2129-2132	"planning isn't covered by CUBESTORE_QUERY_TIMEOUT" is false — queryplanner/mod.rs:296 passes Duration::from_secs(config.query_timeout()) as the throttle's max_wait and planning_throttle.rs:84-90 rejects with a message naming that var. The stated rationale is wrong and the timeout rejection path is undocumented.
2	environment-variables.mdx:2134-2136	0 omitted from possible values for CUBESTORE_MAX_QUEUED_QUERY_PLANS; per planning_throttle.rs:97 it disables the queue limit (unbounded queue), the opposite of the natural reading.
3	environment-variables.mdx:2121-2123	Table column padding misaligned vs the rest of the file (cosmetic).

Verified correct: auto = max(4, 2 * cores) with a fallback of 4 cores when available_parallelism() fails (config/mod.rs:1402-1407); 0 disabling the concurrency limit (planning_throttle.rs:34-36); default 5000 (config/mod.rs:1822); alphabetical placement between CUBESTORE_LOG_LEVEL and CUBESTORE_MAX_WS_CONNECTIONS_PER_USER. Not worth documenting but noted: values above Semaphore::MAX_PERMITS are silently clamped, and an unparseable value falls back to auto / 5000 with a warn log.

Review threads: the listing returned 0 of my own threads on this PR — none to resolve, none re-affirmed.

· branch `claude/gallant-ramanujan-s3fgl7`

[claude]

"planning isn't covered by CUBESTORE_QUERY_TIMEOUT" is backwards — the planning wait is bounded by it. rust/cubestore/cubestore/src/queryplanner/mod.rs:296 passes Duration::from_secs(config.query_timeout()) as the throttle's max_wait, and planning_throttle.rs:84-90 rejects with:

Waited longer than {} s (CUBESTORE_QUERY_TIMEOUT) for a query planning slot. Raise CUBESTORE_MAX_CONCURRENT_QUERY_PLANS to plan more queries at once.

So the queue cap isn't there because the wait is unbounded in time; it's there because the number of waiters is otherwise unbounded (memory, and a queue nobody can drain within the timeout anyway). The timeout-based rejection is also a second failure mode a reader needs to know about and this text currently denies it exists.

Suggested change

	is reached. A query that arrives once the queue is full is rejected rather
	than queued, since planning isn't covered by
	[`CUBESTORE_QUERY_TIMEOUT`](#cubestore_query_timeout) and an unbounded queue
	would otherwise grow without limit.
	is reached. A query that arrives once the queue is full is rejected immediately,
	rather than joining an unbounded queue. A query that does get a queue slot waits
	up to [`CUBESTORE_QUERY_TIMEOUT`](#cubestore_query_timeout) seconds for a
	planning slot and is rejected if none frees up in that time.

[claude]

0 is missing from the possible values, and it means the opposite of what a reader would assume. planning_throttle.rs:97 guards with if self.max_queued != 0 && queued > self.max_queued, so 0 disables the queue limit — unbounded queue — rather than "queue nothing, reject immediately". Someone reaching for 0 to get fail-fast behaviour gets the unbounded queue this variable exists to prevent.

Suggested change

	| Possible Values | Default in Development | Default in Production |
	| --------------- | ---------------------- | --------------------- |
	| A valid number | `5000` | `5000` |
	Set to `0` to disable the queue limit, which lets the queue grow without bound.
	| Possible Values | Default in Development | Default in Production |
	| ------------------------------- | ---------------------- | --------------------- |
	| `0` or a positive integer | `5000` | `5000` |

[claude]

Table pipes are misaligned — the separator row is one cell wider than the header, and the auto cells carry a trailing space. Renders fine, but every neighbouring entry in this file keeps the columns aligned.

Suggested change

	| Possible Values | Default in Development | Default in Production |
	| ------------------------------------ | ---------------------- | --------------------- |
	| `auto`, `0`, or a positive integer | `auto` | `auto` |
	| Possible Values | Default in Development | Default in Production |
	| ---------------------------------- | ---------------------- | --------------------- |
	| `auto`, `0`, or a positive integer | `auto` | `auto` |