docs(influxdb3): define cache --node-spec semantics and warm-up trade-off - #7640
Open
reidkaufmann wants to merge 1 commit into
Open
docs(influxdb3): define cache --node-spec semantics and warm-up trade-off#7640reidkaufmann wants to merge 1 commit into
reidkaufmann wants to merge 1 commit into
Conversation
…-off Document what --node-spec actually controls for last and distinct value caches: which Enterprise nodes load historical data into the cache. All query-capable nodes serve the cache and add newly written data. - Add the flag to the CLI reference pages (it was undocumented there). - Replace the undefined 'configured on' wording on the admin create pages with the historical-data-load semantics and the trade-off: specify a node list only to reduce initial cache warm-up load, and only if temporarily incomplete query results from excluded nodes are acceptable. - Add an Enterprise caveat to the 'Cache data loading' sections, which previously promised unconditional historical loading. Depends on influxdata/influxdb_pro#5155 for the serve-and-update behavior on excluded nodes.
Contributor
Vale Style Check Results
Warnings (8)
✅ Check passed |
Contributor
🔗 Link Check Results — Link Check Bot✅ All links are valid
|
| Source File | URL | Issue |
|---|---|---|
content/influxdb3/core/admin/distinct-value-cache/create/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/distinct-value-cache/create/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/admin/distinct-value-cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/admin/distinct-value-cache/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/last-value-cache/create/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/admin/last-value-cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/reference/cli/influxdb3/create/distinct_cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/reference/cli/influxdb3/create/last_cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/reference/cli/influxdb3/create/last_cache/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/distinct-value-cache/create/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/distinct-value-cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/last-value-cache/create/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/last-value-cache/create/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/last-value-cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/reference/cli/influxdb3/create/distinct_cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/reference/cli/influxdb3/create/last_cache/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/reference/cli/influxdb3/create/last_cache/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
Full details: workflow run summary and artifact. Last updated: 2026-08-11 16:51:49 UTC
reidkaufmann
requested review from
cannonpalms,
jstirnaman,
peterbarnett03 and
sanderson
August 11, 2026 16:53
reidkaufmann
marked this pull request as ready for review
August 11, 2026 16:56
Contributor
There was a problem hiding this comment.
Pull request overview
Documents Enterprise --node-spec cache warm-up semantics and incomplete-result trade-offs.
Changes:
- Adds CLI option references for LVC and DVC.
- Clarifies historical loading and restart behavior.
- Adds multi-node operational guidance.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
influxdb3-cli/create/last_cache.md |
Documents the LVC option. |
influxdb3-cli/create/distinct_cache.md |
Documents the DVC option. |
influxdb3-admin/last-value-cache/create.md |
Expands LVC creation guidance. |
influxdb3-admin/last-value-cache/_index.md |
Explains multi-node LVC loading. |
influxdb3-admin/distinct-value-cache/create.md |
Expands DVC creation guidance. |
influxdb3-admin/distinct-value-cache/_index.md |
Explains multi-node DVC loading. |
Suppressed comments (2)
content/shared/influxdb3-admin/last-value-cache/create.md:22
- These sentences promise that excluded nodes serve and update the cache, but the PR description says released versions instead error on excluded query nodes until restart; this behavior depends on the unshipped
influxdb_pro#5155. Keep the PR draft until the fix ships, or document the current version-specific limitation so the published instructions remain accurate.
to specific nodes. All query-capable nodes serve the LVC and add newly
written data to it, but excluded nodes return incomplete query results until
new data arrives. Only specify a node list if you accept temporarily
incomplete query results from excluded nodes.
content/shared/influxdb3-admin/distinct-value-cache/create.md:22
- These sentences promise that excluded nodes serve and update the cache, but the PR description says released versions instead error on excluded query nodes until restart; this behavior depends on the unshipped
influxdb_pro#5155. Keep the PR draft until the fix ships, or document the current version-specific limitation so the published instructions remain accurate.
to specific nodes. All query-capable nodes serve the DVC and add newly
written data to it, but excluded nodes return incomplete query results until
new data arrives. Only specify a node list if you accept temporarily
incomplete query results from excluded nodes.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| | Option | | Description | | ||
| | :----- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `-n` | `--node-spec` | Which node(s) load historical data into the cache. Two value formats are supported: `all` (default) - all query- and processing-capable nodes load historical data, or `nodes:<node-id>[,<node-id>..]` - only the listed nodes load historical data, reducing the initial cache warm-up load at the cost of temporarily incomplete query results from excluded nodes | |
|
|
||
| | Option | | Description | | ||
| | :----- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `-n` | `--node-spec` | Which node(s) load historical data into the cache. Two value formats are supported: `all` (default) - all query- and processing-capable nodes load historical data, or `nodes:<node-id>[,<node-id>..]` - only the listed nodes load historical data, reducing the initial cache warm-up load at the cost of temporarily incomplete query results from excluded nodes | |
Comment on lines
+100
to
+102
| Excluded nodes still serve the cache and add newly written data to it, | ||
| but until new data arrives, queries served by those nodes return only values | ||
| written after the cache was created (or after the node restarted). |
Comment on lines
+86
to
+88
| Excluded nodes still serve the cache and add newly written data to it, | ||
| but until new data arrives, queries served by those nodes return only values | ||
| written after the cache was created (or after the node restarted). |
Comment on lines
+15
to
+22
| - **Node specification** (`-n`, `--node-spec`): Specify which nodes load | ||
| historical data into the LVC. The default (`all`) loads historical data on | ||
| all query- and processing-capable nodes. To reduce the initial cache warm-up | ||
| load, use `nodes:<node-id>[,<node-id>...]` to limit the historical data load | ||
| to specific nodes. All query-capable nodes serve the LVC and add newly | ||
| written data to it, but excluded nodes return incomplete query results until | ||
| new data arrives. Only specify a node list if you accept temporarily | ||
| incomplete query results from excluded nodes. |
Contributor
📦 PR Preview — Preview Bot
Changed pages (12)
Preview auto-deploys on push. Will be cleaned up when PR closes. |
Contributor
Author
|
Status update: the behavior this documents is now merged — influxdata/influxdb_pro#5155 (squash |
jstirnaman
approved these changes
Aug 14, 2026
Contributor
Author
|
@jstirnaman Do you want me to wait to merge until 3.11.2 releases? Some content is correct now, but a few statements only become true upon release of 3.11.2 and/or 3.12... |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
--node-specflag oninfluxdb3 create last_cache/create distinct_cache(Enterprise) has never had defined semantics in the docs — the admin pages say only "Specify which nodes the [cache] should be configured on," the CLI reference pages omit the flag entirely, and the shared "Cache data loading" sections promise unconditional historical loading with no node-spec caveat.This PR documents what the flag actually controls: which Enterprise nodes load historical data into the cache (at creation and on restart). All query-capable nodes serve the cache and add newly written data to it. The guidance is explicit about when to use it: only to reduce the initial cache warm-up load, and only if temporarily incomplete query results from excluded nodes are acceptable.
Changes (all in
content/shared/, Enterprise-gated with{{% show-in "enterprise" %}})influxdb3-cli/create/last_cache.md,influxdb3-cli/create/distinct_cache.md: add an "Additional Enterprise option" table for-n/--node-spec(pattern borrowed fromcreate/trigger.md), including the warm-up/incomplete-results trade-off. The flag was previously undocumented on these pages.influxdb3-admin/last-value-cache/create.md,influxdb3-admin/distinct-value-cache/create.md: replace the undefined "configured on" bullet with the historical-data-load semantics and the "only specify a node list if…" guidance.influxdb3-admin/last-value-cache/_index.md,influxdb3-admin/distinct-value-cache/_index.md: add an Enterprise paragraph to "Cache data loading" covering multi-node behavior: excluded nodes don't load historical data (at creation or restart), still serve and update the cache, and return only post-creation/post-restart values until new data arrives.Dependency / timing
The "excluded nodes still serve the cache and add newly written data to it" behavior is completed by influxdata/influxdb_pro#5155 (in review). Released versions have a defect where a cache created with an explicit node list errors on excluded query nodes until they restart (EAR-driven fix; see influxdata/EAR#7045). Suggest holding this PR as draft until #5155 merges and/or ships. Historical-load semantics (
--node-specgating warming) are accurate for released versions.Verification
npx hugo --quiet: clean build.influxdb3/enterprise/...pages (admin LVC/DVC + CLI reference) and does not appear on the correspondinginfluxdb3/core/...pages; the internal links to the create pages render.yarn lint/ lefthook pre-commit: pass (Vale skipped locally — no binary/Docker; runs in CI).