PARQUET-2473: Clarify records can not be split across v2 pages or PageIndex

alamb commented 1 month ago

This was sparked by a mailing list discussion: https://lists.apache.org/thread/rd8twnvg4bg3558r507rzpxckcxt5wdn

Several implementors of the Parquet spec have been confused by this point

Notes

There seems to be clear consensus that record boundaries can't span pages in V2 pages or if there is a page index, so let's make that clear in the spec to avoid future confusion

There also seemed to be consensus that Row Groups must start on record boundaries, and that the existing spec language was clear on this point, so I did not propose any changes to that language

https://issues.apache.org/jira/browse/PARQUET-2473

Jira

[x] My PR addresses the following Parquet Jira issues and references them in the PR title. For example, "PARQUET-1234: My Parquet PR"
- https://issues.apache.org/jira/browse/PARQUET-2473
- In case you are adding a dependency, check if the license complies with the ASF 3rd Party License Policy.

Commits

[x] My commits all reference Jira issues in their subject lines. In addition, my commits follow the guidelines from "How to write a good git commit message":
1. Subject is separated from body by a blank line
2. Subject is limited to 50 characters (not including Jira issue reference)
3. Subject does not end with a period
4. Subject uses the imperative mood ("add", not "adding")
5. Body wraps at 72 characters
6. Body explains "what" and "why", not "how"

Documentation

This PR is only a clarification

[x] In case of new functionality, my PR adds documentation that describes how to use it.
- All the public functions and the classes in the PR contain Javadoc that explain what it does

alamb commented 1 month ago

Updated to clarify that records can't repeat when an OffsetIndex is present

alamb commented 1 month ago

I think this PR is now ready to go @wgtmac . Is there anything else we are waiting on?

alamb commented 1 month ago

Sorry for missing this. I'll merge it now.

No worries -- thank you!

I'll file a JIRA shortly to improve the spec to use row terminology

alamb commented 1 month ago

Update: here is a PR to consistently use the "row" terminology: https://github.com/apache/parquet-format/pull/256

apache / parquet-format