etseidl commented on code in PR #588:
URL: https://github.com/apache/parquet-format/pull/588#discussion_r3453618949
##########
ParxMagicNumber.md:
##########
@@ -0,0 +1,89 @@
+# PARX Parquet Format Specification
+
+This specification details a new magic number and associated fixed length
footer metadata changes
+that accompany the footer.
+
+## Motivation
+
+Most parts of the parquet specification lend themselves naturally to
comptability checks
+when a new feature is added (e.g. encodings and compression values have an
enum value added)
+and fail appropriately.
+However, some semantic changes or footer changes are impossible to communicate
appropriately
+within existing structures (e.g. changing the serialization of the footer).
The motivation
+for the new magic number and layout is to accomodate the latter set of changes
by introducing
+a new extensible mechanism for readers to detect these changes and fail
accordingly.
+
+## Design Motivations
+
+* Provide a mechanism to only introduce a single new magic number for parquet
that can
+ last at least a decade.
+* Provide integrity checks for the footer.
+* Provide the ability for readers to have a granular understanding of
structural and semantic
+ backward incompatible features that are required to read a particular file.
+
+## File Layout
+
+A PARX file has the same overall structure as a standard Parquet file, with
two differences:
+the leading and trailing magic bytes are `PARX` instead of `PAR1/PARE`, and
the trailing footer is
+16 bytes instead of 8.
+
+The file layout is as follows:
+
+```
++-----------+-------------------+--------------------+-------------+
+| 'PARX' | File Data | Footer Metadata | Footer tail |
+| (4 bytes) | (variable length) | (variable length) | (16 bytes) |
++-----------+----------+--------+--------------------+-------------+
+```
+
+All multi-byte integer fields are **little-endian**.
+
+
+### PARX Footer Tail — 16 bytes
+
+```
++------------------+-----------+----------+--------+
+| metadata_len | flags | crc32 | 'PARX' |
++------------------+-----------+----------+--------+
+ offset 0 offset 4 offset 8 offset 12
+```
+
+| Field | Type | Offset | Description
|
+|----------------|---------|--------|-------------------------------------------------------------------|
+| `metadata_len` | i32 LE | 0 | Byte length of the Thrift-encoded
`FileMetaData` block |
+| `flags` | u32 LE | 4 | Feature flags (see [Feature
Flags](#feature-flags)) |
Review Comment:
I had the same thought, but I can also understand keeping this simple for
now, as I think the intent is to use this bitfield sparingly. Most changes will
be communicated with a major version bump, so it's only structural changes like
a new footer format that will require a new bit position. I think any new
footer we design should itself be extensible without requiring the use of
additional bits here. As to clean-ups of the existing thrift structure, perhaps
we should roll up the `path_in_schema` change with other changes that have been
suggested before (remove `encodings` from `ColumnMetaData`, remove
`file_offset` and `file_path` from `ColumnChunk`, I think @alkis had others).
If we are concerned about running out of bits, then we could instead say the
footer isn't fixed in size, and use continuation bits to make the bitfield
arbitrary in size. Or keep it fixed, and say bit 32 signifies an additional
bitfield located in a TBD location in the footer.
--
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]
