Architecture

Apache Arrow is organized as a monorepo containing a format specification, a C++ reference implementation, two sister C++ projects (Parquet and Gandiva), and several language bindings. This page explains how the components are layered and how data flows through them.

Layered architecture

graph TD
    subgraph L0["Layer 0 — Format specification"]
        FBS["FlatBuffers schemas (format/*.fbs)"]
        ProtoF["Flight.proto, FlightSql.proto"]
        Cdata["C data interface (cpp/src/arrow/c/abi.h)"]
    end

    subgraph L1["Layer 1 — C++ core"]
        Memory["Memory + buffers (cpp/src/arrow/buffer.h, memory_pool.h)"]
        Types["Types + arrays (cpp/src/arrow/array/, type.h)"]
        IO["I/O + filesystem (cpp/src/arrow/io/, filesystem/)"]
        Compute["Compute kernels (cpp/src/arrow/compute/)"]
        IPC["IPC reader/writer (cpp/src/arrow/ipc/)"]
    end

    subgraph L2["Layer 2 — Higher-level C++"]
        Acero["Acero streaming engine (cpp/src/arrow/acero/)"]
        Dataset["Dataset framework (cpp/src/arrow/dataset/)"]
        Flight["Flight RPC (cpp/src/arrow/flight/)"]
        Engine["Substrait engine (cpp/src/arrow/engine/)"]
    end

    subgraph L3["Layer 3 — Sister projects"]
        Parquet["Apache Parquet C++ (cpp/src/parquet/)"]
        Gandiva["Gandiva LLVM JIT (cpp/src/gandiva/)"]
    end

    subgraph L4["Layer 4 — Language wrappers"]
        PyArrow["PyArrow (python/pyarrow/)"]
        Rpkg["R arrow package (r/)"]
        CGlib["c_glib (C bindings via GObject)"]
        Ruby["Red Arrow (ruby/)"]
        Matlab["MATLAB bindings (matlab/)"]
    end

    L0 --> L1
    L1 --> L2
    L1 --> L3
    L2 --> L3
    L1 --> L4
    L2 --> L4
    L3 --> L4
    L4 --> Ruby
    CGlib --> Ruby

Each layer depends on the layers below it. The format specification is independent of any implementation; everything else depends on it.

Layer 0 — Format specification

The Arrow project starts as a specification, not a library. The binary contracts live in format/:

File	Defines
format/Schema.fbs	Logical and physical types, schemas, fields, field metadata
format/Message.fbs	The IPC envelope: schema, record batch, dictionary batch, tensor messages
format/File.fbs	The on-disk Arrow file format (footer, blocks)
format/Tensor.fbs	Dense tensor wire format
format/SparseTensor.fbs	Sparse tensor wire formats (COO, CSR, CSF)
format/Flight.proto	Arrow Flight RPC service over gRPC
format/FlightSql.proto	Flight SQL extension to Flight

The C data interface in cpp/src/arrow/c/abi.h is a separate ABI for in-process zero-copy data exchange between language runtimes that share the same address space. It is part of the format contract and is reused by every language implementation that wants to interoperate without copying data.

Sister-language implementations that live outside this repo — including Arrow Java, Arrow Rust, Arrow Go, and Arrow JavaScript — independently implement the same FlatBuffers schemas and verify compatibility through the integration test suite under cpp/src/arrow/integration/.

Layer 1 — C++ core

The C++ library is the single most important component in the repo. Source lives in cpp/src/arrow/ and is split into focused subsystems. The core of the core is:

• Memory. cpp/src/arrow/memory_pool.h defines MemoryPool (the allocator interface). cpp/src/arrow/buffer.h defines Buffer and MutableBuffer (reference-counted byte ranges). cpp/src/arrow/util/bit_util.h is the toolkit for bitmap manipulation.
• Types and arrays. cpp/src/arrow/type.h declares every Arrow type (primitive, list, struct, union, dictionary, run-end-encoded, extension). cpp/src/arrow/array/ holds the array hierarchy: array_base.h for the abstract Array and ArrayBuilder, array_primitive.h for fixed-width arrays, array_binary.h and array_nested.h for variable-width and nested arrays, plus dictionary, decimal, and run-end variants.
• Tabular containers. cpp/src/arrow/record_batch.h (a list of arrays with a schema), cpp/src/arrow/table.h (a list of chunked arrays — the column-major equivalent of a data frame), and cpp/src/arrow/chunked_array.h.
• I/O. cpp/src/arrow/io/interfaces.h defines abstract InputStream, OutputStream, RandomAccessFile. Concrete implementations: file.cc, memory.cc, compressed.cc, buffered.cc. The filesystem abstraction in cpp/src/arrow/filesystem/filesystem.h covers local files, S3 (s3fs.cc), GCS (gcsfs.cc), Azure (azurefs.cc), and HDFS (hdfs.cc).
• IPC. cpp/src/arrow/ipc/reader.h and writer.h serialize record batches to and from the IPC stream and file formats defined by the FlatBuffers schemas.
• Compute. cpp/src/arrow/compute/ contains a function registry, a kernel dispatcher, and the actual compute implementations under cpp/src/arrow/compute/kernels/.

See Arrays and types, I/O and filesystem, and Compute kernels for deep dives.

Layer 2 — Higher-level C++

These C++ subsystems compose the core into bigger building blocks.

• Acero (cpp/src/arrow/acero/) — a streaming, push-based query execution engine. It defines an ExecPlan of pluggable nodes (source, filter, project, hash join, asof join, hash aggregate, order by, sink, fetch, pivot longer, sorted merge, TPC-H generators). See Acero.
• Dataset framework (cpp/src/arrow/dataset/) — partitioned, multi-file datasets across local disk and remote object stores, with format adapters for Parquet, Arrow IPC, CSV, JSON, ORC. See Dataset.
• Flight RPC (cpp/src/arrow/flight/) — a high-throughput RPC framework over gRPC for moving Arrow record batches between processes, plus the Flight SQL extension. See Flight.
• Engine (cpp/src/arrow/engine/) — an adapter layer that consumes Substrait plans and lowers them to Acero ExecPlans. See Substrait.

Layer 3 — Sister projects

These projects live in this repo but are independent products with their own users, ABIs, and version cadences.

• Apache Parquet C++ (cpp/src/parquet/) — the C++ implementation of the Parquet columnar file format. It uses Arrow buffers and types, has its own column readers and writers, supports bloom filters, page indexes, modular encryption, and exposes both a Parquet-native API and an Arrow-friendly API in cpp/src/parquet/arrow/. See Parquet.
• Gandiva (cpp/src/gandiva/) — an LLVM-based expression compiler. Given an expression tree, Gandiva JIT-compiles native code that filters or projects record batches at runtime. See Gandiva.

Layer 4 — Language wrappers

The Python, R, Ruby, MATLAB, and C-GLib packages all bind to the same C++ library. They differ in idiom but converge on the same in-memory format.

• PyArrow (python/pyarrow/) — Cython bindings. The build produces a pyarrow Python package that wraps libarrow, libparquet, libgandiva, etc. The Cython surface in python/pyarrow/*.pyx mirrors the C++ API.
• R arrow (r/) — Rcpp + cpp11 bindings. The R package exposes R6 classes (Array, Table, Dataset, Schema) and a dplyr backend (r/R/dplyr-*.R) that translates dplyr verbs into Acero plans.
• C-GLib (c_glib/) — GObject-based C wrappers. They are the foundation for language bindings beyond C++ that prefer to use GObject introspection (Ruby, Lua, Vala). The arrow-glib library wraps libarrow; sibling projects wrap Parquet, Flight, Flight SQL, Gandiva, dataset, and CUDA.
• Red Arrow (ruby/) — Ruby gems on top of the C-GLib bindings. The directory layout mirrors C-GLib (red-arrow, red-parquet, red-arrow-flight, red-arrow-flight-sql, red-arrow-dataset, red-arrow-cuda, red-gandiva, red-arrow-format).
• MATLAB (matlab/) — MATLAB classes that call into the C++ library through MEX shims.

See Implementations for per-language deep dives.

Build system

The C++ library uses CMake (cpp/CMakeLists.txt) with optional Meson support (cpp/meson.build). Components are toggled by ARROW_* cmake options (ARROW_PARQUET, ARROW_FLIGHT, ARROW_GANDIVA, ARROW_DATASET, ARROW_S3, ...). PyArrow and R both build on top of libarrow; PyArrow uses scikit-build with Cython, and the R package uses tools/nixlibs.R and bootstrap.R to fetch and build the C++ library on systems that need it.

CI is GitHub Actions; per-component workflows live in .github/workflows/ (cpp.yml, python.yml, r.yml, ruby.yml, matlab.yml, integration.yml). The release pipeline lives in .github/workflows/release.yml, release_candidate.yml, and verify_rc.yml. See CI workflows.

Cross-cutting concerns

• Asynchronous execution. cpp/src/arrow/util/future.h, async_generator.h, thread_pool.h, and task_group.h form an async runtime that backs Acero, Dataset, and Flight. Threads are dispatched through Arrow's own thread pool (CPU pool + IO pool) rather than blocking inline.
• Status / Result. Errors flow through arrow::Status (cpp/src/arrow/status.h) and arrow::Result<T> (cpp/src/arrow/result.h). Macros like ARROW_RETURN_NOT_OK and ARROW_ASSIGN_OR_RAISE are used pervasively.
• Telemetry. OpenTelemetry hooks live in cpp/src/arrow/util/tracing*.h and cpp/src/arrow/telemetry/. Flight has its own tracing middleware in flight/server_tracing_middleware.cc.
• Vectorization. The library uses dynamic dispatch to pick the best SIMD code path at runtime: scalar, SSE4.2, AVX2, AVX-512, NEON, SVE. CPU detection lives in cpp/src/arrow/util/cpu_info.cc. Pre-generated bit-packing kernels under cpp/src/arrow/util/bpacking_* show the pattern.