[Feature] Add a description column to SHOW VARIABLES output
- Dominant language
- Java
- Stars
- 15.9k
- Forks
- 3.9k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 520
Description
### Search before asking
- [x] I had searched in the [issues](https://github.com/apache/doris/issues?q=is%3Aissue) and found no similar issues.
### Description
Please add a description field to the result of `SHOW VARIABLES`, preferably as an appended third column so that the existing first two columns remain unchanged.
Example:
| Variable_name | Value | Description |
| --- | --- | --- |
| enable_nereids_planner | true | Enables the Nereids query planner. Disabling it may change planner behavior and query performance. |
The description should include, where applicable:
- what the variable controls;
- the consequences and risks of changing it;
- valid values or ranges;
- scope (session/global);
- whether it is dynamic or requires a restart.
Ideally, the description should come from a single metadata source in the codebase so that SQL output and documentation remain consistent.
Some clients may assume that `SHOW VARIABLES` always returns exactly two columns. If appending a column is considered incompatible, an alternative could be `SHOW VARIABLES EXTENDED` or an equivalent metadata view/table that exposes variable descriptions.
### Use case
Currently, `SHOW VARIABLES` returns the variable name and its current value, but it does not explain what each variable controls.
Administrators and developers must search the documentation separately to understand a variable's purpose, the effect and risks of changing it, its valid range, scope, and whether a restart is required. This makes variable discovery, troubleshooting, and tuning less efficient, especially when reviewing many variables.
I have observed this behavior in Doris 3.1.4 and 4.1.3. Making variables self-describing would improve operational troubleshooting, tuning, and discoverability.
### Related issues
No related issue found. I searched the apache/doris issue tracker for SHOW VARIABLES descriptions and variable metadata.
### Are you willing to submit PR?
- [ ] Yes I am willing to submit a PR!
### Code of Conduct
- [x] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct)
Contributor guide
Research direction
Start by tracing the SHOW VARIABLES implementation and how variable metadata is currently defined and documented; the issue does not name specific files or tests. Determine whether an appended Description column is compatible with existing clients or whether an extended command or metadata view is needed. Done means variable descriptions cover the requested metadata and remain consistent between SQL output and documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, sql
- Domain
- databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100