glossary.md's "Operator" entry only covers PD scheduling; execution-plan "operator" is undocumented and possibly ambiguous
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 617
- Forks
- 724
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 223
Description
What did you do?
While reviewing Japanese translation consistency for the term "operator" (see https://github.com/pingcap/docs/pull/23594), I found that glossary.md defines "Operator" strictly as a PD scheduling concept:
Operator
An operator is a collection of actions that applies to a Region for scheduling purposes. Operators perform scheduling tasks such as "migrate the leader of Region 2 to Store 5" and "migrate replicas of Region 2 to Store 1, 4, 5".
An operator can be computed and generated by a scheduler, or created by an external API.
However, the bare word "operator" is also used elsewhere in the docs for a completely different concept — a node/step in a query execution plan (e.g. TableScan, HashAgg, Exchange, IndexLookUp), for example in partitioned-table.md ("each operator supports direct access to multiple partitions") and throughout the EXPLAIN-related pages. This second sense has no glossary entry of its own and is not distinguished from the PD-scheduling sense anywhere in the docs.
What did you expect to see?
Either:
- A separate glossary entry (or a disambiguation note on the existing "Operator" entry) for the execution-plan sense of "operator", so readers landing on the glossary from an EXPLAIN-related page aren't given an unrelated PD-scheduling definition, or
- Confirmation that this overlap is intentional/acceptable, so translation teams (and future doc edits) know to keep treating both senses as the same term rather than trying to disambiguate them.
What did you see instead?
A single "Operator" glossary entry that only documents one of (at least) two distinct technical meanings the word carries elsewhere in the docs, with no cross-reference or disambiguation between them.
Additional context
This surfaced while normalizing the Japanese translation's katakana spelling for "operator" (オペレータ → オペレーター) across both PD-scheduling and execution-plan contexts. Since the English source itself doesn't distinguish the two senses, the Japanese translation currently mirrors that (uses the same term for both) — but it would help future translation/editing work to have an explicit answer on whether that's the intended approach.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with glossary.md, then compare the Operator entry with the operator usage in partitioned-table.md and the EXPLAIN-related pages. Trace both meanings and check whether existing documentation distinguishes them. Done means either a clear glossary cross-reference or disambiguation for execution-plan operators, or a recorded decision that the shared term is intentional.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- sql
- Domain
- databases, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100