pingcap / pingcap/docs

glossary.md's "Operator" entry only covers PD scheduling; execution-plan "operator" is undocumented and possibly ambiguous

Open
#23,595 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.