alamb opened a new pull request, #24634: URL: https://github.com/apache/datafusion/pull/24634
## Which issue does this PR close? - N/A -- documentation only. Inspired by the [DataFusion 55.0.0 release blog post](https://github.com/apache/datafusion-site/pull/203), which introduces `file_row_index()` and `input_file_name()` with a short, self-contained example. That example reads much better than what is currently in the function reference, so this PR brings it into the docs themselves. ## Rationale for this change Both `input_file_name()` and `file_row_index()` currently document the same placeholder example: ```sql SELECT input_file_name() FROM t; ``` This shows no output, and does not convey the two things a reader most needs to know about these functions: 1. They are *per-file* metadata, resolved during a file scan -- so a reader has to see them next to the data columns of an actual file to understand what they return. 2. `file_row_index()` is zero-based and scoped to a single file. Neither is apparent from `... FROM t`, where `t` is an unspecified table that may not even be file-backed. ## What changes are included in this PR? Replaces the `sql_example` in the `#[user_doc]` attribute for both functions with the complete example from the 55.0.0 blog post, and regenerates `docs/source/user-guide/sql/scalar_functions.md`: ```sql > COPY (SELECT * from values (100), (200), (300)) to '/tmp/foo.parquet'; > select *, input_file_name(), file_row_index() from '/tmp/foo.parquet'; +---------+-------------------+------------------+ | column1 | input_file_name() | file_row_index() | +---------+-------------------+------------------+ | 100 | tmp/foo.parquet | 0 | | 200 | tmp/foo.parquet | 1 | | 300 | tmp/foo.parquet | 2 | +---------+-------------------+------------------+ ``` The same example is used for both functions, since showing them together is what makes each one legible. Files touched: - `datafusion/functions/src/core/input_file_name.rs` - `datafusion/functions/src/core/file_row_index.rs` - `docs/source/user-guide/sql/scalar_functions.md` (generated by `dev/update_function_docs.sh`) ## Are these changes tested? There is no new behavior to test -- this only changes doc strings. The example output was verified by running it in `datafusion-cli` built from this branch, and matches byte-for-byte (including the `tmp/foo.parquet` path rendering, which is object-store path normalization rather than a typo). `dev/update_function_docs.sh` was run so that the generated documentation is in sync, which is what CI checks. ## Are there any user-facing changes? Yes, but documentation only -- the rendered examples for `input_file_name()` and `file_row_index()` in the SQL function reference. No API or behavior changes. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
