emkornfield commented on code in PR #623: URL: https://github.com/apache/parquet-format/pull/623#discussion_r4483826582
########## src/main/thrift/ModularFooter.thrift: ########## @@ -0,0 +1,415 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +/** Modular footer supporting flexible data layouts and row-range statistics. + * + * C = physical columns; K_c = chunks in column c; K = sum(K_c). + * P_k = data pages in chunk k; P = sum(P_k); D = dictionaries; G = row groups. + * M = key/value pairs. K_c may vary, including zero, independently of G. + * Chunk membership alone does not determine row coverage. + * + * StreamLocation comments specify the scalar Parquet type, value count and + * nullability. Each stream is a primitive column with no LIST nesting. + * Field IDs define types; no stream schema is serialized. + * FileInfo.schema describes the source data. + * Thrift optional controls stream presence, not value nullability. + * Non-null streams: max RL=DL=0. Nullable streams: max RL=0, max DL=1 + * (DL=0: null; DL=1: present). No hierarchy repetition levels are stored. + * + * Chunk fields have K positions in column/chunk order; page fields have P + * positions in chunk/page order. Nulls keep their positions. Shared indexes + * address logical positions; metadata-page boundaries may differ by stream. + * These streams need not have equal row counts or form one Parquet row group. + * Validate counts, indexes and extents; authenticate/decrypt required streams + * before use. An unavailable index never means an empty hierarchy. + */ +include "parquet.thrift" +namespace cpp parquet.modular +namespace java org.apache.parquet.format.modular + +// Shared metadata structures. + +/** PageHeader/body pairs: [optional DICTIONARY_PAGE][DATA_PAGE_V2 ...]. + * Shared streams inherit root protection, including headers and dictionaries. + * Streams inside ColumnRowRangeStatistics are plaintext within its encrypted module. + */ +struct StreamLocation { + /** Absolute file offset; relative to page_streams inside a column module. */ + 1: required i64 offset; + + /** Stored bytes, including headers and protection. Signed streams append a + * 28-byte signature; encrypted streams add length4 + nonce12 + GCM-tag16. + * Column-module streams have no individual protection overhead. + */ + 2: required i64 length; + + /** Codec for dictionary bodies and V2 values when is_compressed is true. + * Levels are uncompressed. Compress before protection; independent of data codecs. + */ + 3: required parquet.CompressionCodec codec; +} + +/** Exclusive element ends, not byte offsets; non-negative signed i32 values. + * Omit only the fixed leading zero; retain genuine zero ends (empty lists). + * boundary(index,n) = 0 if n=0, else index[n-1], for 0<=n<=length. + */ +struct DataLayout { + /** INT32; number of values = C; nullability: non-null. + * C must match FileInfo.num_columns. Non-decreasing; last end is K + * (K=0 if C=0). Column c owns [boundary(index,c), index[c]) chunks. + */ + 1: required StreamLocation column_chunk_index; + + /** INT32; number of values = K; nullability: non-null. + * Non-decreasing; last end is P (P=0 if K=0). + * Chunk k owns [boundary(index,k), index[k]) pages. + * Required with PageMetadata; otherwise optional. If absent, use source + * page headers for grouping; absence does not imply P=0. + */ + 2: optional StreamLocation page_index; +} + +/** Dictionary IDs address table positions. */ +struct DictionaryMetadata { + /** INT64; number of values = D; nullability: non-null. D fits signed i32. + * Absolute dictionary-page offsets, including headers. Store each referenced + * dictionary once; no adjacency/order restriction. First-reference order is + * recommended. Both streams are empty when no dictionaries are used. + */ + 1: required StreamLocation offsets; + + /** INT64; number of values = D; nullability: non-null. + * Positive stored sizes, including headers. Dictionary d occupies + * [offsets[d], offsets[d]+lengths[d]), disjoint from data and other dictionaries. + */ + 2: required StreamLocation lengths; +} + +struct RowGroupMetadata { + /** INT64; number of values = G; nullability: non-null. + * Row counts in row-group order; sum equals FileInfo.num_rows. + */ + 1: required StreamLocation num_rows; + + /** INT64; number of values = G+1; nullability: non-null. + * Non-decreasing absolute byte boundaries; optional hint for contiguous + * row groups in file order. Omit if interleaving or shared dictionaries + * prevent complete extents. Chunk/dictionary locations remain independent. + */ + 2: optional StreamLocation offsets; +} + +/** Flat fields grouped by DataLayout.column_chunk_index. */ +struct ColumnChunkMetadata { + /** INT32; number of values = K; nullability: non-null. + * parquet.CompressionCodec values. + */ + 1: required StreamLocation codecs; + + /** INT32; number of values = K; nullability: nullable. + * Null means no dictionary; otherwise an ID in [0,D). Sharing is allowed + * only within one physical column, as determined by column_chunk_index. + * Every dictionary must be referenced and compatible with each referencing + * chunk, including its codec. + */ + 2: required StreamLocation dictionary_ids; + + /** BOOLEAN; number of values = K; nullability: non-null. + * True if all data pages use the chunk's dictionary; false without one. + */ + 3: required StreamLocation is_fully_dictionary_encoded; + + /** INT64; number of values = K; nullability: non-null. + * Page headers + uncompressed bodies, counting the dictionary once per + * referencing chunk, even if shared. Omission means unknown sizes. + */ + 4: optional StreamLocation total_uncompressed_sizes; + + /** INT64; number of values = K; nullability: non-null. + * Data-value counts including nulls; not row counts. Review Comment: there was a recent thread on the mailing list about clarifying this. I think one conclusion we should note is that this value is equal to the number of definition/repetition levels written for the chunk when they apply (and it is equal to row count if the column is not nested and non nullable). -- 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]
