Skip to content

[hotfix] [docs] Rework 'Name and Description' section of operators overview to improve grammar and clarity #27201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+12 −12
Open

[hotfix] [docs] Rework 'Name and Description' section of operators overview to improve grammar and clarity #27201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/content/docs/dev/datastream/operators/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -676,16 +676,16 @@ some_stream.filter(...).slot_sharing_group("name")
{{< /tabs>}}

## Name And Description
Operators and job vertices in flink have a name and a description.
Both name and description are introduction about what an operator or a job vertex is doing, but they are used differently.
Operators and job vertices in Flink have a name and a description.
While the name and description both explain what an operator or a job vertex is doing, they are used differently.

The name of operator and job vertex will be used in web ui, thread name, logging, metrics, etc.
The name of a job vertex is constructed based on the name of operators in it.
Operator and job vertex names are used in the web UI, thread name, logging, metrics, etc.
The name of a job vertex is constructed using the names of operators it contains.
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "operators" -> "the operators"

The name needs to be as concise as possible to avoid high pressure on external systems.

The description will be used in the execution plan and displayed as the details of a job vertex in web UI.
The description of a job vertex is constructed based on the description of operators in it.
The description can contain detail information about operators to facilitate debugging at runtime.
The description of a job vertex is constructed using the descriptions of the operators it contains.
The description can contain detailed information about operators to facilitate debugging at runtime.
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when we say "is constructed" do we mean that Flink code constructs it, or user code? If it is Flink code then we should give an example of how the descriptions are constructed. If is is user code then we should make it obvious from the wording that this is advice / good practise around description content.

The line above "The name needs to be as concise as possible to avoid high pressure on external systems." I would suggest changing this to something like , the name should be descriptive, unique (within what ever scope); and concise (why does a long name create high pressure on external systems?)


{{< tabs namedescription >}}
{{< tab "Java" >}}
Expand All @@ -700,12 +700,12 @@ some_stream.filter(...).name("filter").set_description("x in (1, 2, 3, 4) and y
{{< /tab >}}
{{< /tabs>}}

The format of description of a job vertex is a tree format string by default.
Users can set `pipeline.vertex-description-mode` to `CASCADING`, if they want to set description to be the cascading format as in former versions.
Depending on your needs, you may want to modify some of the default naming behaviors for vertices and operators.

Operators generated by Flink SQL will have a name consisted by type of operator and id, and a detailed description, by default.
Users can set `table.exec.simplify-operator-name-enabled` to `false`, if they want to set name to be the detailed description as in former versions.
By default, the description of a job vertex is organized in a multi-tree line mode.
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does multi-tree line mode mean?

To use a single line cascading mode, set `pipeline.vertex-description-mode` to `CASCADING`
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest giving examples of these modes


When the topology of the pipeline is complex, users can add a topological index in the name of vertex by set `pipeline.vertex-name-include-index-prefix` to `true`,
so that we can easily find the vertex in the graph according to logs or metrics tags.
By default, operators generated by Flink SQL will have a name composed of the operator type and id. Details will remain in the description.
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you mention "Details will remain in the description.". What details are these - it would be better to list them.
You say remain - I am not sure what we are trying to say with this. I suggest something like:
"The description contains more information on the operator including ...."

To include the description, set `table.exec.simplify-operator-name-enabled` to `false`
Copy link
Contributor

@davidradl davidradl Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would think table.exec.simplify-operator-name-enabled
true : would mean a simplified name with more details in the description.
false: would mean a more complicated name including elements of the description. Does this mean there is no description?

I am not sure this sentence is saying that. Did I understand correctly?


If the topology of the pipeline is complex, you can prefix vertex names with their topological index by setting `pipeline.vertex-name-include-index-prefix` to `true`. This makes it easier to find vertices in logs or metrics tags.