Apache Pinot is a real-time distributed OLAP datastore for low-latency analytics over streaming and batch data. Core runtime roles: broker (query routing), server (segment storage/execution), controller (cluster metadata/management), minion (async tasks).

When locating a plugin implementation, consult kb/plugin-modules.md.

Use AGENTS.md for the build JDK, artifact bytecode targets, and scoped build/test commands. Use kb/skills/run-test.md for targeted tests and kb/skills/quickstart.md to start and verify a local cluster.

• Run ./mvnw spotless:apply to auto-format code.
• Run ./mvnw checkstyle:check to validate style. Checkstyle config is in config/checkstyle.xml.
• Run ./mvnw license:format to add license headers to new files.
• Run ./mvnw license:check to validate license headers.
• Always use the Maven wrapper (./mvnw) rather than a system mvn.

• Add class-level Javadoc for new classes; describe behavior and thread-safety.
• Use Javadoc syntax supported by the owning module's configured source release; see AGENTS.md.
• Keep Apache 2.0 license headers on all new source files.
• Preserve backward compatibility across mixed-version broker/server/controller.
• Prefer imports over fully qualified class names (e.g., use import com.foo.Bar and refer to Bar, not com.foo.Bar inline).
• Prefer List.of(), Set.of(), and Map.of() for non-null immutable collection literals. Checkstyle blocks Collections.emptyList(), Collections.emptySet(), and Collections.emptyMap(); use List.of(), Set.of(), and Map.of() instead. Do not add blanket bans for Collections.singleton*; use them only when an element/key/value argument is intentionally null because List.of(null), Set.of(null), and Map.of(...) with null keys or values throw NullPointerException. Before replacing empty collection factories, check whether the value flows to mutating callers. See kb/code-review-principles.md C7.12.
• Prefer targeted unit tests; use integration tests when behavior crosses roles.
• Avoid deprecated APIs in new code. If you must reference one (e.g., for backward-compat serialization or to test the deprecated path), justify it with a comment.

• Do not include Co-authored-by trailers that reference AI tools (e.g., Claude, Copilot).
  • Why: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.
  • Fix: Omit the Co-authored-by line entirely when committing.

Before pushing, follow kb/skills/precommit.md for affected-module formatting, license headers, checkstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when compiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing. Claude Code users can invoke /precommit.

• Query changes often touch broker planning and server execution; verify both.
• Segment/index changes usually live under pinot-segment-local and pinot-segment-spi.
• Config or API changes should update relevant configs and docs where applicable.

Review the changed behavior and relevant contracts before declaring implementation complete. Follow kb/agents/code-reviewer.md for requested full reviews and changes that benefit from independent domain review, especially compatibility, concurrency, security, and distributed state changes. Small changes can be reviewed directly. Reuse review evidence while the relevant diff and assumptions remain unchanged. Fix confirmed CRITICAL findings before proceeding; address MAJOR findings or explain why they can be deferred.

• This is a large multi-module Maven project. Building the entire project takes a long time — prefer building only the modules you need with -pl <module> -am.
• When running tests, use -Dtest=ClassName to run a specific test class rather than the full suite.
• Mixed-version compatibility matters — do not break wire protocols or serialization formats without careful consideration.