raminqaf opened a new pull request, #29864:
URL: https://github.com/apache/flink/pull/29864
## What is the purpose of the change
Step 2 of FLINK-23804: every function of five categories gets a page of its
own, generated from YAML. A page has the SQL, Java and Python syntax, the
arguments, what it returns and when it returns NULL, usage notes, and examples.
Each function was rechecked against its implementation, and every example
result comes from running its SQL. The recheck changed what the docs say, for
example:
| Function | Old docs
| Master
|
|----------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------|
| `REGEXP_REPLACE` | Says nothing about the replacement
| `$1` is inserted as written. The replacement can't refer
to groups. |
| `REGEXP_EXTRACT_ALL` | `extractIndex` defaults to 1
| So a regex without groups returns NULL unless you pass 0
|
| `RANK` | "one plus the number of rows preceding or equal to
the current row" | One plus the rows before it. Peers aren't counted.
|
| `TRY_CAST` | `COALESCE(TRY_CAST('non-number' AS INT), 0)`
"returns 0 of type INT" | The type is `INT NOT NULL`
|
| `LEAD` | No mention of streaming
| Fails in streaming mode with `LEAD Function is not
supported in stream mode.` |
## Brief change log
- Bump Hugo from 0.124.1 to 0.126.3. The pages come from a content adapter,
which needs Hugo 0.126. The docs CI script passes `--logLevel info` instead of
`-v`, which 0.126.3 logs as a deprecation error.
- Generate one page per `data/functions/<category>/<name>.yml`, in English
and Chinese. The category tables and the A-Z page link converted rows to their
page. A category in the sidebar expands to its function pages.
- Add 33 pages: Regular Expressions 7, Cast 2, Conditional 7, Window 9,
Utility 8. Every row of these categories now points at a page.
- Chinese pages show the English sections. Where a row had a Chinese
description, its first sentence becomes the summary.
- Two Table API-only rows lose their Scala-only form: `BOOLEAN.?` folds into
the `IF` row as `BOOLEAN.then`, and `NUMERIC.rows` becomes `rowInterval(LONG)`.
- Add a guide for function pages to `docs/README.md`, and point AGENTS.md
step 8 at it.
## Verifying this change
This change is documentation only.
- Every SQL example ran in batch and streaming mode on master with a local
runner, which isn't part of this PR. The results on the pages are pasted from
those runs.
- A second review per category checked each statement against the type
strategies, the runtime code and the tests.
- Hugo 0.126.3 builds both languages without warnings. A link check finds no
new broken internal links. The A-Z page still lists 241 functions in English
and 238 in Chinese, as on master, and 15 Table API-only entries instead of 16.
- Every commit builds on its own.
The recheck found bugs in the code, which this PR doesn't fix. The pages
describe the intended behavior, and I'll file the bugs separately.
## Does this pull request potentially affect one of the following parts:
- Dependencies (does it add or upgrade a dependency): no
- The public API, i.e., is any changed class annotated with
`@Public(Evolving)`: no
- The serializers: no
- The runtime per-record code paths (performance sensitive): no
- Anything that affects deployment or recovery: JobManager (and its
components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
- The S3 file system connector: no
## Documentation
- Does this pull request introduce a new feature? no
- If yes, how is the feature documented? not applicable
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes (please specify the tool below)
Generated-by: Claude Code 2.1.321 (Claude Opus 5.5)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
