elastic / elastic/docs-content
[Internal]: Document all of the ways to update ES settings
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 17h
- Merged PRs (30d)
- 130
Description
### Description
Do a better job of explaining how settings can be set / overridden / reset, impact of JSON parsing order
Raised in https://github.com/elastic/elasticsearch-specification/issues/4435, behavior outlined in https://docs.google.com/document/d/1DqkEMTCyJsFArJP_ePj4zFsuTx2-0UNsH4NGmjg00yQ/edit?tab=t.0#heading=h.vwpq1kn6hahn
Impacts both cluster + index settings
### Resources
https://docs.google.com/document/d/1DqkEMTCyJsFArJP_ePj4zFsuTx2-0UNsH4NGmjg00yQ/edit?tab=t.0#heading=h.vwpq1kn6hahn
Content up to, but not including "How to model index settings in the API specification?"
### Which documentation set does this change impact?
Unknown
### Feature differences
-
### What release is this request related to?
N/A
### Serverless release
-
### Collaboration model
The documentation team
### Point of contact.
**Main contact:** @l-trotta
---
## Elastic Docs AI Scoping 🤖
Docs issue scope
### Summary
The issue requests better documentation of all the ways Elasticsearch settings can be set, overridden, and reset — specifically covering the coexistence of flat dotted notation (e.g., `indices.recovery.max_bytes_per_sec`) and nested JSON hierarchy, JSON parsing order (last value in text order wins), wildcard resets for cluster settings, and the "index" prefix equivalence for index settings. The linked elasticsearch-specification issue (#4435, now closed/completed) confirms these behaviors are real and provides concrete examples. There are no linked code-change PRs — this is a documentation gap for existing, undocumented behavior. The primary technical content source is the Google Doc referenced in the issue (internal) and the elasticsearch-specification issue body.
### Request accuracy
Accurate — the elasticsearch-specification issue provides detailed examples confirming all four behaviors are present and undocumented.
### Next action for author
Add a new "API request formats" (or equivalent) section to `deploy-manage/stack-settings.md` covering the four JSON representation behaviors, using examples from the elasticsearch-specification issue and the internal Google Doc.
### Impact: High
### Scope boundary
Node-level and static settings (elasticsearch.yml) do not need changes — this is scoped to the dynamic settings API request format behaviors only.
### Recommended documentation targets
| Page | URL | Action | Impact | Confidence | Why this page? |
|------|-----|--------|--------|------------|----------------|
| Elastic Stack settings | https://www.elastic.co/docs/deploy-manage/stack-settings | Add section to existing page | High | High | This page already covers dynamic settings (transient/persistent, null reset) and is the natural home for a new subsection on API request formats (flat vs. nested, parsing order, wildcards, index prefix). |
| Dynamic settings snippet | `deploy-manage/deploy/self-managed/_snippets/dynamic-settings.md` (transcluded into stack-settings.md) | Update existing page | Medium | High | The snippet briefly describes transient/persistent and null reset but omits JSON format behaviors; expanding it or adding a link from it would catch all pages that include it. |
| Cluster update settings API reference | https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings | Review only | Medium | Medium | This API reference page (likely in the elasticsearch-specification or elasticsearch server repo, not this repo) should document the wildcard reset and flat/nested coexistence for cluster settings. |
| Update index settings API reference | https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings | Review only | Medium | Medium | This API reference page should document the "index" prefix equivalence and flat/nested mixing for index settings. |
### Recommendations
1. In `deploy-manage/stack-settings.md`, add a subsection under "Dynamic and static Elasticsearch settings" titled something like **"Setting request formats"** that covers:
- Flat dotted names (e.g., `indices.recovery.max_bytes_per_sec`) and nested JSON objects are both valid and can be mixed in a single request.
- When both forms appear in the same request body, the last value encountered in JSON text order takes precedence.
- For cluster settings, wildcards can be used to reset a group of settings at once (both flat `"indices.*": null` and nested `"indices": {"*": null}` work).
- For index settings, requests with no prefix, with the `index.` dotted prefix, and with the nested `index:{}` wrapper are all equivalent.
2. Update (or add a cross-reference from) the `dynamic-settings.md` snippet to point to the new section.
3. File follow-up issues (or coordinate with `@pquentin`) to update the Cluster update settings and Update index settings API reference pages in the elasticsearch-specification repo.
### Notes
- The `stack-settings.md` page currently functions as a mixed-purpose configuration overview; adding a focused "request formats" subsection fits its existing role and avoids creating a new standalone page for what is conceptually a short reference section.
- The examples in the elasticsearch-specification issue body (#4435) can be used directly as illustrative code snippets.
- The internal Google Doc should be reviewed for any additional edge cases not captured in the specification issue before writing.
---
[Docs automation](https://github.com/elastic/docs-actions) | [From workflow: Issue Scope Analyzer](https://github.com/elastic/docs-content/actions/runs/24730380927)
React with 👍 if helpful, 👎 if not.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.