Design Documents
Index of design documents and how to propose new ones
Design documents capture the motivation, technical approach, and trade-offs behind significant changes to Apache Pinot. They serve as a permanent record so that contributors and operators can understand why a feature works the way it does.
Purpose
Alignment -- A design doc lets the community review the approach before code is written, reducing rework.
Onboarding -- New contributors can read design docs to understand the reasoning behind major subsystems.
Auditability -- Design docs provide a historical record of architectural decisions.
When to write a design document
Write a design doc when your change involves any of the following:
A new major feature or subsystem (for example, a new index type, a new query engine phase, or a new ingestion path)
A significant change to an existing subsystem that alters its behavior or data format
A cross-component change that affects multiple Pinot services (controller, broker, server, minion)
A public API change that affects backward compatibility
Bug fixes, small enhancements, and documentation changes typically do not need a design doc.
How to propose a design document
Open a GitHub issue describing the problem and proposed solution at a high level. Label it with
design-docorPEP(Pinot Enhancement Proposal).Write the design doc in a Google Doc (or equivalent) and share it with the Pinot dev mailing list (
[email protected]). Include:Problem statement and motivation
Proposed design with diagrams where helpful
API or configuration changes
Alternatives considered
Rollout and backward-compatibility plan
Collect feedback from reviewers on the doc and the GitHub issue.
Update this page by adding a row to the index table below once the design is accepted.
Implement the feature following the Contribution Guidelines.
Design document index
In-repo design docs
API for programmatically building Pinot segments without a full batch ingestion job
2025
2024
2022
2021
2020
2019 and earlier
Last updated
Was this helpful?