You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@ozone.apache.org by "chihsuan (via GitHub)" <gi...@apache.org> on 2026/09/05 03:24:21 UTC
[PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
chihsuan opened a new pull request, #11204:
URL: https://github.com/apache/ozone/pull/11204
## What changes were proposed in this pull request?
This pull request documents the exact semantics of the optional `fileSize` filter on the Recon
`GET /api/v1/utilization/fileCount` endpoint.
The API documentation, Swagger specification, chatbot semantics guide, and LLM tool description now clarify that:
* `fileSize` is matched against the exact upper bound of a file-size histogram bin.
* It is not an arbitrary raw file size or a cumulative less-than-or-equal threshold.
* A positive value that is not a bin upper bound returns an empty result.
* The filter can be used independently or together with `volume` and/or `bucket`.
The misleading chatbot example "how many files are under 1MB" is replaced with an example that asks for the single
bin ending at 1 MiB.
This is a documentation follow-up to #11203, which fixes the endpoint scan path to apply `fileSize` independently of
the other filters. #11203 should be merged before this pull request so that the implementation and documented behavior
remain consistent.
## What is the link to the Apache JIRA
https://issues.apache.org/jira/browse/HDDS-16384
## How was this patch tested?
* `mvn -pl :ozone-recon -am install -DskipTests -DskipShade -DskipRecon -DskipDocs`
* `mvn -pl :ozone-recon test -Dtest=TestReconToolCatalogConsistency -DskipShade -DskipRecon -DskipDocs`
* `./hadoop-ozone/dev-support/checks/checkstyle.sh`
* Parsed `recon-api.yaml` with Ruby's YAML parser.
* `git diff --check`
Generated-by: Codex (GPT-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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #11204:
URL: https://github.com/apache/ozone/pull/11204#discussion_r3939297852
##########
hadoop-hdds/docs/content/interface/ReconApi.md:
##########
@@ -1397,12 +1397,15 @@ Returns the status of all the Recon tasks.
* fileSize (optional)
- Filters the results based on the given fileSize.
+ Filters the results by the exact upper bound of a file-size histogram bin, in bytes. It is not an arbitrary file
+ size or a cumulative less-than-or-equal threshold. A positive value that is not a bin upper bound returns an empty
+ result. This filter can be used independently or together with volume and/or bucket.
Review Comment:
The docs now state that `fileSize` can be used independently of `volume`/`bucket`, but the current implementation only applies the `fileSize > 0` lookup path when *both* `volume` and `bucket` are provided; otherwise `fileSize` is ignored during the scan. If this PR is merged without the implementation change from #11203, the published API docs will be incorrect.
##########
hadoop-hdds/docs/content/interface/ReconApi.zh.md:
##########
@@ -964,11 +964,13 @@ Recon跟踪所有大小从`1 KB`到`1 PB`的键。对于小于`1 KB`的键，映
根据给定的桶名过滤结果。
* fileSize (可选)
- 根据给定的文件大小筛选结果。
+ 根据文件大小直方图分桶的上界精确筛选结果，单位为字节。该值不是任意文件大小，也不是小于或等于该值的
+ 累计阈值。正数值如果不等于分桶上界，将回传空结果。该筛选条件可以单独使用，也可以与卷和/或桶一起使用。
Review Comment:
The `fileSize` parameter bullet is missing the blank line used by the surrounding parameter list items (e.g., `volume`, `bucket`). Adding the blank line keeps the Markdown list formatting consistent and avoids rendering differences.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
Posted by "chihsuan (via GitHub)" <gi...@apache.org>.
chihsuan commented on code in PR #11204:
URL: https://github.com/apache/ozone/pull/11204#discussion_r3995095543
##########
hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml:
##########
@@ -1081,7 +1081,11 @@ paths:
- name: fileSize
in: query
description: |
- Filters the results based on the given file size.<br>
+ Filters the results by the exact upper bound of a file-size histogram bin, in bytes.<br>
Review Comment:
Thanks for the pointer @sravani-revuri I'll open a follow-up PR in ozone-site to mirror this into static/recon-api.yaml, and link it here once it's up.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
Posted by "sravani-revuri (via GitHub)" <gi...@apache.org>.
sravani-revuri commented on code in PR #11204:
URL: https://github.com/apache/ozone/pull/11204#discussion_r3986450027
##########
hadoop-hdds/docs/themes/ozonedoc/static/swagger-resources/recon-api.yaml:
##########
@@ -1081,7 +1081,11 @@ paths:
- name: fileSize
in: query
description: |
- Filters the results based on the given file size.<br>
+ Filters the results by the exact upper bound of a file-size histogram bin, in bytes.<br>
Review Comment:
Thanks @chihsuan for the change ! doc changes are supposed to go into ozone-site also. Could you please mirror these changes there? maybe in [recon-api.yaml](https://github.com/apache/ozone-site/blob/master/static/recon-api.yaml) ?
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
Posted by "chihsuan (via GitHub)" <gi...@apache.org>.
chihsuan commented on PR #11204:
URL: https://github.com/apache/ozone/pull/11204#issuecomment-6142357905
Thanks for the review! @sravani-revuri @F64116045
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-16384. Document Recon fileSize bin semantics [ozone]
Posted by "chihsuan (via GitHub)" <gi...@apache.org>.
chihsuan merged PR #11204:
URL: https://github.com/apache/ozone/pull/11204
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org