Skip to content

[docs] Polish integrate_with_flink doc: self-contained snippets and language-scoped notes#800

Merged
wenjin272 merged 1 commit into
apache:mainfrom
wzhero1:777-polish-integrate-with-flink-doc
Jun 8, 2026
Merged

[docs] Polish integrate_with_flink doc: self-contained snippets and language-scoped notes#800
wenjin272 merged 1 commit into
apache:mainfrom
wzhero1:777-polish-integrate-with-flink-doc

Conversation

@wzhero1

@wzhero1 wzhero1 commented Jun 8, 2026

Copy link
Copy Markdown
Collaborator

Linked issue: #777

Purpose of change

Doc-quality follow-ups for docs/content/docs/development/integrate_with_flink.md, found during integrate_with_flink doc verification (#743):

  • Overview grammar: "By integrate agent with flink ..." → "By integrating agents with Flink DataStream/Table" (and capitalize Flink).
  • Self-contained snippets (Python + Java, DataStream + Table): replace the bare from_source(...) / fromSource(...) / from_elements(...) / fromValues(...) ellipses with concrete calls; define YourPojo (a valid Flink POJO), MyKeySelector, and RowKeySelector; add the missing imports (ExternalTypeInfo, RowTypeInfo, BasicTypeInfo, Schema, DataTypes, KeySelector, ...); and link each section to a runnable quickstart example.
  • Java "always nested row" comment: corrected — the agent output is exposed as a single anonymous column f0; declare f0 with the agent's output type (a scalar type for scalar output, a nested ROW(...) only for composite output). Matches the flat column("f0", DataTypes.STRING()) in FlinkIntegrationTest.testFromTableToTable.
  • Python vs Java column naming: document why the schemas look different — Python names output columns via the RowTypeInfo field names passed to to_table(), while Java's toTable(Schema) exposes the agent output as a single f0 column (it calls fromDataStream(DataStream<Object>, schema) internally).

Tests

Documentation-only change; no runtime impact. Verified manually:

  • Both Java snippets compile against Flink 2.2.0 with JDK 11 (javac clean; the POJO/KeySelector helpers as static nested classes, the pipeline fragments as methods).
  • Python snippets py_compile clean; MyKeySelector(), ExternalTypeInfo(RowTypeInfo([...], ["result"])), and Schema.new_builder().column("result", DataTypes.INT()).build() constructed on pyflink 2.2.1 (output_typeschema consistent); imports run-checked in the venv.
  • All four linked example files exist; no bare (...) left in executable code.
  • Hugo renders clean: shortcodes balanced (tabs/tab/hint) with no raw shortcode leakage, both code blocks render inside each tab, and both example links resolve.

API

No public API changes.

Documentation

  • doc-needed
  • doc-not-needed
  • doc-included

Closes #777

@github-actions github-actions Bot added doc-label-missing The Bot applies this label either because none or multiple labels were provided. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. labels Jun 8, 2026
@wzhero1 wzhero1 marked this pull request as draft June 8, 2026 07:00
@github-actions github-actions Bot added doc-included Your PR already contains the necessary documentation updates. and removed doc-label-missing The Bot applies this label either because none or multiple labels were provided. labels Jun 8, 2026
…anguage-scoped notes

- Fix Overview grammar: "By integrating agents with Flink DataStream/Table".
- Make the Python/Java DataStream and Table snippets self-contained: define
  YourPojo / MyKeySelector / RowKeySelector, replace bare "..." sources with
  concrete calls, add the real imports, and link to runnable examples.
- Correct the misleading Java "always a nested row" comment: the agent output
  is exposed as a single anonymous column f0; nest as ROW only for composite
  output (matches FlinkIntegrationTest.testFromTableToTable's flat f0 STRING).
- Document the Python/Java output-column naming difference (named RowTypeInfo
  fields vs the Java f0 default).

Closes apache#777
@wzhero1 wzhero1 force-pushed the 777-polish-integrate-with-flink-doc branch from 96ce94d to bb65aaa Compare June 8, 2026 07:15
@wzhero1 wzhero1 marked this pull request as ready for review June 8, 2026 08:18
@wzhero1 wzhero1 requested a review from wenjin272 June 8, 2026 08:18

@wenjin272 wenjin272 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM.

Regarding point four in #777, I believe we should reconsider the API design in the next release to align the Python and Java implementations and improve usability as much as possible. However, for version 0.3, providing a clear explanation in the documentation should be sufficient.

@wenjin272 wenjin272 merged commit 26eaffc into apache:main Jun 8, 2026
23 of 25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc-included Your PR already contains the necessary documentation updates. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Tech Debt] Polish integrate_with_flink doc: self-contained snippets and language-scoped notes

2 participants