{"owner":"apache","repo":"pinot","hasSkills":true,"totalSkillsCount":6,"totalTokensCount":6033,"categories":["claude-rule","root-instruction","copilot-instructions","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"pinot":{"command":"npx","args":["-y","@modelcontextprotocol/server-pinot"]}}},"found":["CLAUDE.md","AGENTS.md",".github/copilot-instructions.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"CLAUDE.md":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# CLAUDE.md - Apache Pinot\n\n## What is this project?\nApache 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).\n\n## Repository layout\n| Directory | Purpose |\n|---|---|\n| `pinot-broker` | Broker query planning and scatter-gather |\n| `pinot-controller` | Controller APIs, table/segment metadata, Helix management |\n| `pinot-server` | Server query execution, segment loading, indexing |\n| `pinot-minion` | Background tasks (segment conversion, purge, etc.) |\n| `pinot-common` / `pinot-spi` | Shared utils, config, and SPI interfaces |\n| `pinot-segment-local` / `pinot-segment-spi` | Segment generation, indexes, storage |\n| `pinot-query-planner` / `pinot-query-runtime` | Multi-stage query engine (MSQE) |\n| `pinot-connectors` | External tooling to connect to Pinot |\n| `pinot-plugins` | All Pinot plugins (input formats, filesystems, stream/batch ingestion, metrics, etc.) |\n| `pinot-tools` | CLI and quickstart scripts |\n| `pinot-integration-tests` | End-to-end validation suites |\n| `pinot-distribution` | Packaging artifacts |\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build commands\nUse [AGENTS.md](AGENTS.md#build-and-test) for the build JDK, artifact bytecode targets, and scoped build/test commands.\nUse [kb/skills/run-test.md](kb/skills/run-test.md) for targeted tests and\n[kb/skills/quickstart.md](kb/skills/quickstart.md) to start and verify a local cluster.\n\n## Code style and formatting\n- Run `./mvnw spotless:apply` to auto-format code.\n- Run `./mvnw checkstyle:check` to validate style. Checkstyle config is in `config/checkstyle.xml`.\n- Run `./mvnw license:format` to add license headers to new files.\n- Run `./mvnw license:check` to validate license headers.\n- Always use the Maven wrapper (`./mvnw`) rather than a system `mvn`.\n\n## Coding conventions\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc syntax supported by the owning module's configured source release; see [AGENTS.md](AGENTS.md#coding-conventions-and-hygiene).\n- Keep Apache 2.0 license headers on all new source files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n- 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.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\nClaude Code users can invoke `/precommit`.\n\n## Change guidance\n- **Query changes** often touch broker planning and server execution; verify both.\n- **Segment/index changes** usually live under `pinot-segment-local` and `pinot-segment-spi`.\n- **Config or API changes** should update relevant configs and docs where applicable.\n\n## Code review\n\nReview the changed behavior and relevant contracts before declaring implementation complete. Follow\n[kb/agents/code-reviewer.md](kb/agents/code-reviewer.md) for requested full reviews and changes that benefit from independent\ndomain review, especially compatibility, concurrency, security, and distributed state changes. Small changes can be\nreviewed directly. Reuse review evidence while the relevant diff and assumptions remain unchanged.\nFix confirmed CRITICAL findings before proceeding; address MAJOR findings or explain why they can be deferred.\n\n## Common gotchas\n- 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`.\n- When running tests, use `-Dtest=ClassName` to run a specific test class rather than the full suite.\n- Mixed-version compatibility matters — do not break wire protocols or serialization formats without careful consideration.\n","AGENTS.md":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# Apache Pinot - AGENTS Guide\n\nThis file provides quick, practical guidance for coding agents working in this\nrepo. It is intentionally short and focused on day-to-day work.\n\n## Project overview\n- Apache Pinot is a real-time distributed OLAP datastore for low-latency\n  analytics over streaming and batch data.\n- Core runtime roles: broker (query routing), server (segment storage/execution),\n  controller (cluster metadata/management), minion (async tasks).\n\n## Repository layout (high level)\n- pinot-broker: broker query planning and scatter-gather.\n- pinot-controller: controller APIs, table/segment metadata, Helix management.\n- pinot-server: server query execution, segment loading, indexing.\n- pinot-minion: background tasks (segment conversion, purge, etc).\n- pinot-common / pinot-spi: shared utils, config, and SPI interfaces.\n- pinot-segment-local / pinot-segment-spi: segment generation, indexes, storage.\n- pinot-query-planner / pinot-query-runtime: multi-stage query (MSQ) engine.\n- pinot-connectors: external tooling to connect to Pinot\n- pinot-plugins: all pinot plugins.\n- pinot-tools: CLI and quickstart scripts.\n- pinot-integration-tests: end-to-end validation suites.\n- pinot-distribution: packaging artifacts.\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build and test\n- Build JDK: Use JDK 25+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.\n- Runtime JRE: Broker/server/controller/minion run on Java 25+.\n- Default to affected modules and their dependencies: `./mvnw -pl <module> -am test`.\n- Faster module build: `./mvnw -pl <module> -am verify -Ppinot-fastdev`. This profile skips style and license checks;\n  it does not replace applicable pre-push validation.\n- Single test example: `./mvnw -pl pinot-segment-local -am -Dtest=RangeIndexTest -Dsurefire.failIfNoSpecifiedTests=false test`.\n  See [kb/skills/run-test.md](kb/skills/run-test.md) for dependency availability and evidence reuse.\n- Full reactor build, when the task requires it: `./mvnw clean install`.\n- Full binary/shaded distribution, when required: `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`.\n- Local cluster startup: follow [kb/skills/quickstart.md](kb/skills/quickstart.md) for the smallest required build and readiness checks.\n\n## Integration tests\n- Single integration test example: `./mvnw -pl pinot-integration-tests -am -Dtest=OfflineClusterIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false test`\n\n## Coding conventions and hygiene\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 25 by default.\n- Keep license headers on all new source files.\n- Use `./mvnw license:format` to add headers to new files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- In tests, statically import methods from `Assert` and `Mockito`; do not qualify calls with `Assert.` or `Mockito.`.\n- Import `FieldSpec.DataType` and `DataSchema.ColumnDataType` directly and use their simple names at call sites.\n- Keep a ternary expression on one line when it fits. Otherwise, put `? <true-expression>` and\n  `: <false-expression>` on separate lines.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Checkstyle config\n- Checkstyle rules and related config files live under `config/`.\n- Use the Maven wrapper (`./mvnw` on Unix-like systems or `mvnw.cmd` on Windows) to run `spotless:apply` to format code and `checkstyle:check` to validate style.\n- Run `./mvnw license:check` to validate license headers.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\n\n## Change guidance\n- Query changes often touch broker planning and server execution; verify both.\n- Segment/index changes usually live under `pinot-segment-local` and\n  `pinot-segment-spi`.\n- Config or API changes should update relevant configs and docs where applicable.\n\n## Reference docs\n- `README.md` for build and quickstart details.\n- `CONTRIBUTING.md` for style, licensing, and contribution guidance.\n\n## Knowledge base (tool-neutral)\nThe `kb/` directory holds AI-optimized procedures and reference material that any\ncoding agent (Claude Code, Copilot, Cursor, GPT, Qwen, Gemini, etc.) can read.\nClaude Code's `.claude/skills/<name>/SKILL.md` and `.claude/agents/<name>.md`\nfiles are thin pointers that delegate to the kb/ procedures — non-Claude agents\nshould read kb/ directly.\n\n- `kb/skills/` — operational procedures and review checklists. See\n  [`kb/skills/README.md`](kb/skills/README.md) for the index. Each file is\n  self-contained; read it and follow it when your task matches the skill name.\n  - Operations: `precommit`, `run-test`, `quickstart`, `bench-compare`,\n    `flaky-analyze`.\n  - Review (eight domains, one per file): `review-config-backcompat`,\n    `review-concurrency-state`, `review-architecture`, `review-performance`,\n    `review-correctness-nulls`, `review-testing`, `review-naming-api`,\n    `review-process-scope`.\n- `kb/agents/code-reviewer.md` — review procedure that selects relevant domains,\n  delegates substantial independent checks, and verifies consolidated findings.\n- `kb/code-review-principles.md` — Pinot-specific review principles cited by id\n  (e.g. `C2.4`, `C6.1`) from the review skills.\n- `kb/claude.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).\n\n**For non-Claude agents:** when a task matches a skill name (e.g. user asks for\na pre-commit check, a benchmark comparison, a flaky-test investigation, or a\ncode review), read the corresponding `kb/skills/<name>.md` and follow its\nprocedure. For a full code review, follow `kb/agents/code-reviewer.md` and cover\nthe domains relevant to the diff; small changes can be reviewed directly.\n",".github/copilot-instructions.md":"# Project overview\nOriginally developed at LinkedIn, Apache PinotTM is a real-time distributed OLAP datastore,\npurpose-built to provide ultra low-latency analytics at extremely high throughput.\n\nWith its distributed architecture and columnar storage, Apache Pinot empowers businesses to gain valuable insights from\nreal-time data, supporting data-driven decision-making and applications.\n\nThis document guides AI coding assistants (Copilot, Cursor, etc.) contributing to this repository.\n\n## Libraries and Frameworks\n\n- Most source code is written in Java 21. `pinot-spi`, `pinot-segment-spi`, `pinot-timeseries-spi`, `pinot-common`, `pinot-java-client`, and `pinot-jdbc-client` target Java 11 bytecode for external consumers.\n- Pinot UI is a React.js frontend. It is stored in `pinot-controller/src/main/resources/`.\n- The code is compiled with Maven and follows a multimodule structure. Use each module's `pom.xml` to\n  understand dependencies and configurations.\n\n## Coding Standards\n\n- Include the Apache Software Foundation (ASF) license header in all supported file types (Java, XML, JSON, Markdown).\n- Javadoc comments can either be written using the `/** ... */` syntax or the `///` syntax,\n  as specified in [JEP-467](https://openjdk.org/jeps/467).\n- Methods and parameters are non-null by default unless annotated with `javax.annotation.Nullable`.\n- Prefer explicit imports for classes rather than fully qualified names used inline.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Use SLF4J for logging; do not use `System.out` or `System.err`.\n- Propagate exceptions with useful context; avoid blanket `catch (Exception)` and never swallow errors.\n- Keep diffs minimal: do not reformat unrelated code and preserve existing whitespace/indentation styles.\n- Favor early returns and guard clauses; avoid deep nesting beyond two to three levels.\n- Add concise comments that explain \"why\", not \"how\"; avoid TODOs—implement instead.\n\n## Repository and Workflow Conventions\n\n- Use SSH Git remotes (`git@github.com:...`) rather than HTTPS.\n- Keep changes small and focused; include or update tests when behavior changes.\n- Write descriptive commit messages and PR descriptions; link related issues when relevant.\n- Prefer absolute file paths in discussions and tool calls for clarity.\n- Do not commit generated files, large binaries, or secrets.\n\n## Build and Test\n\n- Build with Maven from the repository root.\n- Run unit tests locally before opening a PR; ensure the project compiles cleanly without introducing lint errors.\n- Respect the multi-module structure; build order is governed by Maven.\n\n## Domain-specific conventions\n\n- Timezones: When defining or updating `STANDARD_TIMEZONES`, use a three-letter timezone ID with location in the\n  format `PDT(America/Los_Angeles)`. Prefer specific timezone IDs over generic UTC offsets, ensure comprehensive\n  coverage of common timezones, and sort entries by UTC offset.\n- Imports: Favor importing classes at the top of files instead of using fully qualified class names inline.\n\n## Testing Best Practices\n\n- Write unit tests for new functionality and bug fixes; follow the existing test naming conventions.\n- Use Mockito for mocking dependencies in unit tests.\n- Include integration tests when modifying core components or data flows.\n- Add performance tests for optimization changes; measure impact with realistic data volumes.\n- Use `@Test(expected = Exception.class)` sparingly; prefer `@Test` with try-catch for specific assertions.\n- Keep test methods focused and descriptive; avoid overly complex test setups.\n\n## Test Coverage Guidelines\n\n- Aim for high branch coverage (≥80%) on new code and modified code paths.\n- Focus on testing business logic rather than trivial getters/setters or framework boilerplate.\n- Prioritize coverage of error handling paths, edge cases, and boundary conditions.\n- Use JaCoCo or similar tools for measuring coverage; include coverage reports in CI builds.\n- Don't artificially inflate coverage with trivial tests; quality matters more than quantity.\n- Cover both happy path and failure scenarios, including timeout and resource exhaustion cases.\n- For critical components (e.g., query execution, data ingestion), maintain ≥90% coverage.\n- Document coverage expectations in PR descriptions when coverage goals aren't met.\n- Use mutation testing (e.g., PITest) for critical code to ensure test quality.\n- Exclude generated code, test utilities, and simple data transfer objects from coverage requirements.\n\n## Performance Considerations\n\n- Be mindful of memory usage in data processing pipelines; avoid loading large datasets into memory unnecessarily.\n- Use efficient data structures (e.g., primitive arrays over collections for numerical data).\n- Consider lazy evaluation for expensive operations that might not always be needed.\n- Profile performance-critical code paths and document assumptions about data scale.\n- Use appropriate collection types based on access patterns (e.g., ArrayList for iteration, HashMap for lookups).\n\n## Security Guidelines\n\n- Never log sensitive information like passwords, API keys, or personally identifiable data.\n- Validate all user inputs and external data sources; sanitize inputs to prevent injection attacks.\n- Use parameterized queries for database operations to prevent SQL injection.\n- Implement proper authentication and authorization checks for sensitive operations.\n- Follow the principle of least privilege when granting permissions.\n\n## Error Handling and Logging\n\n- Use appropriate log levels: ERROR for failures, WARN for concerning situations, INFO for important events, DEBUG for detailed troubleshooting.\n- Include relevant context in log messages (e.g., request IDs, user context, operation parameters).\n- Use structured logging with key-value pairs for better searchability and analysis.\n- Create custom exception types for domain-specific errors rather than generic RuntimeException.\n- Include stack traces only in DEBUG level; avoid in production logs to prevent information leakage.\n\n## Concurrency and Threading\n\n- Use thread-safe data structures (e.g., ConcurrentHashMap) in multi-threaded contexts.\n- Prefer immutable objects for shared state to avoid race conditions.\n- Use appropriate synchronization mechanisms; favor higher-level constructs over synchronized blocks.\n- Document thread safety guarantees in class-level Javadoc.\n- Be aware of Pinot's distributed nature; consider consistency models and eventual consistency scenarios.\n\n## Configuration Management\n\n- Externalize configuration values; avoid hardcoding environment-specific settings.\n- Use meaningful default values with clear documentation about their impact.\n- Validate configuration at startup and provide helpful error messages for invalid settings.\n- Document all configuration properties in code comments or separate configuration docs.\n- Use consistent naming conventions for configuration keys (e.g., pinot.server.port).\n\n## Documentation Standards\n\n- Document public APIs with comprehensive Javadoc including parameter descriptions, return values, and exceptions.\n- Include code examples in documentation where helpful for complex APIs.\n- Update documentation when changing behavior; keep README files current.\n- Use consistent terminology across documentation and code comments.\n- Document performance characteristics and limitations for important components.\n\n## Code Review Process\n\n- Address all review comments thoughtfully; if you disagree, explain your reasoning clearly.\n- Keep PRs focused on a single concern; split large changes into smaller, reviewable commits.\n- Include context in PR descriptions: what problem you're solving, how you solved it, and any trade-offs.\n- Test your changes thoroughly before requesting review; include test results when relevant.\n- Be responsive to feedback and iterate quickly on requested changes.\n\n## Assistant guidance\n\n- When editing, touch only what is necessary; keep changes minimal and localized.\n- Preserve the file's existing indentation and whitespace; do not reflow or reformat unrelated code.\n- When creating new files, include the ASF license header and all required imports/dependencies.\n- Avoid adding extremely long hashes or non-textual content; keep repository contents textual and reviewable.\n- If uncertain about where a change belongs, search for similar code in the codebase and follow established patterns.\n- Use absolute file paths in discussions and tool calls for clarity.\n- Prefer early returns and guard clauses to reduce nesting and improve readability.\n- When implementing complex logic, break it into smaller, well-named methods.\n- Consider edge cases and failure scenarios in your implementations.\n- Follow the existing code patterns and architectural decisions in the codebase.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/plugin.json)"},"files":{"CLAUDE.md":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# CLAUDE.md - Apache Pinot\n\n## What is this project?\nApache 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).\n\n## Repository layout\n| Directory | Purpose |\n|---|---|\n| `pinot-broker` | Broker query planning and scatter-gather |\n| `pinot-controller` | Controller APIs, table/segment metadata, Helix management |\n| `pinot-server` | Server query execution, segment loading, indexing |\n| `pinot-minion` | Background tasks (segment conversion, purge, etc.) |\n| `pinot-common` / `pinot-spi` | Shared utils, config, and SPI interfaces |\n| `pinot-segment-local` / `pinot-segment-spi` | Segment generation, indexes, storage |\n| `pinot-query-planner` / `pinot-query-runtime` | Multi-stage query engine (MSQE) |\n| `pinot-connectors` | External tooling to connect to Pinot |\n| `pinot-plugins` | All Pinot plugins (input formats, filesystems, stream/batch ingestion, metrics, etc.) |\n| `pinot-tools` | CLI and quickstart scripts |\n| `pinot-integration-tests` | End-to-end validation suites |\n| `pinot-distribution` | Packaging artifacts |\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build commands\nUse [AGENTS.md](AGENTS.md#build-and-test) for the build JDK, artifact bytecode targets, and scoped build/test commands.\nUse [kb/skills/run-test.md](kb/skills/run-test.md) for targeted tests and\n[kb/skills/quickstart.md](kb/skills/quickstart.md) to start and verify a local cluster.\n\n## Code style and formatting\n- Run `./mvnw spotless:apply` to auto-format code.\n- Run `./mvnw checkstyle:check` to validate style. Checkstyle config is in `config/checkstyle.xml`.\n- Run `./mvnw license:format` to add license headers to new files.\n- Run `./mvnw license:check` to validate license headers.\n- Always use the Maven wrapper (`./mvnw`) rather than a system `mvn`.\n\n## Coding conventions\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc syntax supported by the owning module's configured source release; see [AGENTS.md](AGENTS.md#coding-conventions-and-hygiene).\n- Keep Apache 2.0 license headers on all new source files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n- 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.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\nClaude Code users can invoke `/precommit`.\n\n## Change guidance\n- **Query changes** often touch broker planning and server execution; verify both.\n- **Segment/index changes** usually live under `pinot-segment-local` and `pinot-segment-spi`.\n- **Config or API changes** should update relevant configs and docs where applicable.\n\n## Code review\n\nReview the changed behavior and relevant contracts before declaring implementation complete. Follow\n[kb/agents/code-reviewer.md](kb/agents/code-reviewer.md) for requested full reviews and changes that benefit from independent\ndomain review, especially compatibility, concurrency, security, and distributed state changes. Small changes can be\nreviewed directly. Reuse review evidence while the relevant diff and assumptions remain unchanged.\nFix confirmed CRITICAL findings before proceeding; address MAJOR findings or explain why they can be deferred.\n\n## Common gotchas\n- 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`.\n- When running tests, use `-Dtest=ClassName` to run a specific test class rather than the full suite.\n- Mixed-version compatibility matters — do not break wire protocols or serialization formats without careful consideration.\n","AGENTS.md":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# Apache Pinot - AGENTS Guide\n\nThis file provides quick, practical guidance for coding agents working in this\nrepo. It is intentionally short and focused on day-to-day work.\n\n## Project overview\n- Apache Pinot is a real-time distributed OLAP datastore for low-latency\n  analytics over streaming and batch data.\n- Core runtime roles: broker (query routing), server (segment storage/execution),\n  controller (cluster metadata/management), minion (async tasks).\n\n## Repository layout (high level)\n- pinot-broker: broker query planning and scatter-gather.\n- pinot-controller: controller APIs, table/segment metadata, Helix management.\n- pinot-server: server query execution, segment loading, indexing.\n- pinot-minion: background tasks (segment conversion, purge, etc).\n- pinot-common / pinot-spi: shared utils, config, and SPI interfaces.\n- pinot-segment-local / pinot-segment-spi: segment generation, indexes, storage.\n- pinot-query-planner / pinot-query-runtime: multi-stage query (MSQ) engine.\n- pinot-connectors: external tooling to connect to Pinot\n- pinot-plugins: all pinot plugins.\n- pinot-tools: CLI and quickstart scripts.\n- pinot-integration-tests: end-to-end validation suites.\n- pinot-distribution: packaging artifacts.\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build and test\n- Build JDK: Use JDK 25+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.\n- Runtime JRE: Broker/server/controller/minion run on Java 25+.\n- Default to affected modules and their dependencies: `./mvnw -pl <module> -am test`.\n- Faster module build: `./mvnw -pl <module> -am verify -Ppinot-fastdev`. This profile skips style and license checks;\n  it does not replace applicable pre-push validation.\n- Single test example: `./mvnw -pl pinot-segment-local -am -Dtest=RangeIndexTest -Dsurefire.failIfNoSpecifiedTests=false test`.\n  See [kb/skills/run-test.md](kb/skills/run-test.md) for dependency availability and evidence reuse.\n- Full reactor build, when the task requires it: `./mvnw clean install`.\n- Full binary/shaded distribution, when required: `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`.\n- Local cluster startup: follow [kb/skills/quickstart.md](kb/skills/quickstart.md) for the smallest required build and readiness checks.\n\n## Integration tests\n- Single integration test example: `./mvnw -pl pinot-integration-tests -am -Dtest=OfflineClusterIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false test`\n\n## Coding conventions and hygiene\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 25 by default.\n- Keep license headers on all new source files.\n- Use `./mvnw license:format` to add headers to new files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- In tests, statically import methods from `Assert` and `Mockito`; do not qualify calls with `Assert.` or `Mockito.`.\n- Import `FieldSpec.DataType` and `DataSchema.ColumnDataType` directly and use their simple names at call sites.\n- Keep a ternary expression on one line when it fits. Otherwise, put `? <true-expression>` and\n  `: <false-expression>` on separate lines.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Checkstyle config\n- Checkstyle rules and related config files live under `config/`.\n- Use the Maven wrapper (`./mvnw` on Unix-like systems or `mvnw.cmd` on Windows) to run `spotless:apply` to format code and `checkstyle:check` to validate style.\n- Run `./mvnw license:check` to validate license headers.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\n\n## Change guidance\n- Query changes often touch broker planning and server execution; verify both.\n- Segment/index changes usually live under `pinot-segment-local` and\n  `pinot-segment-spi`.\n- Config or API changes should update relevant configs and docs where applicable.\n\n## Reference docs\n- `README.md` for build and quickstart details.\n- `CONTRIBUTING.md` for style, licensing, and contribution guidance.\n\n## Knowledge base (tool-neutral)\nThe `kb/` directory holds AI-optimized procedures and reference material that any\ncoding agent (Claude Code, Copilot, Cursor, GPT, Qwen, Gemini, etc.) can read.\nClaude Code's `.claude/skills/<name>/SKILL.md` and `.claude/agents/<name>.md`\nfiles are thin pointers that delegate to the kb/ procedures — non-Claude agents\nshould read kb/ directly.\n\n- `kb/skills/` — operational procedures and review checklists. See\n  [`kb/skills/README.md`](kb/skills/README.md) for the index. Each file is\n  self-contained; read it and follow it when your task matches the skill name.\n  - Operations: `precommit`, `run-test`, `quickstart`, `bench-compare`,\n    `flaky-analyze`.\n  - Review (eight domains, one per file): `review-config-backcompat`,\n    `review-concurrency-state`, `review-architecture`, `review-performance`,\n    `review-correctness-nulls`, `review-testing`, `review-naming-api`,\n    `review-process-scope`.\n- `kb/agents/code-reviewer.md` — review procedure that selects relevant domains,\n  delegates substantial independent checks, and verifies consolidated findings.\n- `kb/code-review-principles.md` — Pinot-specific review principles cited by id\n  (e.g. `C2.4`, `C6.1`) from the review skills.\n- `kb/claude.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).\n\n**For non-Claude agents:** when a task matches a skill name (e.g. user asks for\na pre-commit check, a benchmark comparison, a flaky-test investigation, or a\ncode review), read the corresponding `kb/skills/<name>.md` and follow its\nprocedure. For a full code review, follow `kb/agents/code-reviewer.md` and cover\nthe domains relevant to the diff; small changes can be reviewed directly.\n",".github/copilot-instructions.md":"# Project overview\nOriginally developed at LinkedIn, Apache PinotTM is a real-time distributed OLAP datastore,\npurpose-built to provide ultra low-latency analytics at extremely high throughput.\n\nWith its distributed architecture and columnar storage, Apache Pinot empowers businesses to gain valuable insights from\nreal-time data, supporting data-driven decision-making and applications.\n\nThis document guides AI coding assistants (Copilot, Cursor, etc.) contributing to this repository.\n\n## Libraries and Frameworks\n\n- Most source code is written in Java 21. `pinot-spi`, `pinot-segment-spi`, `pinot-timeseries-spi`, `pinot-common`, `pinot-java-client`, and `pinot-jdbc-client` target Java 11 bytecode for external consumers.\n- Pinot UI is a React.js frontend. It is stored in `pinot-controller/src/main/resources/`.\n- The code is compiled with Maven and follows a multimodule structure. Use each module's `pom.xml` to\n  understand dependencies and configurations.\n\n## Coding Standards\n\n- Include the Apache Software Foundation (ASF) license header in all supported file types (Java, XML, JSON, Markdown).\n- Javadoc comments can either be written using the `/** ... */` syntax or the `///` syntax,\n  as specified in [JEP-467](https://openjdk.org/jeps/467).\n- Methods and parameters are non-null by default unless annotated with `javax.annotation.Nullable`.\n- Prefer explicit imports for classes rather than fully qualified names used inline.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Use SLF4J for logging; do not use `System.out` or `System.err`.\n- Propagate exceptions with useful context; avoid blanket `catch (Exception)` and never swallow errors.\n- Keep diffs minimal: do not reformat unrelated code and preserve existing whitespace/indentation styles.\n- Favor early returns and guard clauses; avoid deep nesting beyond two to three levels.\n- Add concise comments that explain \"why\", not \"how\"; avoid TODOs—implement instead.\n\n## Repository and Workflow Conventions\n\n- Use SSH Git remotes (`git@github.com:...`) rather than HTTPS.\n- Keep changes small and focused; include or update tests when behavior changes.\n- Write descriptive commit messages and PR descriptions; link related issues when relevant.\n- Prefer absolute file paths in discussions and tool calls for clarity.\n- Do not commit generated files, large binaries, or secrets.\n\n## Build and Test\n\n- Build with Maven from the repository root.\n- Run unit tests locally before opening a PR; ensure the project compiles cleanly without introducing lint errors.\n- Respect the multi-module structure; build order is governed by Maven.\n\n## Domain-specific conventions\n\n- Timezones: When defining or updating `STANDARD_TIMEZONES`, use a three-letter timezone ID with location in the\n  format `PDT(America/Los_Angeles)`. Prefer specific timezone IDs over generic UTC offsets, ensure comprehensive\n  coverage of common timezones, and sort entries by UTC offset.\n- Imports: Favor importing classes at the top of files instead of using fully qualified class names inline.\n\n## Testing Best Practices\n\n- Write unit tests for new functionality and bug fixes; follow the existing test naming conventions.\n- Use Mockito for mocking dependencies in unit tests.\n- Include integration tests when modifying core components or data flows.\n- Add performance tests for optimization changes; measure impact with realistic data volumes.\n- Use `@Test(expected = Exception.class)` sparingly; prefer `@Test` with try-catch for specific assertions.\n- Keep test methods focused and descriptive; avoid overly complex test setups.\n\n## Test Coverage Guidelines\n\n- Aim for high branch coverage (≥80%) on new code and modified code paths.\n- Focus on testing business logic rather than trivial getters/setters or framework boilerplate.\n- Prioritize coverage of error handling paths, edge cases, and boundary conditions.\n- Use JaCoCo or similar tools for measuring coverage; include coverage reports in CI builds.\n- Don't artificially inflate coverage with trivial tests; quality matters more than quantity.\n- Cover both happy path and failure scenarios, including timeout and resource exhaustion cases.\n- For critical components (e.g., query execution, data ingestion), maintain ≥90% coverage.\n- Document coverage expectations in PR descriptions when coverage goals aren't met.\n- Use mutation testing (e.g., PITest) for critical code to ensure test quality.\n- Exclude generated code, test utilities, and simple data transfer objects from coverage requirements.\n\n## Performance Considerations\n\n- Be mindful of memory usage in data processing pipelines; avoid loading large datasets into memory unnecessarily.\n- Use efficient data structures (e.g., primitive arrays over collections for numerical data).\n- Consider lazy evaluation for expensive operations that might not always be needed.\n- Profile performance-critical code paths and document assumptions about data scale.\n- Use appropriate collection types based on access patterns (e.g., ArrayList for iteration, HashMap for lookups).\n\n## Security Guidelines\n\n- Never log sensitive information like passwords, API keys, or personally identifiable data.\n- Validate all user inputs and external data sources; sanitize inputs to prevent injection attacks.\n- Use parameterized queries for database operations to prevent SQL injection.\n- Implement proper authentication and authorization checks for sensitive operations.\n- Follow the principle of least privilege when granting permissions.\n\n## Error Handling and Logging\n\n- Use appropriate log levels: ERROR for failures, WARN for concerning situations, INFO for important events, DEBUG for detailed troubleshooting.\n- Include relevant context in log messages (e.g., request IDs, user context, operation parameters).\n- Use structured logging with key-value pairs for better searchability and analysis.\n- Create custom exception types for domain-specific errors rather than generic RuntimeException.\n- Include stack traces only in DEBUG level; avoid in production logs to prevent information leakage.\n\n## Concurrency and Threading\n\n- Use thread-safe data structures (e.g., ConcurrentHashMap) in multi-threaded contexts.\n- Prefer immutable objects for shared state to avoid race conditions.\n- Use appropriate synchronization mechanisms; favor higher-level constructs over synchronized blocks.\n- Document thread safety guarantees in class-level Javadoc.\n- Be aware of Pinot's distributed nature; consider consistency models and eventual consistency scenarios.\n\n## Configuration Management\n\n- Externalize configuration values; avoid hardcoding environment-specific settings.\n- Use meaningful default values with clear documentation about their impact.\n- Validate configuration at startup and provide helpful error messages for invalid settings.\n- Document all configuration properties in code comments or separate configuration docs.\n- Use consistent naming conventions for configuration keys (e.g., pinot.server.port).\n\n## Documentation Standards\n\n- Document public APIs with comprehensive Javadoc including parameter descriptions, return values, and exceptions.\n- Include code examples in documentation where helpful for complex APIs.\n- Update documentation when changing behavior; keep README files current.\n- Use consistent terminology across documentation and code comments.\n- Document performance characteristics and limitations for important components.\n\n## Code Review Process\n\n- Address all review comments thoughtfully; if you disagree, explain your reasoning clearly.\n- Keep PRs focused on a single concern; split large changes into smaller, reviewable commits.\n- Include context in PR descriptions: what problem you're solving, how you solved it, and any trade-offs.\n- Test your changes thoroughly before requesting review; include test results when relevant.\n- Be responsive to feedback and iterate quickly on requested changes.\n\n## Assistant guidance\n\n- When editing, touch only what is necessary; keep changes minimal and localized.\n- Preserve the file's existing indentation and whitespace; do not reflow or reformat unrelated code.\n- When creating new files, include the ASF license header and all required imports/dependencies.\n- Avoid adding extremely long hashes or non-textual content; keep repository contents textual and reviewable.\n- If uncertain about where a change belongs, search for similar code in the codebase and follow established patterns.\n- Use absolute file paths in discussions and tool calls for clarity.\n- Prefer early returns and guard clauses to reduce nesting and improve readability.\n- When implementing complex logic, break it into smaller, well-named methods.\n- Consider edge cases and failure scenarios in your implementations.\n- Follow the existing code patterns and architectural decisions in the codebase.\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# Apache Pinot - AGENTS Guide\n\nThis file provides quick, practical guidance for coding agents working in this\nrepo. It is intentionally short and focused on day-to-day work.\n\n## Project overview\n- Apache Pinot is a real-time distributed OLAP datastore for low-latency\n  analytics over streaming and batch data.\n- Core runtime roles: broker (query routing), server (segment storage/execution),\n  controller (cluster metadata/management), minion (async tasks).\n\n## Repository layout (high level)\n- pinot-broker: broker query planning and scatter-gather.\n- pinot-controller: controller APIs, table/segment metadata, Helix management.\n- pinot-server: server query execution, segment loading, indexing.\n- pinot-minion: background tasks (segment conversion, purge, etc).\n- pinot-common / pinot-spi: shared utils, config, and SPI interfaces.\n- pinot-segment-local / pinot-segment-spi: segment generation, indexes, storage.\n- pinot-query-planner / pinot-query-runtime: multi-stage query (MSQ) engine.\n- pinot-connectors: external tooling to connect to Pinot\n- pinot-plugins: all pinot plugins.\n- pinot-tools: CLI and quickstart scripts.\n- pinot-integration-tests: end-to-end validation suites.\n- pinot-distribution: packaging artifacts.\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build and test\n- Build JDK: Use JDK 25+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.\n- Runtime JRE: Broker/server/controller/minion run on Java 25+.\n- Default to affected modules and their dependencies: `./mvnw -pl <module> -am test`.\n- Faster module build: `./mvnw -pl <module> -am verify -Ppinot-fastdev`. This profile skips style and license checks;\n  it does not replace applicable pre-push validation.\n- Single test example: `./mvnw -pl pinot-segment-local -am -Dtest=RangeIndexTest -Dsurefire.failIfNoSpecifiedTests=false test`.\n  See [kb/skills/run-test.md](kb/skills/run-test.md) for dependency availability and evidence reuse.\n- Full reactor build, when the task requires it: `./mvnw clean install`.\n- Full binary/shaded distribution, when required: `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`.\n- Local cluster startup: follow [kb/skills/quickstart.md](kb/skills/quickstart.md) for the smallest required build and readiness checks.\n\n## Integration tests\n- Single integration test example: `./mvnw -pl pinot-integration-tests -am -Dtest=OfflineClusterIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false test`\n\n## Coding conventions and hygiene\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 25 by default.\n- Keep license headers on all new source files.\n- Use `./mvnw license:format` to add headers to new files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- In tests, statically import methods from `Assert` and `Mockito`; do not qualify calls with `Assert.` or `Mockito.`.\n- Import `FieldSpec.DataType` and `DataSchema.ColumnDataType` directly and use their simple names at call sites.\n- Keep a ternary expression on one line when it fits. Otherwise, put `? <true-expression>` and\n  `: <false-expression>` on separate lines.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Checkstyle config\n- Checkstyle rules and related config files live under `config/`.\n- Use the Maven wrapper (`./mvnw` on Unix-like systems or `mvnw.cmd` on Windows) to run `spotless:apply` to format code and `checkstyle:check` to validate style.\n- Run `./mvnw license:check` to validate license headers.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\n\n## Change guidance\n- Query changes often touch broker planning and server execution; verify both.\n- Segment/index changes usually live under `pinot-segment-local` and\n  `pinot-segment-spi`.\n- Config or API changes should update relevant configs and docs where applicable.\n\n## Reference docs\n- `README.md` for build and quickstart details.\n- `CONTRIBUTING.md` for style, licensing, and contribution guidance.\n\n## Knowledge base (tool-neutral)\nThe `kb/` directory holds AI-optimized procedures and reference material that any\ncoding agent (Claude Code, Copilot, Cursor, GPT, Qwen, Gemini, etc.) can read.\nClaude Code's `.claude/skills/<name>/SKILL.md` and `.claude/agents/<name>.md`\nfiles are thin pointers that delegate to the kb/ procedures — non-Claude agents\nshould read kb/ directly.\n\n- `kb/skills/` — operational procedures and review checklists. See\n  [`kb/skills/README.md`](kb/skills/README.md) for the index. Each file is\n  self-contained; read it and follow it when your task matches the skill name.\n  - Operations: `precommit`, `run-test`, `quickstart`, `bench-compare`,\n    `flaky-analyze`.\n  - Review (eight domains, one per file): `review-config-backcompat`,\n    `review-concurrency-state`, `review-architecture`, `review-performance`,\n    `review-correctness-nulls`, `review-testing`, `review-naming-api`,\n    `review-process-scope`.\n- `kb/agents/code-reviewer.md` — review procedure that selects relevant domains,\n  delegates substantial independent checks, and verifies consolidated findings.\n- `kb/code-review-principles.md` — Pinot-specific review principles cited by id\n  (e.g. `C2.4`, `C6.1`) from the review skills.\n- `kb/claude.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).\n\n**For non-Claude agents:** when a task matches a skill name (e.g. user asks for\na pre-commit check, a benchmark comparison, a flaky-test investigation, or a\ncode review), read the corresponding `kb/skills/<name>.md` and follow its\nprocedure. For a full code review, follow `kb/agents/code-reviewer.md` and cover\nthe domains relevant to the diff; small changes can be reviewed directly.\n","isInternal":false,"tokens":1918,"sizeBytes":8121},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# CLAUDE.md - Apache Pinot\n\n## What is this project?\nApache 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).\n\n## Repository layout\n| Directory | Purpose |\n|---|---|\n| `pinot-broker` | Broker query planning and scatter-gather |\n| `pinot-controller` | Controller APIs, table/segment metadata, Helix management |\n| `pinot-server` | Server query execution, segment loading, indexing |\n| `pinot-minion` | Background tasks (segment conversion, purge, etc.) |\n| `pinot-common` / `pinot-spi` | Shared utils, config, and SPI interfaces |\n| `pinot-segment-local` / `pinot-segment-spi` | Segment generation, indexes, storage |\n| `pinot-query-planner` / `pinot-query-runtime` | Multi-stage query engine (MSQE) |\n| `pinot-connectors` | External tooling to connect to Pinot |\n| `pinot-plugins` | All Pinot plugins (input formats, filesystems, stream/batch ingestion, metrics, etc.) |\n| `pinot-tools` | CLI and quickstart scripts |\n| `pinot-integration-tests` | End-to-end validation suites |\n| `pinot-distribution` | Packaging artifacts |\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build commands\nUse [AGENTS.md](AGENTS.md#build-and-test) for the build JDK, artifact bytecode targets, and scoped build/test commands.\nUse [kb/skills/run-test.md](kb/skills/run-test.md) for targeted tests and\n[kb/skills/quickstart.md](kb/skills/quickstart.md) to start and verify a local cluster.\n\n## Code style and formatting\n- Run `./mvnw spotless:apply` to auto-format code.\n- Run `./mvnw checkstyle:check` to validate style. Checkstyle config is in `config/checkstyle.xml`.\n- Run `./mvnw license:format` to add license headers to new files.\n- Run `./mvnw license:check` to validate license headers.\n- Always use the Maven wrapper (`./mvnw`) rather than a system `mvn`.\n\n## Coding conventions\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc syntax supported by the owning module's configured source release; see [AGENTS.md](AGENTS.md#coding-conventions-and-hygiene).\n- Keep Apache 2.0 license headers on all new source files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n- 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.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\nClaude Code users can invoke `/precommit`.\n\n## Change guidance\n- **Query changes** often touch broker planning and server execution; verify both.\n- **Segment/index changes** usually live under `pinot-segment-local` and `pinot-segment-spi`.\n- **Config or API changes** should update relevant configs and docs where applicable.\n\n## Code review\n\nReview the changed behavior and relevant contracts before declaring implementation complete. Follow\n[kb/agents/code-reviewer.md](kb/agents/code-reviewer.md) for requested full reviews and changes that benefit from independent\ndomain review, especially compatibility, concurrency, security, and distributed state changes. Small changes can be\nreviewed directly. Reuse review evidence while the relevant diff and assumptions remain unchanged.\nFix confirmed CRITICAL findings before proceeding; address MAJOR findings or explain why they can be deferred.\n\n## Common gotchas\n- 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`.\n- When running tests, use `-Dtest=ClassName` to run a specific test class rather than the full suite.\n- Mixed-version compatibility matters — do not break wire protocols or serialization formats without careful consideration.\n","isInternal":false,"tokens":1409,"sizeBytes":6244},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Project overview\nOriginally developed at LinkedIn, Apache PinotTM is a real-time distributed OLAP datastore,\npurpose-built to provide ultra low-latency analytics at extremely high throughput.\n\nWith its distributed architecture and columnar storage, Apache Pinot empowers businesses to gain valuable insights from\nreal-time data, supporting data-driven decision-making and applications.\n\nThis document guides AI coding assistants (Copilot, Cursor, etc.) contributing to this repository.\n\n## Libraries and Frameworks\n\n- Most source code is written in Java 21. `pinot-spi`, `pinot-segment-spi`, `pinot-timeseries-spi`, `pinot-common`, `pinot-java-client`, and `pinot-jdbc-client` target Java 11 bytecode for external consumers.\n- Pinot UI is a React.js frontend. It is stored in `pinot-controller/src/main/resources/`.\n- The code is compiled with Maven and follows a multimodule structure. Use each module's `pom.xml` to\n  understand dependencies and configurations.\n\n## Coding Standards\n\n- Include the Apache Software Foundation (ASF) license header in all supported file types (Java, XML, JSON, Markdown).\n- Javadoc comments can either be written using the `/** ... */` syntax or the `///` syntax,\n  as specified in [JEP-467](https://openjdk.org/jeps/467).\n- Methods and parameters are non-null by default unless annotated with `javax.annotation.Nullable`.\n- Prefer explicit imports for classes rather than fully qualified names used inline.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Use SLF4J for logging; do not use `System.out` or `System.err`.\n- Propagate exceptions with useful context; avoid blanket `catch (Exception)` and never swallow errors.\n- Keep diffs minimal: do not reformat unrelated code and preserve existing whitespace/indentation styles.\n- Favor early returns and guard clauses; avoid deep nesting beyond two to three levels.\n- Add concise comments that explain \"why\", not \"how\"; avoid TODOs—implement instead.\n\n## Repository and Workflow Conventions\n\n- Use SSH Git remotes (`git@github.com:...`) rather than HTTPS.\n- Keep changes small and focused; include or update tests when behavior changes.\n- Write descriptive commit messages and PR descriptions; link related issues when relevant.\n- Prefer absolute file paths in discussions and tool calls for clarity.\n- Do not commit generated files, large binaries, or secrets.\n\n## Build and Test\n\n- Build with Maven from the repository root.\n- Run unit tests locally before opening a PR; ensure the project compiles cleanly without introducing lint errors.\n- Respect the multi-module structure; build order is governed by Maven.\n\n## Domain-specific conventions\n\n- Timezones: When defining or updating `STANDARD_TIMEZONES`, use a three-letter timezone ID with location in the\n  format `PDT(America/Los_Angeles)`. Prefer specific timezone IDs over generic UTC offsets, ensure comprehensive\n  coverage of common timezones, and sort entries by UTC offset.\n- Imports: Favor importing classes at the top of files instead of using fully qualified class names inline.\n\n## Testing Best Practices\n\n- Write unit tests for new functionality and bug fixes; follow the existing test naming conventions.\n- Use Mockito for mocking dependencies in unit tests.\n- Include integration tests when modifying core components or data flows.\n- Add performance tests for optimization changes; measure impact with realistic data volumes.\n- Use `@Test(expected = Exception.class)` sparingly; prefer `@Test` with try-catch for specific assertions.\n- Keep test methods focused and descriptive; avoid overly complex test setups.\n\n## Test Coverage Guidelines\n\n- Aim for high branch coverage (≥80%) on new code and modified code paths.\n- Focus on testing business logic rather than trivial getters/setters or framework boilerplate.\n- Prioritize coverage of error handling paths, edge cases, and boundary conditions.\n- Use JaCoCo or similar tools for measuring coverage; include coverage reports in CI builds.\n- Don't artificially inflate coverage with trivial tests; quality matters more than quantity.\n- Cover both happy path and failure scenarios, including timeout and resource exhaustion cases.\n- For critical components (e.g., query execution, data ingestion), maintain ≥90% coverage.\n- Document coverage expectations in PR descriptions when coverage goals aren't met.\n- Use mutation testing (e.g., PITest) for critical code to ensure test quality.\n- Exclude generated code, test utilities, and simple data transfer objects from coverage requirements.\n\n## Performance Considerations\n\n- Be mindful of memory usage in data processing pipelines; avoid loading large datasets into memory unnecessarily.\n- Use efficient data structures (e.g., primitive arrays over collections for numerical data).\n- Consider lazy evaluation for expensive operations that might not always be needed.\n- Profile performance-critical code paths and document assumptions about data scale.\n- Use appropriate collection types based on access patterns (e.g., ArrayList for iteration, HashMap for lookups).\n\n## Security Guidelines\n\n- Never log sensitive information like passwords, API keys, or personally identifiable data.\n- Validate all user inputs and external data sources; sanitize inputs to prevent injection attacks.\n- Use parameterized queries for database operations to prevent SQL injection.\n- Implement proper authentication and authorization checks for sensitive operations.\n- Follow the principle of least privilege when granting permissions.\n\n## Error Handling and Logging\n\n- Use appropriate log levels: ERROR for failures, WARN for concerning situations, INFO for important events, DEBUG for detailed troubleshooting.\n- Include relevant context in log messages (e.g., request IDs, user context, operation parameters).\n- Use structured logging with key-value pairs for better searchability and analysis.\n- Create custom exception types for domain-specific errors rather than generic RuntimeException.\n- Include stack traces only in DEBUG level; avoid in production logs to prevent information leakage.\n\n## Concurrency and Threading\n\n- Use thread-safe data structures (e.g., ConcurrentHashMap) in multi-threaded contexts.\n- Prefer immutable objects for shared state to avoid race conditions.\n- Use appropriate synchronization mechanisms; favor higher-level constructs over synchronized blocks.\n- Document thread safety guarantees in class-level Javadoc.\n- Be aware of Pinot's distributed nature; consider consistency models and eventual consistency scenarios.\n\n## Configuration Management\n\n- Externalize configuration values; avoid hardcoding environment-specific settings.\n- Use meaningful default values with clear documentation about their impact.\n- Validate configuration at startup and provide helpful error messages for invalid settings.\n- Document all configuration properties in code comments or separate configuration docs.\n- Use consistent naming conventions for configuration keys (e.g., pinot.server.port).\n\n## Documentation Standards\n\n- Document public APIs with comprehensive Javadoc including parameter descriptions, return values, and exceptions.\n- Include code examples in documentation where helpful for complex APIs.\n- Update documentation when changing behavior; keep README files current.\n- Use consistent terminology across documentation and code comments.\n- Document performance characteristics and limitations for important components.\n\n## Code Review Process\n\n- Address all review comments thoughtfully; if you disagree, explain your reasoning clearly.\n- Keep PRs focused on a single concern; split large changes into smaller, reviewable commits.\n- Include context in PR descriptions: what problem you're solving, how you solved it, and any trade-offs.\n- Test your changes thoroughly before requesting review; include test results when relevant.\n- Be responsive to feedback and iterate quickly on requested changes.\n\n## Assistant guidance\n\n- When editing, touch only what is necessary; keep changes minimal and localized.\n- Preserve the file's existing indentation and whitespace; do not reflow or reformat unrelated code.\n- When creating new files, include the ASF license header and all required imports/dependencies.\n- Avoid adding extremely long hashes or non-textual content; keep repository contents textual and reviewable.\n- If uncertain about where a change belongs, search for similar code in the codebase and follow established patterns.\n- Use absolute file paths in discussions and tool calls for clarity.\n- Prefer early returns and guard clauses to reduce nesting and improve readability.\n- When implementing complex logic, break it into smaller, well-named methods.\n- Consider edge cases and failure scenarios in your implementations.\n- Follow the existing code patterns and architectural decisions in the codebase.\n","isInternal":false,"tokens":1806,"sizeBytes":9378},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":191},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":177},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/apache/pinot/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":170}],"systemPromptSnippet":"<yakaai_skills repo=\"apache/pinot\">\n<!-- File: AGENTS.md (Tokens: ~1918 | Category: root-instruction) -->\n<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# Apache Pinot - AGENTS Guide\n\nThis file provides quick, practical guidance for coding agents working in this\nrepo. It is intentionally short and focused on day-to-day work.\n\n## Project overview\n- Apache Pinot is a real-time distributed OLAP datastore for low-latency\n  analytics over streaming and batch data.\n- Core runtime roles: broker (query routing), server (segment storage/execution),\n  controller (cluster metadata/management), minion (async tasks).\n\n## Repository layout (high level)\n- pinot-broker: broker query planning and scatter-gather.\n- pinot-controller: controller APIs, table/segment metadata, Helix management.\n- pinot-server: server query execution, segment loading, indexing.\n- pinot-minion: background tasks (segment conversion, purge, etc).\n- pinot-common / pinot-spi: shared utils, config, and SPI interfaces.\n- pinot-segment-local / pinot-segment-spi: segment generation, indexes, storage.\n- pinot-query-planner / pinot-query-runtime: multi-stage query (MSQ) engine.\n- pinot-connectors: external tooling to connect to Pinot\n- pinot-plugins: all pinot plugins.\n- pinot-tools: CLI and quickstart scripts.\n- pinot-integration-tests: end-to-end validation suites.\n- pinot-distribution: packaging artifacts.\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build and test\n- Build JDK: Use JDK 25+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.\n- Runtime JRE: Broker/server/controller/minion run on Java 25+.\n- Default to affected modules and their dependencies: `./mvnw -pl <module> -am test`.\n- Faster module build: `./mvnw -pl <module> -am verify -Ppinot-fastdev`. This profile skips style and license checks;\n  it does not replace applicable pre-push validation.\n- Single test example: `./mvnw -pl pinot-segment-local -am -Dtest=RangeIndexTest -Dsurefire.failIfNoSpecifiedTests=false test`.\n  See [kb/skills/run-test.md](kb/skills/run-test.md) for dependency availability and evidence reuse.\n- Full reactor build, when the task requires it: `./mvnw clean install`.\n- Full binary/shaded distribution, when required: `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`.\n- Local cluster startup: follow [kb/skills/quickstart.md](kb/skills/quickstart.md) for the smallest required build and readiness checks.\n\n## Integration tests\n- Single integration test example: `./mvnw -pl pinot-integration-tests -am -Dtest=OfflineClusterIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false test`\n\n## Coding conventions and hygiene\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 25 by default.\n- Keep license headers on all new source files.\n- Use `./mvnw license:format` to add headers to new files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- In tests, statically import methods from `Assert` and `Mockito`; do not qualify calls with `Assert.` or `Mockito.`.\n- Import `FieldSpec.DataType` and `DataSchema.ColumnDataType` directly and use their simple names at call sites.\n- Keep a ternary expression on one line when it fits. Otherwise, put `? <true-expression>` and\n  `: <false-expression>` on separate lines.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Checkstyle config\n- Checkstyle rules and related config files live under `config/`.\n- Use the Maven wrapper (`./mvnw` on Unix-like systems or `mvnw.cmd` on Windows) to run `spotless:apply` to format code and `checkstyle:check` to validate style.\n- Run `./mvnw license:check` to validate license headers.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\n\n## Change guidance\n- Query changes often touch broker planning and server execution; verify both.\n- Segment/index changes usually live under `pinot-segment-local` and\n  `pinot-segment-spi`.\n- Config or API changes should update relevant configs and docs where applicable.\n\n## Reference docs\n- `README.md` for build and quickstart details.\n- `CONTRIBUTING.md` for style, licensing, and contribution guidance.\n\n## Knowledge base (tool-neutral)\nThe `kb/` directory holds AI-optimized procedures and reference material that any\ncoding agent (Claude Code, Copilot, Cursor, GPT, Qwen, Gemini, etc.) can read.\nClaude Code's `.claude/skills/<name>/SKILL.md` and `.claude/agents/<name>.md`\nfiles are thin pointers that delegate to the kb/ procedures — non-Claude agents\nshould read kb/ directly.\n\n- `kb/skills/` — operational procedures and review checklists. See\n  [`kb/skills/README.md`](kb/skills/README.md) for the index. Each file is\n  self-contained; read it and follow it when your task matches the skill name.\n  - Operations: `precommit`, `run-test`, `quickstart`, `bench-compare`,\n    `flaky-analyze`.\n  - Review (eight domains, one per file): `review-config-backcompat`,\n    `review-concurrency-state`, `review-architecture`, `review-performance`,\n    `review-correctness-nulls`, `review-testing`, `review-naming-api`,\n    `review-process-scope`.\n- `kb/agents/code-reviewer.md` — review procedure that selects relevant domains,\n  delegates substantial independent checks, and verifies consolidated findings.\n- `kb/code-review-principles.md` — Pinot-specific review principles cited by id\n  (e.g. `C2.4`, `C6.1`) from the review skills.\n- `kb/claude.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).\n\n**For non-Claude agents:** when a task matches a skill name (e.g. user asks for\na pre-commit check, a benchmark comparison, a flaky-test investigation, or a\ncode review), read the corresponding `kb/skills/<name>.md` and follow its\nprocedure. For a full code review, follow `kb/agents/code-reviewer.md` and cover\nthe domains relevant to the diff; small changes can be reviewed directly.\n\n<!-- File: CLAUDE.md (Tokens: ~1409 | Category: claude-rule) -->\n<!--\n\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n\n-->\n# CLAUDE.md - Apache Pinot\n\n## What is this project?\nApache 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).\n\n## Repository layout\n| Directory | Purpose |\n|---|---|\n| `pinot-broker` | Broker query planning and scatter-gather |\n| `pinot-controller` | Controller APIs, table/segment metadata, Helix management |\n| `pinot-server` | Server query execution, segment loading, indexing |\n| `pinot-minion` | Background tasks (segment conversion, purge, etc.) |\n| `pinot-common` / `pinot-spi` | Shared utils, config, and SPI interfaces |\n| `pinot-segment-local` / `pinot-segment-spi` | Segment generation, indexes, storage |\n| `pinot-query-planner` / `pinot-query-runtime` | Multi-stage query engine (MSQE) |\n| `pinot-connectors` | External tooling to connect to Pinot |\n| `pinot-plugins` | All Pinot plugins (input formats, filesystems, stream/batch ingestion, metrics, etc.) |\n| `pinot-tools` | CLI and quickstart scripts |\n| `pinot-integration-tests` | End-to-end validation suites |\n| `pinot-distribution` | Packaging artifacts |\n\nWhen locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).\n\n## Build commands\nUse [AGENTS.md](AGENTS.md#build-and-test) for the build JDK, artifact bytecode targets, and scoped build/test commands.\nUse [kb/skills/run-test.md](kb/skills/run-test.md) for targeted tests and\n[kb/skills/quickstart.md](kb/skills/quickstart.md) to start and verify a local cluster.\n\n## Code style and formatting\n- Run `./mvnw spotless:apply` to auto-format code.\n- Run `./mvnw checkstyle:check` to validate style. Checkstyle config is in `config/checkstyle.xml`.\n- Run `./mvnw license:format` to add license headers to new files.\n- Run `./mvnw license:check` to validate license headers.\n- Always use the Maven wrapper (`./mvnw`) rather than a system `mvn`.\n\n## Coding conventions\n- Add class-level Javadoc for new classes; describe behavior and thread-safety.\n- Use Javadoc syntax supported by the owning module's configured source release; see [AGENTS.md](AGENTS.md#coding-conventions-and-hygiene).\n- Keep Apache 2.0 license headers on all new source files.\n- Preserve backward compatibility across mixed-version broker/server/controller.\n- Prefer imports over fully qualified class names (e.g., use `import com.foo.Bar` and refer to `Bar`, not `com.foo.Bar` inline).\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Prefer targeted unit tests; use integration tests when behavior crosses roles.\n- 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.\n\n## Commit messages\n- Do not include `Co-authored-by` trailers that reference AI tools (e.g., Claude, Copilot).\n  - **Why**: These trailers propagate into squash-merge commits on GitHub, making the project history appear AI-authored rather than human-authored.\n  - **Fix**: Omit the `Co-authored-by` line entirely when committing.\n\n## Pre-commit checks\nBefore pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,\ncheckstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when\ncompiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.\nClaude Code users can invoke `/precommit`.\n\n## Change guidance\n- **Query changes** often touch broker planning and server execution; verify both.\n- **Segment/index changes** usually live under `pinot-segment-local` and `pinot-segment-spi`.\n- **Config or API changes** should update relevant configs and docs where applicable.\n\n## Code review\n\nReview the changed behavior and relevant contracts before declaring implementation complete. Follow\n[kb/agents/code-reviewer.md](kb/agents/code-reviewer.md) for requested full reviews and changes that benefit from independent\ndomain review, especially compatibility, concurrency, security, and distributed state changes. Small changes can be\nreviewed directly. Reuse review evidence while the relevant diff and assumptions remain unchanged.\nFix confirmed CRITICAL findings before proceeding; address MAJOR findings or explain why they can be deferred.\n\n## Common gotchas\n- 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`.\n- When running tests, use `-Dtest=ClassName` to run a specific test class rather than the full suite.\n- Mixed-version compatibility matters — do not break wire protocols or serialization formats without careful consideration.\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~1806 | Category: copilot-instructions) -->\n# Project overview\nOriginally developed at LinkedIn, Apache PinotTM is a real-time distributed OLAP datastore,\npurpose-built to provide ultra low-latency analytics at extremely high throughput.\n\nWith its distributed architecture and columnar storage, Apache Pinot empowers businesses to gain valuable insights from\nreal-time data, supporting data-driven decision-making and applications.\n\nThis document guides AI coding assistants (Copilot, Cursor, etc.) contributing to this repository.\n\n## Libraries and Frameworks\n\n- Most source code is written in Java 21. `pinot-spi`, `pinot-segment-spi`, `pinot-timeseries-spi`, `pinot-common`, `pinot-java-client`, and `pinot-jdbc-client` target Java 11 bytecode for external consumers.\n- Pinot UI is a React.js frontend. It is stored in `pinot-controller/src/main/resources/`.\n- The code is compiled with Maven and follows a multimodule structure. Use each module's `pom.xml` to\n  understand dependencies and configurations.\n\n## Coding Standards\n\n- Include the Apache Software Foundation (ASF) license header in all supported file types (Java, XML, JSON, Markdown).\n- Javadoc comments can either be written using the `/** ... */` syntax or the `///` syntax,\n  as specified in [JEP-467](https://openjdk.org/jeps/467).\n- Methods and parameters are non-null by default unless annotated with `javax.annotation.Nullable`.\n- Prefer explicit imports for classes rather than fully qualified names used inline.\n- Prefer `List.of()`, `Set.of()`, and `Map.of()` for non-null immutable collection literals. Checkstyle blocks\n  `Collections.emptyList()`, `Collections.emptySet()`, and `Collections.emptyMap()`; use `List.of()`, `Set.of()`, and\n  `Map.of()` instead. Do not add blanket bans for `Collections.singleton*`; use them only when an element/key/value\n  argument is intentionally null because `List.of(null)`, `Set.of(null)`, and `Map.of(...)` with null keys or values\n  throw `NullPointerException`. Before replacing empty collection factories, check whether the value flows to\n  mutating callers. See\n  `kb/code-review-principles.md` C7.12.\n- Use SLF4J for logging; do not use `System.out` or `System.err`.\n- Propagate exceptions with useful context; avoid blanket `catch (Exception)` and never swallow errors.\n- Keep diffs minimal: do not reformat unrelated code and preserve existing whitespace/indentation styles.\n- Favor early returns and guard clauses; avoid deep nesting beyond two to three levels.\n- Add concise comments that explain \"why\", not \"how\"; avoid TODOs—implement instead.\n\n## Repository and Workflow Conventions\n\n- Use SSH Git remotes (`git@github.com:...`) rather than HTTPS.\n- Keep changes small and focused; include or update tests when behavior changes.\n- Write descriptive commit messages and PR descriptions; link related issues when relevant.\n- Prefer absolute file paths in discussions and tool calls for clarity.\n- Do not commit generated files, large binaries, or secrets.\n\n## Build and Test\n\n- Build with Maven from the repository root.\n- Run unit tests locally before opening a PR; ensure the project compiles cleanly without introducing lint errors.\n- Respect the multi-module structure; build order is governed by Maven.\n\n## Domain-specific conventions\n\n- Timezones: When defining or updating `STANDARD_TIMEZONES`, use a three-letter timezone ID with location in the\n  format `PDT(America/Los_Angeles)`. Prefer specific timezone IDs over generic UTC offsets, ensure comprehensive\n  coverage of common timezones, and sort entries by UTC offset.\n- Imports: Favor importing classes at the top of files instead of using fully qualified class names inline.\n\n## Testing Best Practices\n\n- Write unit tests for new functionality and bug fixes; follow the existing test naming conventions.\n- Use Mockito for mocking dependencies in unit tests.\n- Include integration tests when modifying core components or data flows.\n- Add performance tests for optimization changes; measure impact with realistic data volumes.\n- Use `@Test(expected = Exception.class)` sparingly; prefer `@Test` with try-catch for specific assertions.\n- Keep test methods focused and descriptive; avoid overly complex test setups.\n\n## Test Coverage Guidelines\n\n- Aim for high branch coverage (≥80%) on new code and modified code paths.\n- Focus on testing business logic rather than trivial getters/setters or framework boilerplate.\n- Prioritize coverage of error handling paths, edge cases, and boundary conditions.\n- Use JaCoCo or similar tools for measuring coverage; include coverage reports in CI builds.\n- Don't artificially inflate coverage with trivial tests; quality matters more than quantity.\n- Cover both happy path and failure scenarios, including timeout and resource exhaustion cases.\n- For critical components (e.g., query execution, data ingestion), maintain ≥90% coverage.\n- Document coverage expectations in PR descriptions when coverage goals aren't met.\n- Use mutation testing (e.g., PITest) for critical code to ensure test quality.\n- Exclude generated code, test utilities, and simple data transfer objects from coverage requirements.\n\n## Performance Considerations\n\n- Be mindful of memory usage in data processing pipelines; avoid loading large datasets into memory unnecessarily.\n- Use efficient data structures (e.g., primitive arrays over collections for numerical data).\n- Consider lazy evaluation for expensive operations that might not always be needed.\n- Profile performance-critical code paths and document assumptions about data scale.\n- Use appropriate collection types based on access patterns (e.g., ArrayList for iteration, HashMap for lookups).\n\n## Security Guidelines\n\n- Never log sensitive information like passwords, API keys, or personally identifiable data.\n- Validate all user inputs and external data sources; sanitize inputs to prevent injection attacks.\n- Use parameterized queries for database operations to prevent SQL injection.\n- Implement proper authentication and authorization checks for sensitive operations.\n- Follow the principle of least privilege when granting permissions.\n\n## Error Handling and Logging\n\n- Use appropriate log levels: ERROR for failures, WARN for concerning situations, INFO for important events, DEBUG for detailed troubleshooting.\n- Include relevant context in log messages (e.g., request IDs, user context, operation parameters).\n- Use structured logging with key-value pairs for better searchability and analysis.\n- Create custom exception types for domain-specific errors rather than generic RuntimeException.\n- Include stack traces only in DEBUG level; avoid in production logs to prevent information leakage.\n\n## Concurrency and Threading\n\n- Use thread-safe data structures (e.g., ConcurrentHashMap) in multi-threaded contexts.\n- Prefer immutable objects for shared state to avoid race conditions.\n- Use appropriate synchronization mechanisms; favor higher-level constructs over synchronized blocks.\n- Document thread safety guarantees in class-level Javadoc.\n- Be aware of Pinot's distributed nature; consider consistency models and eventual consistency scenarios.\n\n## Configuration Management\n\n- Externalize configuration values; avoid hardcoding environment-specific settings.\n- Use meaningful default values with clear documentation about their impact.\n- Validate configuration at startup and provide helpful error messages for invalid settings.\n- Document all configuration properties in code comments or separate configuration docs.\n- Use consistent naming conventions for configuration keys (e.g., pinot.server.port).\n\n## Documentation Standards\n\n- Document public APIs with comprehensive Javadoc including parameter descriptions, return values, and exceptions.\n- Include code examples in documentation where helpful for complex APIs.\n- Update documentation when changing behavior; keep README files current.\n- Use consistent terminology across documentation and code comments.\n- Document performance characteristics and limitations for important components.\n\n## Code Review Process\n\n- Address all review comments thoughtfully; if you disagree, explain your reasoning clearly.\n- Keep PRs focused on a single concern; split large changes into smaller, reviewable commits.\n- Include context in PR descriptions: what problem you're solving, how you solved it, and any trade-offs.\n- Test your changes thoroughly before requesting review; include test results when relevant.\n- Be responsive to feedback and iterate quickly on requested changes.\n\n## Assistant guidance\n\n- When editing, touch only what is necessary; keep changes minimal and localized.\n- Preserve the file's existing indentation and whitespace; do not reflow or reformat unrelated code.\n- When creating new files, include the ASF license header and all required imports/dependencies.\n- Avoid adding extremely long hashes or non-textual content; keep repository contents textual and reviewable.\n- If uncertain about where a change belongs, search for similar code in the codebase and follow established patterns.\n- Use absolute file paths in discussions and tool calls for clarity.\n- Prefer early returns and guard clauses to reduce nesting and improve readability.\n- When implementing complex logic, break it into smaller, well-named methods.\n- Consider edge cases and failure scenarios in your implementations.\n- Follow the existing code patterns and architectural decisions in the codebase.\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/apache/pinot/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}