This is an automated email from the ASF dual-hosted git repository.
tustvold pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/master by this push:
new 28c1cae83f6 Fix documentation for parquet `parse_metadata`,
`decode_metadata` and `decode_footer` (#5781)
28c1cae83f6 is described below
commit 28c1cae83f6a10644a0b92e8b185587b0cd72f9f
Author: Andrew Lamb <[email protected]>
AuthorDate: Fri May 17 11:40:41 2024 -0400
Fix documentation for parquet `parse_metadata`, `decode_metadata` and
`decode_footer` (#5781)
---
parquet/src/file/footer.rs | 44 ++++++++++++++++++++++++++++++++++++++------
1 file changed, 38 insertions(+), 6 deletions(-)
diff --git a/parquet/src/file/footer.rs b/parquet/src/file/footer.rs
index 9695dbeae6e..7a75576c364 100644
--- a/parquet/src/file/footer.rs
+++ b/parquet/src/file/footer.rs
@@ -27,14 +27,30 @@ use crate::file::{metadata::*, reader::ChunkReader,
FOOTER_SIZE, PARQUET_MAGIC};
use crate::schema::types::{self, SchemaDescriptor};
-/// Layout of Parquet file
+/// Reads the [ParquetMetaData] from the footer of the parquet file.
+///
+/// # Layout of Parquet file
+/// ```text
/// +---------------------------+-----+---+
/// | Rest of file | B | A |
/// +---------------------------+-----+---+
-/// where A: parquet footer, B: parquet metadata.
+/// ```
+/// where
+/// * `A`: parquet footer which stores the length of the metadata.
+/// * `B`: parquet metadata.
+///
+/// # I/O
+///
+/// This method first reads the last 8 bytes of the file via
+/// [`ChunkReader::get_read`] to get the the parquet footer which contains the
+/// metadata length.
+///
+/// It then issues a second `get_read` to read the encoded metadata
+/// metadata.
///
-/// The reader first reads DEFAULT_FOOTER_SIZE bytes from the end of the file.
-/// If it is not enough according to the length indicated in the footer, it
reads more bytes.
+/// # See Also
+/// [`decode_metadata`] for decoding the metadata from the bytes.
+/// [`decode_footer`] for decoding the metadata length from the footer.
pub fn parse_metadata<R: ChunkReader>(chunk_reader: &R) ->
Result<ParquetMetaData> {
// check file is large enough to hold footer
let file_size = chunk_reader.len();
@@ -65,7 +81,13 @@ pub fn parse_metadata<R: ChunkReader>(chunk_reader: &R) ->
Result<ParquetMetaDat
decode_metadata(chunk_reader.get_bytes(start, metadata_len)?.as_ref())
}
-/// Decodes [`ParquetMetaData`] from the provided bytes
+/// Decodes [`ParquetMetaData`] from the provided bytes.
+///
+/// Typically this is used to decode the metadata from the end of a parquet
+/// file. The format of `buf` is the Thift compact binary protocol, as
specified
+/// by the [Parquet Spec].
+///
+/// [Parquet Spec]: https://github.com/apache/parquet-format#metadata
pub fn decode_metadata(buf: &[u8]) -> Result<ParquetMetaData> {
// TODO: row group filtering
let mut prot = TCompactSliceInputProtocol::new(buf);
@@ -90,7 +112,17 @@ pub fn decode_metadata(buf: &[u8]) ->
Result<ParquetMetaData> {
Ok(ParquetMetaData::new(file_metadata, row_groups))
}
-/// Decodes the footer returning the metadata length in bytes
+/// Decodes the Parquet footer returning the metadata length in bytes
+///
+/// A parquet footer is 8 bytes long and has the following layout:
+/// * 4 bytes for the metadata length
+/// * 4 bytes for the magic bytes 'PAR1'
+///
+/// ```text
+/// +-----+--------+
+/// | len | 'PAR1' |
+/// +-----+--------+
+/// ```
pub fn decode_footer(slice: &[u8; FOOTER_SIZE]) -> Result<usize> {
// check this is indeed a parquet file
if slice[4..] != PARQUET_MAGIC {
