You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@datafusion.apache.org by "2010YOUY01 (via GitHub)" <gi...@apache.org> on 2026/10/02 10:07:47 UTC
[PR] chore: Hide internal public utility APIs [datafusion]
2010YOUY01 opened a new pull request, #25963:
URL: https://github.com/apache/datafusion/pull/25963
## Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and enhancements and this helps us generate change logs for our releases. You can link an issue to this PR using the GitHub syntax. For example `Closes #123` indicates that this PR will close issue #123.
-->
- Closes #.
## Rationale for this change
<!--
Why are you proposing this change? If this is already explained clearly in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand your changes and offer better suggestions for fixes.
Please explain the problem you are trying to solve in terms of the user-visible
behavior, rather than the implementation.
For example, "The code in `foo.rs` doesn't handle nulls" is a symptom of the
implementation. "COUNT(DISTINCT) returns wrong results when the column contains
nulls" is the user-visible problem.
-->
See the previous PR for rationale
- https://github.com/apache/datafusion/pull/25495
This PR adds #[doc(hidden)] and comments for public APIs that is used as internal utility.
The major categories are
- already includes `#doc(hidden)`
- Already explained in the comment that this public API is internal-only
- Optimizer utilities, with strict preconditions to use it correctly.
## What changes are included in this PR?
<!--
There is no need to duplicate the description in the issue here, but it is sometimes worth providing a summary of the individual changes in this PR.
-->
comments only
## What is the testing strategy for this PR?
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code
Briefly describe how this PR is tested, and point to the specific tests you added. For example: 'This new feature is covered by the `sqllogictest` cases added in `foo.slt`'.
If this PR does not add tests, explain why. For example, if the change is already covered by existing tests, please mention it.
You should also check the `codecov` bot reply on this PR to confirm the changed code is exercised.
-->
## Are there any user-facing changes?
<!--
If there are user-facing changes then we may require documentation to be updated before approving the PR.
If there are any breaking changes to public APIs, please add the `api change` label.
-->
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "alamb (via GitHub)" <gi...@apache.org>.
alamb commented on code in PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#discussion_r4223479615
##########
datafusion/expr/src/logical_plan/plan.rs:
##########
@@ -2837,6 +2837,12 @@ impl Filter {
/// - the `predicate` expression returns a boolean value
/// - the `predicate` expression is not aliased
/// - the `predicate` expression contains no window function calls
+ ///
+ /// # Public Only for Internal Use:
Review Comment:
in fact the comment above says "for internal use in Datafusion only"
##########
datafusion/physical-plan/src/joins/hash_join/exec.rs:
##########
@@ -1408,6 +1408,13 @@ impl HashJoinExec {
/// physical optimizer rule to determine a good join order, which is
/// executed before the `EnforceDistribution` rule (the rule that may
/// insert `RepartitionExec` operators).
+ ///
+ /// # Public Only for Internal Use:
+ ///
+ /// This is not a public API and is for internal use only; see [API policy] for details.
+ ///
+ /// [API policy]: https://datafusion.apache.org/contributor-guide/api-health.html#internal-public-apis
+ #[doc(hidden)]
Review Comment:
This one in particular I would like to maybe add a comment about "might change" or "is tricky to use" if posisble to make it easier to understand the internal marking
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#issuecomment-5950052982
<!-- semver-check-comment -->
Thank you for opening this pull request!
Reviewer note: [cargo-semver-checks](https://github.com/obi1kenobi/cargo-semver-checks) reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch).
<details>
<summary>Details</summary>
```
Cloning apache/main
Building datafusion-expr v55.1.0 (current)
Built [ 24.164s] (current)
Parsing datafusion-expr v55.1.0 (current)
Parsed [ 0.066s] (current)
Building datafusion-expr v55.1.0 (baseline)
Built [ 24.030s] (baseline)
Parsing datafusion-expr v55.1.0 (baseline)
Parsed [ 0.066s] (baseline)
Checking datafusion-expr v55.1.0 -> v55.1.0 (no change; assume patch)
Checked [ 1.765s] 223 checks: 223 pass, 31 skip
Summary no semver update required
Finished [ 51.593s] datafusion-expr
Building datafusion-physical-expr v55.1.0 (current)
Built [ 23.895s] (current)
Parsing datafusion-physical-expr v55.1.0 (current)
Parsed [ 0.039s] (current)
Building datafusion-physical-expr v55.1.0 (baseline)
Built [ 22.885s] (baseline)
Parsing datafusion-physical-expr v55.1.0 (baseline)
Parsed [ 0.039s] (baseline)
Checking datafusion-physical-expr v55.1.0 -> v55.1.0 (no change; assume patch)
Checked [ 0.460s] 223 checks: 223 pass, 31 skip
Summary no semver update required
Finished [ 48.424s] datafusion-physical-expr
Building datafusion-physical-expr-common v55.1.0 (current)
Built [ 18.955s] (current)
Parsing datafusion-physical-expr-common v55.1.0 (current)
Parsed [ 0.017s] (current)
Building datafusion-physical-expr-common v55.1.0 (baseline)
Built [ 19.200s] (baseline)
Parsing datafusion-physical-expr-common v55.1.0 (baseline)
Parsed [ 0.018s] (baseline)
Checking datafusion-physical-expr-common v55.1.0 -> v55.1.0 (no change; assume patch)
Checked [ 0.272s] 223 checks: 223 pass, 31 skip
Summary no semver update required
Finished [ 39.480s] datafusion-physical-expr-common
Building datafusion-physical-plan v55.1.0 (current)
Built [ 30.636s] (current)
Parsing datafusion-physical-plan v55.1.0 (current)
Parsed [ 0.137s] (current)
Building datafusion-physical-plan v55.1.0 (baseline)
Built [ 31.081s] (baseline)
Parsing datafusion-physical-plan v55.1.0 (baseline)
Parsed [ 0.137s] (baseline)
Checking datafusion-physical-plan v55.1.0 -> v55.1.0 (no change; assume patch)
Checked [ 0.904s] 223 checks: 218 pass, 5 fail, 0 warn, 31 skip
--- failure enum_now_doc_hidden: pub enum is now #[doc(hidden)] ---
Description:
A pub enum is now #[doc(hidden)], removing it from the crate's public API.
ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/enum_now_doc_hidden.ron
Failed in:
enum Map in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/joins/mod.rs:88
--- failure function_now_doc_hidden: pub function is now #[doc(hidden)] ---
Description:
A pub function is now #[doc(hidden)], removing it from the crate's public API.
ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/function_now_doc_hidden.ron
Failed in:
function get_best_fitting_window in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/windows/mod.rs:604
function concat_slices in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/aggregates/mod.rs:3263
--- failure inherent_method_now_doc_hidden: inherent method #[doc(hidden)] added ---
Description:
A method or associated fn is now #[doc(hidden)], removing it from the crate's public API.
ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/inherent_method_now_doc_hidden.ron
Failed in:
HashJoinExec::swap_inputs in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/joins/hash_join/exec.rs:1411
SymmetricHashJoinExec::check_if_order_information_available in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/joins/symmetric_hash_join.rs:339
AggregateExec::try_optimize_distinct_soft_limit in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/aggregates/mod.rs:1144
AggregateExec::with_new_aggr_exprs in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/aggregates/mod.rs:1169
CrossJoinExec::swap_inputs in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/joins/cross_join.rs:190
NestedLoopJoinExec::swap_inputs in file /home/runner/work/datafusion/datafusion/target/semver-checks/git-apache_main/0eb77530100399687f856d20ead4d21e95c75500/datafusion/physical-plan/src/joins/nested_loop_join.rs:479
--- failure struct_now_doc_hidden: pub struct is now #[doc(hidden)] ---
Description:
A pub struct is now #[doc(hidden)], removing it from the crate's public API.
ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/struct_now_doc_hidden.ron
Failed in:
struct HashExpr in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs:90
struct SeededRandomState in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/joins/hash_join/partitioned_hash_eval.rs:50
--- failure trait_now_doc_hidden: pub trait is now #[doc(hidden)] ---
Description:
A pub trait is now #[doc(hidden)], removing it from the crate's public API.
ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden
impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/trait_now_doc_hidden.ron
Failed in:
trait JoinHashMapType in file /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/joins/join_hash_map.rs:110
Summary semver requires new major version: 5 major and 0 minor checks failed
Finished [ 64.243s] datafusion-physical-plan
```
</details>
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#issuecomment-6092750572
@alamb Thank you for the review! Feedbacks addressed.
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 merged PR #25963:
URL: https://github.com/apache/datafusion/pull/25963
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#discussion_r4164812156
##########
datafusion/physical-plan/src/joins/hash_join/exec.rs:
##########
@@ -1408,6 +1408,13 @@ impl HashJoinExec {
/// physical optimizer rule to determine a good join order, which is
/// executed before the `EnforceDistribution` rule (the rule that may
/// insert `RepartitionExec` operators).
+ ///
+ /// # Public Only for Internal Use:
+ ///
+ /// This is not a public API and is for internal use only; see [API policy] for details.
+ ///
+ /// [API policy]: https://datafusion.apache.org/contributor-guide/api-health.html#internal-public-apis
+ #[doc(hidden)]
Review Comment:
This API seem like reasonable to be public, however now it requires cooperation from several other optimizer rules, to make it safe. The comments right above can demonstrate it is tricky to use.
Note downstreams can still have access to it, this marker is only a hint for (a) might change without often (b) tricky to use it correctly, as explained in the link
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#discussion_r4164812156
##########
datafusion/physical-plan/src/joins/hash_join/exec.rs:
##########
@@ -1408,6 +1408,13 @@ impl HashJoinExec {
/// physical optimizer rule to determine a good join order, which is
/// executed before the `EnforceDistribution` rule (the rule that may
/// insert `RepartitionExec` operators).
+ ///
+ /// # Public Only for Internal Use:
+ ///
+ /// This is not a public API and is for internal use only; see [API policy] for details.
+ ///
+ /// [API policy]: https://datafusion.apache.org/contributor-guide/api-health.html#internal-public-apis
+ #[doc(hidden)]
Review Comment:
This API seem like reasonable to be public, however now it requires cooperation from several other optimizer rules, to make it safe. The comments right above can demonstrate it is tricky to use.
Note downstreams can still have access to it, this marker is only a hint for (a) might change often (b) tricky to use it correctly, as explained in the link
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] chore: Hide internal public utility APIs [datafusion]
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #25963:
URL: https://github.com/apache/datafusion/pull/25963#issuecomment-5950481968
## [Codecov](https://app.codecov.io/gh/apache/datafusion/pull/25963?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 82.59%. Comparing base ([`e6dfef5`](https://app.codecov.io/gh/apache/datafusion/commit/e6dfef5fc808d9631aa8c464a9efbd0b664acf0a?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`be2d525`](https://app.codecov.io/gh/apache/datafusion/commit/be2d525e6434e4ce652bc5837fab9426db5a714c?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
:warning: Report is 2 commits behind head on main.
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## main #25963 +/- ##
========================================
Coverage 82.59% 82.59%
========================================
Files 1145 1145
Lines 443934 444096 +162
Branches 443934 444096 +162
========================================
+ Hits 366669 366804 +135
- Misses 55009 55023 +14
- Partials 22256 22269 +13
```
</details>
[:umbrella: View full report in Codecov by Harness](https://app.codecov.io/gh/apache/datafusion/pull/25963?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
<details><summary> :rocket: New features to boost your workflow: </summary>
- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
- :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
</details>
--
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: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org