# apache/parquet-format architecture

> Architecture diagram of the GitHub repository apache/parquet-format, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/parquet-format
- Repository: https://github.com/apache/parquet-format

## Overview

This repository defines the Parquet file format and its Thrift metadata structures; it is a specification, not a reader/writer implementation. The documented workflow is that writers place column data before file metadata, while readers inspect metadata to locate and sequentially read selected column chunks. The graph includes documented format extensions and representations. Source excerpts were unavailable, so relationships are limited to those stated in the README.

Main entry points: [`README.md`](https://github.com/apache/parquet-format/blob/master/README.md) (File layout), [`src/main/thrift/parquet.thrift`](https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift) (Thrift metadata), [`LogicalTypes.md`](https://github.com/apache/parquet-format/blob/master/LogicalTypes.md) (Logical types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_layout["File Structure"]
  node_file_layout["File layout<br/>[README.md]"]
  node_metadata["Thrift metadata<br/>[parquet.thrift]"]
  node_hierarchy["Row groups and pages<br/>[README.md]"]
end

subgraph group_types["Data Representation"]
  node_primitive_types["Primitive types<br/>[README.md]"]
  node_logical_types["Logical types<br/>[LogicalTypes.md]"]
  node_nested_encoding["Nested encoding<br/>[README.md]"]
end

subgraph group_features["Format Capabilities"]
  node_encodings["Encodings<br/>[Encodings.md]"]
  node_compression["Compression<br/>[Compression.md]"]
  node_encryption["Encryption<br/>[Encryption.md]"]
  node_bloom_filter["Bloom filter<br/>[BloomFilter.md]"]
  node_page_index["Page index<br/>[PageIndex.md]"]
  node_variant["Variant encoding<br/>[VariantEncoding.md]"]
  node_variant_shredding["Variant shredding"]
  node_geospatial["Geospatial types<br/>[Geospatial.md]"]
  node_alp["ALP encoding<br/>[AlpEncoding.md]"]
  node_binary_extensions["Binary extensions"]
end

node_writers(("Format writers"))
node_readers(("Format readers"))

node_writers -->|"write format"| node_file_layout
node_file_layout -->|"defines metadata"| node_metadata
node_file_layout -->|"organizes data"| node_hierarchy
node_readers -->|"read first"| node_metadata
node_readers -->|"locate chunks"| node_file_layout
node_logical_types -->|"annotate types"| node_primitive_types
node_nested_encoding -->|"encode nesting"| node_hierarchy

click node_file_layout "https://github.com/apache/parquet-format/blob/master/README.md"
click node_metadata "https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift"
click node_hierarchy "https://github.com/apache/parquet-format/blob/master/README.md"
click node_primitive_types "https://github.com/apache/parquet-format/blob/master/README.md"
click node_logical_types "https://github.com/apache/parquet-format/blob/master/LogicalTypes.md"
click node_nested_encoding "https://github.com/apache/parquet-format/blob/master/README.md"
click node_encodings "https://github.com/apache/parquet-format/blob/master/Encodings.md"
click node_compression "https://github.com/apache/parquet-format/blob/master/Compression.md"
click node_encryption "https://github.com/apache/parquet-format/blob/master/Encryption.md"
click node_bloom_filter "https://github.com/apache/parquet-format/blob/master/BloomFilter.md"
click node_page_index "https://github.com/apache/parquet-format/blob/master/PageIndex.md"
click node_variant "https://github.com/apache/parquet-format/blob/master/VariantEncoding.md"
click node_variant_shredding "https://github.com/apache/parquet-format/blob/master/VariantShredding.md"
click node_geospatial "https://github.com/apache/parquet-format/blob/master/Geospatial.md"
click node_alp "https://github.com/apache/parquet-format/blob/master/AlpEncoding.md"
click node_binary_extensions "https://github.com/apache/parquet-format/blob/master/BinaryProtocolExtensions.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_file_layout,node_metadata,node_hierarchy toneBlue
class node_primitive_types,node_logical_types,node_nested_encoding toneAmber
class node_encodings,node_compression,node_encryption,node_bloom_filter,node_page_index,node_variant,node_variant_shredding,node_geospatial,node_alp,node_binary_extensions toneMint
class node_writers,node_readers toneIndigo
```

## Components

### File Structure

- [File layout](https://github.com/apache/parquet-format/blob/master/README.md): `README.md`
- [Thrift metadata](https://github.com/apache/parquet-format/blob/master/src/main/thrift/parquet.thrift): `src/main/thrift/parquet.thrift`
- [Row groups and pages](https://github.com/apache/parquet-format/blob/master/README.md): `README.md`

### Data Representation

- [Primitive types](https://github.com/apache/parquet-format/blob/master/README.md): `README.md`
- [Logical types](https://github.com/apache/parquet-format/blob/master/LogicalTypes.md): `LogicalTypes.md`
- [Nested encoding](https://github.com/apache/parquet-format/blob/master/README.md): `README.md`

### Format Capabilities

- [Encodings](https://github.com/apache/parquet-format/blob/master/Encodings.md): `Encodings.md`
- [Compression](https://github.com/apache/parquet-format/blob/master/Compression.md): `Compression.md`
- [Encryption](https://github.com/apache/parquet-format/blob/master/Encryption.md): `Encryption.md`
- [Bloom filter](https://github.com/apache/parquet-format/blob/master/BloomFilter.md): `BloomFilter.md`
- [Page index](https://github.com/apache/parquet-format/blob/master/PageIndex.md): `PageIndex.md`
- [Variant encoding](https://github.com/apache/parquet-format/blob/master/VariantEncoding.md): `VariantEncoding.md`
- [Variant shredding](https://github.com/apache/parquet-format/blob/master/VariantShredding.md): `VariantShredding.md`
- [Geospatial types](https://github.com/apache/parquet-format/blob/master/Geospatial.md): `Geospatial.md`
- [ALP encoding](https://github.com/apache/parquet-format/blob/master/AlpEncoding.md): `AlpEncoding.md`
- [Binary extensions](https://github.com/apache/parquet-format/blob/master/BinaryProtocolExtensions.md): `BinaryProtocolExtensions.md`

### Other components

- **Format writers**
- **Format readers**

## Connections

- Format writers → File layout: write format (evidence: `README.md`)
- File layout → Thrift metadata: defines metadata (evidence: `README.md`)
- File layout → Row groups and pages: organizes data (evidence: `README.md`)
- Format readers → Thrift metadata: read first (evidence: `README.md`)
- Format readers → File layout: locate chunks (evidence: `README.md`)
- Logical types → Primitive types: annotate types (evidence: `README.md`)
- Nested encoding → Row groups and pages: encode nesting (evidence: `README.md`)
