{"owner":"StarRocks","repo":"starrocks","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# AGENTS.md - StarRocks\n\nAgent entrypoint for this repository. Start with the nearest nested `AGENTS.md`; use this file for repo-wide rules only.\n\n## Read Order\n\n1. Read [`handbook/index.md`](./handbook/index.md) for repo topology, architecture entrypoints, and active engineering plans. If `handbook/plans/local/index.md` exists, treat it as a checkout-local extension to the tracked plan set after reading [`handbook/plans/index.md`](./handbook/plans/index.md).\n2. Read the nearest nested `AGENTS.md`.\n3. For Backend work, read [`handbook/domains/backend.md`](./handbook/domains/backend.md) and [`be/AGENTS.md`](./be/AGENTS.md).\n4. For Frontend work, read [`handbook/domains/frontend.md`](./handbook/domains/frontend.md) and [`fe/AGENTS.md`](./fe/AGENTS.md).\n5. For SQL tests, docs, generated code, Java extensions, or CI/tooling, read the matching `handbook/domains/` page before the nested guide.\n\n## Repo Map\n\n- `be/`: C++ backend for execution, storage, services, and data processing.\n- `fe/`: Java frontend for parsing, planning, metadata, and coordination.\n- `gensrc/`: generated thrift/protobuf code.\n- `test/`: SQL integration tests.\n- `docs/`: user and admin documentation.\n- `java-extensions/`: JNI and external source integrations.\n\n## Quick Commands\n\n```bash\n# Build backend or frontend\n./build.sh --be\n./build.sh --fe\n\n# Run backend or frontend unit tests\n./run-be-ut.sh\n./run-fe-ut.sh\n\n# Run SQL integration tests\ncd test && python3 run.py -v\n```\n\n## Repo-Wide Invariants\n\n- Do not hand-edit generated outputs in `gensrc/` unless the generator workflow explicitly requires it.\n- Protobuf fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- Thrift fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- User-facing config or metric changes must update the matching docs in `docs/en/` and `docs/zh/` when applicable.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## PR Contract\n\n- Commit messages: English, imperative, concise.\n- PR titles: `[BugFix] ...`, `[Feature] ...`, `[Enhancement] ...`, `[Refactor] ...`, `[UT] ...`, `[Doc] ...`, or `[Tool] ...`.\n- Fill the repository PR template completely, including behavior-change classification and test/docs checkboxes.\n- Bug-fix PRs intended for branch backports must set the version checkboxes that drive auto-backporting.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## Codex PR Review Context\n\nWhen performing a PR review (including `@codex review`), first inspect the PR\ncomments for one beginning with `<!-- module-risk-briefing -->`.\n\nIf a current briefing exists, treat it as review focus, not a finding list:\n- check the listed modules/files first;\n- validate every risk against the actual diff before reporting;\n- do not report a finding solely because the briefing cites a historical risk;\n- if the embedded `<!-- module-risk-head-sha: X -->` differs from the PR's\n  current head commit, the briefing predates the latest push: use it only as\n  historical reference, NOT as the primary review focus for the current diff,\n  and flag this in the review summary;\n- if the briefing is stale or absent, say so briefly — never silently drop the\n  historical risks, and never report one as a current finding without checking\n  the diff.\n\n## Nested Guides\n\n- [`handbook/index.md`](./handbook/index.md)\n- [`handbook/domains/index.md`](./handbook/domains/index.md)\n- [`handbook/policies/index.md`](./handbook/policies/index.md)\n- [`handbook/quality/index.md`](./handbook/quality/index.md)\n- [`be/AGENTS.md`](./be/AGENTS.md)\n- [`fe/AGENTS.md`](./fe/AGENTS.md)\n- [`docs/AGENTS.md`](./docs/AGENTS.md)\n- [`gensrc/AGENTS.md`](./gensrc/AGENTS.md)\n- [`java-extensions/AGENTS.md`](./java-extensions/AGENTS.md)\n- [`test/AGENTS.md`](./test/AGENTS.md)\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for StarRocks\n\n## Project Overview\n\nStarRocks is a high-performance, cloud-native analytical database system designed for real-time analytics and ad-hoc queries. It features a streamlined architecture with both shared-nothing and shared-data deployment modes, supporting sub-second query performance for complex analytical workloads.\n\n**Key Technologies:**\n- **Backend (BE)**: C++ - Core analytical engine, storage layer, and query execution\n- **Frontend (FE)**: Java - SQL parsing, query planning, metadata management, and coordination\n- **Java Extensions**: Java - External connectors and UDF framework\n- **Testing**: Python - Integration tests and SQL test framework\n\n## Architecture Components\n\n### Backend (be/) - C++\nThe core analytical engine responsible for data storage, processing, and query execution:\n\n**Core Components:**\n- `be/src/exec/` - Query execution operators (scan, join, aggregate, etc.)\n- `be/src/storage/` - Storage engine (tablets, rowsets, segments, compaction)\n- `be/src/exprs/` - Expression evaluation and vectorized computation\n- `be/src/formats/` - Data format support (Parquet, ORC, CSV, JSON)\n- `be/src/runtime/` - Runtime services (memory management, load balancing, stream processing)\n- `be/src/connector/` - External data source connectors (Hive, Iceberg, Delta Lake)\n- `be/src/service/` - RPC services and BE coordination\n- `be/src/common/` - Shared utilities and common data structures\n\n**Performance Focus:**\n- Vectorized query execution\n- Columnar storage format\n- Memory-efficient algorithms\n- SIMD optimizations where applicable\n\n📋 **Note:** See `be/.cursorrules` for detailed backend component breakdown\n\n### Frontend (fe/) - Java\nSQL interface and query coordination layer:\n\n**Core Components:**\n- `fe/fe-core/src/main/java/com/starrocks/`\n  - `sql/` - SQL parser, analyzer, and AST\n  - `planner/` - Query planning and optimization (CBO)\n  - `catalog/` - Metadata management (tables, partitions, statistics)\n  - `scheduler/` - Query scheduling and execution coordination\n  - `load/` - Data loading coordination (Broker Load, Stream Load, etc.)\n  - `backup/` - Backup and restore functionality\n  - `privilege/` - Authentication and authorization\n  - `qe/` - Query execution coordination and session management\n- `fe/fe-common/` - Common frontend utilities\n- `fe/plugin-common/` - Plugin framework common components\n- `fe/spark-dpp/` - Spark data preprocessing integration\n- `fe/hive-udf/` - Hive UDF compatibility layer\n\n**Key Responsibilities:**\n- Parse and validate SQL statements\n- Generate optimized query plans using Cost-Based Optimizer (CBO)\n- Manage cluster metadata and coordination\n- Handle user sessions and security\n\n📋 **Note:** See `fe/.cursorrules` for detailed frontend component breakdown\n\n### Java Extensions (java-extensions/) - Java\nExternal connectivity and extensibility:\n\n**Data Source Connectors:**\n- `hive-reader/` - Apache Hive integration\n- `iceberg-metadata-reader/` - Apache Iceberg support\n- `hudi-reader/` - Apache Hudi integration\n- `paimon-reader/` - Apache Paimon support\n- `jdbc-bridge/` - JDBC connectivity for external databases\n- `odps-reader/` - Alibaba ODPS integration\n\n**Extension Framework:**\n- `udf-extensions/` - User-Defined Function framework\n- `common-runtime/` - Shared runtime for extensions\n- `hadoop-ext/` - Hadoop ecosystem integration\n\n📋 **Note:** See `java-extensions/.cursorrules` for detailed extensions breakdown\n\n### Additional Important Directories\n\n**Generated Sources (gensrc/):**\n- `gensrc/proto/` - Protocol buffer definitions\n- `gensrc/thrift/` - Thrift interface definitions\n- `gensrc/script/` - Code generation scripts\n\n**Testing Framework (test/):**\n- `test/sql/` - SQL test cases organized by functionality\n- `test/common/` - Common test utilities\n- `test/lib/` - Test libraries and helpers\n\n**Tools and Utilities:**\n- `tools/` - Diagnostic tools, benchmarks, and utilities\n- `bin/` - Binary executables and scripts\n- `conf/` - Configuration files and templates\n- `build-support/` - Build system support files\n- `docker/` - Docker build configurations\n\n**Other Key Directories:**\n- `thirdparty/` - External dependencies and patches\n- `fs_brokers/` - File system broker implementations\n- `webroot/` - Web UI static files\n- `format-sdk/` - Format SDK for data interchange\n\n## Coding Guidelines\n\n### C++ (Backend)\n```cpp\n// Use modern C++ features (C++17/C++20)\n// Follow Google C++ Style Guide conventions\n// Use RAII for resource management\n// Prefer smart pointers over raw pointers\n// Use const-correctness\n\n// Example: Vectorized processing pattern\nStatus ColumnProcessor::process_batch(const ChunkPtr& chunk) {\n    const auto& column = chunk->get_column_by_name(\"column_name\");\n    auto result_column = std::make_shared<Column>();\n    \n    // Vectorized operation on entire column\n    for (size_t i = 0; i < chunk->num_rows(); ++i) {\n        // Process element\n    }\n    \n    return Status::OK();\n}\n```\n\n### Java (Frontend)\n```java\n// Follow Java coding conventions\n// Use dependency injection where appropriate  \n// Implement proper exception handling\n// Use builder patterns for complex objects\n// Follow existing naming conventions\n\n// Example: Query planning pattern\npublic class ScanNodePlanner extends PlanFragment {\n    @Override\n    public PlanFragment visitLogicalScanOperator(\n            OptExpression optExpression, ExecPlan context) {\n        LogicalScanOperator scanOperator = \n            (LogicalScanOperator) optExpression.getOp();\n        \n        // Create physical scan node\n        ScanNode scanNode = createScanNode(scanOperator);\n        return new PlanFragment(scanNode);\n    }\n}\n```\n\n\n## ⚠️ CRITICAL BUILD SYSTEM WARNING\n**DO NOT attempt to build or run unit tests (UT) for this project unless explicitly requested by the user.**\n\nThe build system is extremely resource-intensive and time-consuming. Building the full project can take hours and requires significant system resources.\n\n**Specific commands and files to AVOID:**\n- `build.sh` - Main build script (extremely resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-be-ut.sh` / `run-fe-ut.sh` / `run-java-exts-ut.sh` - Unit test runners\n- `docker-compose` commands - Heavy resource usage\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\n**Focus on code analysis and targeted changes instead of full builds.**\n\n## Important Guidelines\n\n### Pull Request Requirements\n\n**PR Title Format:**\nMust include category prefix:\n- `[BugFix]` - Bug fixes and error corrections\n- `[Feature]` - New features and capabilities  \n- `[Enhancement]` - Improvements to existing functionality\n- `[Refactor]` - Code refactoring without functional changes\n- `[Test]` - Test-related changes\n- `[Doc]` - Documentation updates\n- `[Build]` - Build system and CI/CD changes\n- `[Performance]` - Performance optimizations\n\n**Example:** `[Feature] Add Apache Paimon table format support`\n\n\n### Code Review Focus Areas\n\n**Performance Considerations:**\n- Query execution efficiency\n- Memory usage patterns\n- Lock contention in concurrent scenarios\n- Network I/O optimization\n\n**Correctness Priorities:**\n- SQL standard compliance\n- Data type handling accuracy\n- Transaction consistency\n- Error handling completeness\n\n**Security Considerations:**\n- Input validation and sanitization\n- Authentication and authorization\n- Resource usage limits\n- Information leak prevention\n\n## Common Development Patterns\n\n### Adding New SQL Functions\n1. Define function signature in `fe/fe-core/src/main/java/com/starrocks/catalog/FunctionSet.java`\n2. Implement evaluation logic in `be/src/exprs/`\n3. Add comprehensive tests in `test/sql/test_functions/`\n\n### Adding New Data Source Connectors\n1. Implement connector interface in `java-extensions/`\n2. Add metadata reader and schema handling\n3. Integrate with query planner in `fe/fe-core/src/main/java/com/starrocks/connector/`\n4. Add integration tests\n\n### Query Optimization Improvements\n1. Analyze optimizer rules in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/rule/`\n2. Update cost model if needed in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/cost/`\n3. Add test cases in `test/sql/test_optimizer/`\n\n## Documentation References\n\n- **Contributing Guide**: [`CONTRIBUTING.md`](../CONTRIBUTING.md)\n- **Development Setup**: [StarRocks Documentation](https://docs.starrocks.io/docs/developers/)\n- **Architecture Overview**: [README.md](../README.md#architecture-overview)\n- **PR Template**: [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md)\n\n## Quick Reference\n\n**Key File Extensions:**\n- `.cpp`, `.h`, `.cc` - C++ backend code\n- `.java` - Java frontend/extensions code  \n- `.sql` - SQL test cases\n- `.py` - Python test scripts\n- `.proto` - Protocol buffer definitions\n- `.thrift` - Thrift interface definitions\n\n**Important Configuration:**\n- `conf/` - Runtime configuration templates\n- `gensrc/` - Auto-generated code from IDL definitions\n- `thirdparty/` - External dependencies\n\n**Testing Structure:**\n- `test/sql/` - SQL correctness tests organized by functionality\n- `be/test/` - C++ unit tests\n- `fe/fe-core/src/test/` - Java unit tests\n\n**Build System Files to Avoid:**\n- `build.sh` - Main build script (very resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-*-ut.sh` - Unit test runners\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\nThis project prioritizes **performance**, **correctness**, and **scalability**. When contributing, consider the impact on query performance and ensure changes maintain SQL standard compliance."},"files":{"AGENTS.md":"# AGENTS.md - StarRocks\n\nAgent entrypoint for this repository. Start with the nearest nested `AGENTS.md`; use this file for repo-wide rules only.\n\n## Read Order\n\n1. Read [`handbook/index.md`](./handbook/index.md) for repo topology, architecture entrypoints, and active engineering plans. If `handbook/plans/local/index.md` exists, treat it as a checkout-local extension to the tracked plan set after reading [`handbook/plans/index.md`](./handbook/plans/index.md).\n2. Read the nearest nested `AGENTS.md`.\n3. For Backend work, read [`handbook/domains/backend.md`](./handbook/domains/backend.md) and [`be/AGENTS.md`](./be/AGENTS.md).\n4. For Frontend work, read [`handbook/domains/frontend.md`](./handbook/domains/frontend.md) and [`fe/AGENTS.md`](./fe/AGENTS.md).\n5. For SQL tests, docs, generated code, Java extensions, or CI/tooling, read the matching `handbook/domains/` page before the nested guide.\n\n## Repo Map\n\n- `be/`: C++ backend for execution, storage, services, and data processing.\n- `fe/`: Java frontend for parsing, planning, metadata, and coordination.\n- `gensrc/`: generated thrift/protobuf code.\n- `test/`: SQL integration tests.\n- `docs/`: user and admin documentation.\n- `java-extensions/`: JNI and external source integrations.\n\n## Quick Commands\n\n```bash\n# Build backend or frontend\n./build.sh --be\n./build.sh --fe\n\n# Run backend or frontend unit tests\n./run-be-ut.sh\n./run-fe-ut.sh\n\n# Run SQL integration tests\ncd test && python3 run.py -v\n```\n\n## Repo-Wide Invariants\n\n- Do not hand-edit generated outputs in `gensrc/` unless the generator workflow explicitly requires it.\n- Protobuf fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- Thrift fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- User-facing config or metric changes must update the matching docs in `docs/en/` and `docs/zh/` when applicable.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## PR Contract\n\n- Commit messages: English, imperative, concise.\n- PR titles: `[BugFix] ...`, `[Feature] ...`, `[Enhancement] ...`, `[Refactor] ...`, `[UT] ...`, `[Doc] ...`, or `[Tool] ...`.\n- Fill the repository PR template completely, including behavior-change classification and test/docs checkboxes.\n- Bug-fix PRs intended for branch backports must set the version checkboxes that drive auto-backporting.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## Codex PR Review Context\n\nWhen performing a PR review (including `@codex review`), first inspect the PR\ncomments for one beginning with `<!-- module-risk-briefing -->`.\n\nIf a current briefing exists, treat it as review focus, not a finding list:\n- check the listed modules/files first;\n- validate every risk against the actual diff before reporting;\n- do not report a finding solely because the briefing cites a historical risk;\n- if the embedded `<!-- module-risk-head-sha: X -->` differs from the PR's\n  current head commit, the briefing predates the latest push: use it only as\n  historical reference, NOT as the primary review focus for the current diff,\n  and flag this in the review summary;\n- if the briefing is stale or absent, say so briefly — never silently drop the\n  historical risks, and never report one as a current finding without checking\n  the diff.\n\n## Nested Guides\n\n- [`handbook/index.md`](./handbook/index.md)\n- [`handbook/domains/index.md`](./handbook/domains/index.md)\n- [`handbook/policies/index.md`](./handbook/policies/index.md)\n- [`handbook/quality/index.md`](./handbook/quality/index.md)\n- [`be/AGENTS.md`](./be/AGENTS.md)\n- [`fe/AGENTS.md`](./fe/AGENTS.md)\n- [`docs/AGENTS.md`](./docs/AGENTS.md)\n- [`gensrc/AGENTS.md`](./gensrc/AGENTS.md)\n- [`java-extensions/AGENTS.md`](./java-extensions/AGENTS.md)\n- [`test/AGENTS.md`](./test/AGENTS.md)\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for StarRocks\n\n## Project Overview\n\nStarRocks is a high-performance, cloud-native analytical database system designed for real-time analytics and ad-hoc queries. It features a streamlined architecture with both shared-nothing and shared-data deployment modes, supporting sub-second query performance for complex analytical workloads.\n\n**Key Technologies:**\n- **Backend (BE)**: C++ - Core analytical engine, storage layer, and query execution\n- **Frontend (FE)**: Java - SQL parsing, query planning, metadata management, and coordination\n- **Java Extensions**: Java - External connectors and UDF framework\n- **Testing**: Python - Integration tests and SQL test framework\n\n## Architecture Components\n\n### Backend (be/) - C++\nThe core analytical engine responsible for data storage, processing, and query execution:\n\n**Core Components:**\n- `be/src/exec/` - Query execution operators (scan, join, aggregate, etc.)\n- `be/src/storage/` - Storage engine (tablets, rowsets, segments, compaction)\n- `be/src/exprs/` - Expression evaluation and vectorized computation\n- `be/src/formats/` - Data format support (Parquet, ORC, CSV, JSON)\n- `be/src/runtime/` - Runtime services (memory management, load balancing, stream processing)\n- `be/src/connector/` - External data source connectors (Hive, Iceberg, Delta Lake)\n- `be/src/service/` - RPC services and BE coordination\n- `be/src/common/` - Shared utilities and common data structures\n\n**Performance Focus:**\n- Vectorized query execution\n- Columnar storage format\n- Memory-efficient algorithms\n- SIMD optimizations where applicable\n\n📋 **Note:** See `be/.cursorrules` for detailed backend component breakdown\n\n### Frontend (fe/) - Java\nSQL interface and query coordination layer:\n\n**Core Components:**\n- `fe/fe-core/src/main/java/com/starrocks/`\n  - `sql/` - SQL parser, analyzer, and AST\n  - `planner/` - Query planning and optimization (CBO)\n  - `catalog/` - Metadata management (tables, partitions, statistics)\n  - `scheduler/` - Query scheduling and execution coordination\n  - `load/` - Data loading coordination (Broker Load, Stream Load, etc.)\n  - `backup/` - Backup and restore functionality\n  - `privilege/` - Authentication and authorization\n  - `qe/` - Query execution coordination and session management\n- `fe/fe-common/` - Common frontend utilities\n- `fe/plugin-common/` - Plugin framework common components\n- `fe/spark-dpp/` - Spark data preprocessing integration\n- `fe/hive-udf/` - Hive UDF compatibility layer\n\n**Key Responsibilities:**\n- Parse and validate SQL statements\n- Generate optimized query plans using Cost-Based Optimizer (CBO)\n- Manage cluster metadata and coordination\n- Handle user sessions and security\n\n📋 **Note:** See `fe/.cursorrules` for detailed frontend component breakdown\n\n### Java Extensions (java-extensions/) - Java\nExternal connectivity and extensibility:\n\n**Data Source Connectors:**\n- `hive-reader/` - Apache Hive integration\n- `iceberg-metadata-reader/` - Apache Iceberg support\n- `hudi-reader/` - Apache Hudi integration\n- `paimon-reader/` - Apache Paimon support\n- `jdbc-bridge/` - JDBC connectivity for external databases\n- `odps-reader/` - Alibaba ODPS integration\n\n**Extension Framework:**\n- `udf-extensions/` - User-Defined Function framework\n- `common-runtime/` - Shared runtime for extensions\n- `hadoop-ext/` - Hadoop ecosystem integration\n\n📋 **Note:** See `java-extensions/.cursorrules` for detailed extensions breakdown\n\n### Additional Important Directories\n\n**Generated Sources (gensrc/):**\n- `gensrc/proto/` - Protocol buffer definitions\n- `gensrc/thrift/` - Thrift interface definitions\n- `gensrc/script/` - Code generation scripts\n\n**Testing Framework (test/):**\n- `test/sql/` - SQL test cases organized by functionality\n- `test/common/` - Common test utilities\n- `test/lib/` - Test libraries and helpers\n\n**Tools and Utilities:**\n- `tools/` - Diagnostic tools, benchmarks, and utilities\n- `bin/` - Binary executables and scripts\n- `conf/` - Configuration files and templates\n- `build-support/` - Build system support files\n- `docker/` - Docker build configurations\n\n**Other Key Directories:**\n- `thirdparty/` - External dependencies and patches\n- `fs_brokers/` - File system broker implementations\n- `webroot/` - Web UI static files\n- `format-sdk/` - Format SDK for data interchange\n\n## Coding Guidelines\n\n### C++ (Backend)\n```cpp\n// Use modern C++ features (C++17/C++20)\n// Follow Google C++ Style Guide conventions\n// Use RAII for resource management\n// Prefer smart pointers over raw pointers\n// Use const-correctness\n\n// Example: Vectorized processing pattern\nStatus ColumnProcessor::process_batch(const ChunkPtr& chunk) {\n    const auto& column = chunk->get_column_by_name(\"column_name\");\n    auto result_column = std::make_shared<Column>();\n    \n    // Vectorized operation on entire column\n    for (size_t i = 0; i < chunk->num_rows(); ++i) {\n        // Process element\n    }\n    \n    return Status::OK();\n}\n```\n\n### Java (Frontend)\n```java\n// Follow Java coding conventions\n// Use dependency injection where appropriate  \n// Implement proper exception handling\n// Use builder patterns for complex objects\n// Follow existing naming conventions\n\n// Example: Query planning pattern\npublic class ScanNodePlanner extends PlanFragment {\n    @Override\n    public PlanFragment visitLogicalScanOperator(\n            OptExpression optExpression, ExecPlan context) {\n        LogicalScanOperator scanOperator = \n            (LogicalScanOperator) optExpression.getOp();\n        \n        // Create physical scan node\n        ScanNode scanNode = createScanNode(scanOperator);\n        return new PlanFragment(scanNode);\n    }\n}\n```\n\n\n## ⚠️ CRITICAL BUILD SYSTEM WARNING\n**DO NOT attempt to build or run unit tests (UT) for this project unless explicitly requested by the user.**\n\nThe build system is extremely resource-intensive and time-consuming. Building the full project can take hours and requires significant system resources.\n\n**Specific commands and files to AVOID:**\n- `build.sh` - Main build script (extremely resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-be-ut.sh` / `run-fe-ut.sh` / `run-java-exts-ut.sh` - Unit test runners\n- `docker-compose` commands - Heavy resource usage\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\n**Focus on code analysis and targeted changes instead of full builds.**\n\n## Important Guidelines\n\n### Pull Request Requirements\n\n**PR Title Format:**\nMust include category prefix:\n- `[BugFix]` - Bug fixes and error corrections\n- `[Feature]` - New features and capabilities  \n- `[Enhancement]` - Improvements to existing functionality\n- `[Refactor]` - Code refactoring without functional changes\n- `[Test]` - Test-related changes\n- `[Doc]` - Documentation updates\n- `[Build]` - Build system and CI/CD changes\n- `[Performance]` - Performance optimizations\n\n**Example:** `[Feature] Add Apache Paimon table format support`\n\n\n### Code Review Focus Areas\n\n**Performance Considerations:**\n- Query execution efficiency\n- Memory usage patterns\n- Lock contention in concurrent scenarios\n- Network I/O optimization\n\n**Correctness Priorities:**\n- SQL standard compliance\n- Data type handling accuracy\n- Transaction consistency\n- Error handling completeness\n\n**Security Considerations:**\n- Input validation and sanitization\n- Authentication and authorization\n- Resource usage limits\n- Information leak prevention\n\n## Common Development Patterns\n\n### Adding New SQL Functions\n1. Define function signature in `fe/fe-core/src/main/java/com/starrocks/catalog/FunctionSet.java`\n2. Implement evaluation logic in `be/src/exprs/`\n3. Add comprehensive tests in `test/sql/test_functions/`\n\n### Adding New Data Source Connectors\n1. Implement connector interface in `java-extensions/`\n2. Add metadata reader and schema handling\n3. Integrate with query planner in `fe/fe-core/src/main/java/com/starrocks/connector/`\n4. Add integration tests\n\n### Query Optimization Improvements\n1. Analyze optimizer rules in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/rule/`\n2. Update cost model if needed in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/cost/`\n3. Add test cases in `test/sql/test_optimizer/`\n\n## Documentation References\n\n- **Contributing Guide**: [`CONTRIBUTING.md`](../CONTRIBUTING.md)\n- **Development Setup**: [StarRocks Documentation](https://docs.starrocks.io/docs/developers/)\n- **Architecture Overview**: [README.md](../README.md#architecture-overview)\n- **PR Template**: [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md)\n\n## Quick Reference\n\n**Key File Extensions:**\n- `.cpp`, `.h`, `.cc` - C++ backend code\n- `.java` - Java frontend/extensions code  \n- `.sql` - SQL test cases\n- `.py` - Python test scripts\n- `.proto` - Protocol buffer definitions\n- `.thrift` - Thrift interface definitions\n\n**Important Configuration:**\n- `conf/` - Runtime configuration templates\n- `gensrc/` - Auto-generated code from IDL definitions\n- `thirdparty/` - External dependencies\n\n**Testing Structure:**\n- `test/sql/` - SQL correctness tests organized by functionality\n- `be/test/` - C++ unit tests\n- `fe/fe-core/src/test/` - Java unit tests\n\n**Build System Files to Avoid:**\n- `build.sh` - Main build script (very resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-*-ut.sh` - Unit test runners\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\nThis project prioritizes **performance**, **correctness**, and **scalability**. When contributing, consider the impact on query performance and ensure changes maintain SQL standard compliance."},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md - StarRocks\n\nAgent entrypoint for this repository. Start with the nearest nested `AGENTS.md`; use this file for repo-wide rules only.\n\n## Read Order\n\n1. Read [`handbook/index.md`](./handbook/index.md) for repo topology, architecture entrypoints, and active engineering plans. If `handbook/plans/local/index.md` exists, treat it as a checkout-local extension to the tracked plan set after reading [`handbook/plans/index.md`](./handbook/plans/index.md).\n2. Read the nearest nested `AGENTS.md`.\n3. For Backend work, read [`handbook/domains/backend.md`](./handbook/domains/backend.md) and [`be/AGENTS.md`](./be/AGENTS.md).\n4. For Frontend work, read [`handbook/domains/frontend.md`](./handbook/domains/frontend.md) and [`fe/AGENTS.md`](./fe/AGENTS.md).\n5. For SQL tests, docs, generated code, Java extensions, or CI/tooling, read the matching `handbook/domains/` page before the nested guide.\n\n## Repo Map\n\n- `be/`: C++ backend for execution, storage, services, and data processing.\n- `fe/`: Java frontend for parsing, planning, metadata, and coordination.\n- `gensrc/`: generated thrift/protobuf code.\n- `test/`: SQL integration tests.\n- `docs/`: user and admin documentation.\n- `java-extensions/`: JNI and external source integrations.\n\n## Quick Commands\n\n```bash\n# Build backend or frontend\n./build.sh --be\n./build.sh --fe\n\n# Run backend or frontend unit tests\n./run-be-ut.sh\n./run-fe-ut.sh\n\n# Run SQL integration tests\ncd test && python3 run.py -v\n```\n\n## Repo-Wide Invariants\n\n- Do not hand-edit generated outputs in `gensrc/` unless the generator workflow explicitly requires it.\n- Protobuf fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- Thrift fields must stay optional/repeated; never add `required` and never reuse ordinals.\n- User-facing config or metric changes must update the matching docs in `docs/en/` and `docs/zh/` when applicable.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## PR Contract\n\n- Commit messages: English, imperative, concise.\n- PR titles: `[BugFix] ...`, `[Feature] ...`, `[Enhancement] ...`, `[Refactor] ...`, `[UT] ...`, `[Doc] ...`, or `[Tool] ...`.\n- Fill the repository PR template completely, including behavior-change classification and test/docs checkboxes.\n- Bug-fix PRs intended for branch backports must set the version checkboxes that drive auto-backporting.\n- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.\n\n## Codex PR Review Context\n\nWhen performing a PR review (including `@codex review`), first inspect the PR\ncomments for one beginning with `<!-- module-risk-briefing -->`.\n\nIf a current briefing exists, treat it as review focus, not a finding list:\n- check the listed modules/files first;\n- validate every risk against the actual diff before reporting;\n- do not report a finding solely because the briefing cites a historical risk;\n- if the embedded `<!-- module-risk-head-sha: X -->` differs from the PR's\n  current head commit, the briefing predates the latest push: use it only as\n  historical reference, NOT as the primary review focus for the current diff,\n  and flag this in the review summary;\n- if the briefing is stale or absent, say so briefly — never silently drop the\n  historical risks, and never report one as a current finding without checking\n  the diff.\n\n## Nested Guides\n\n- [`handbook/index.md`](./handbook/index.md)\n- [`handbook/domains/index.md`](./handbook/domains/index.md)\n- [`handbook/policies/index.md`](./handbook/policies/index.md)\n- [`handbook/quality/index.md`](./handbook/quality/index.md)\n- [`be/AGENTS.md`](./be/AGENTS.md)\n- [`fe/AGENTS.md`](./fe/AGENTS.md)\n- [`docs/AGENTS.md`](./docs/AGENTS.md)\n- [`gensrc/AGENTS.md`](./gensrc/AGENTS.md)\n- [`java-extensions/AGENTS.md`](./java-extensions/AGENTS.md)\n- [`test/AGENTS.md`](./test/AGENTS.md)\n","category":"root","tokens":978},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# GitHub Copilot Instructions for StarRocks\n\n## Project Overview\n\nStarRocks is a high-performance, cloud-native analytical database system designed for real-time analytics and ad-hoc queries. It features a streamlined architecture with both shared-nothing and shared-data deployment modes, supporting sub-second query performance for complex analytical workloads.\n\n**Key Technologies:**\n- **Backend (BE)**: C++ - Core analytical engine, storage layer, and query execution\n- **Frontend (FE)**: Java - SQL parsing, query planning, metadata management, and coordination\n- **Java Extensions**: Java - External connectors and UDF framework\n- **Testing**: Python - Integration tests and SQL test framework\n\n## Architecture Components\n\n### Backend (be/) - C++\nThe core analytical engine responsible for data storage, processing, and query execution:\n\n**Core Components:**\n- `be/src/exec/` - Query execution operators (scan, join, aggregate, etc.)\n- `be/src/storage/` - Storage engine (tablets, rowsets, segments, compaction)\n- `be/src/exprs/` - Expression evaluation and vectorized computation\n- `be/src/formats/` - Data format support (Parquet, ORC, CSV, JSON)\n- `be/src/runtime/` - Runtime services (memory management, load balancing, stream processing)\n- `be/src/connector/` - External data source connectors (Hive, Iceberg, Delta Lake)\n- `be/src/service/` - RPC services and BE coordination\n- `be/src/common/` - Shared utilities and common data structures\n\n**Performance Focus:**\n- Vectorized query execution\n- Columnar storage format\n- Memory-efficient algorithms\n- SIMD optimizations where applicable\n\n📋 **Note:** See `be/.cursorrules` for detailed backend component breakdown\n\n### Frontend (fe/) - Java\nSQL interface and query coordination layer:\n\n**Core Components:**\n- `fe/fe-core/src/main/java/com/starrocks/`\n  - `sql/` - SQL parser, analyzer, and AST\n  - `planner/` - Query planning and optimization (CBO)\n  - `catalog/` - Metadata management (tables, partitions, statistics)\n  - `scheduler/` - Query scheduling and execution coordination\n  - `load/` - Data loading coordination (Broker Load, Stream Load, etc.)\n  - `backup/` - Backup and restore functionality\n  - `privilege/` - Authentication and authorization\n  - `qe/` - Query execution coordination and session management\n- `fe/fe-common/` - Common frontend utilities\n- `fe/plugin-common/` - Plugin framework common components\n- `fe/spark-dpp/` - Spark data preprocessing integration\n- `fe/hive-udf/` - Hive UDF compatibility layer\n\n**Key Responsibilities:**\n- Parse and validate SQL statements\n- Generate optimized query plans using Cost-Based Optimizer (CBO)\n- Manage cluster metadata and coordination\n- Handle user sessions and security\n\n📋 **Note:** See `fe/.cursorrules` for detailed frontend component breakdown\n\n### Java Extensions (java-extensions/) - Java\nExternal connectivity and extensibility:\n\n**Data Source Connectors:**\n- `hive-reader/` - Apache Hive integration\n- `iceberg-metadata-reader/` - Apache Iceberg support\n- `hudi-reader/` - Apache Hudi integration\n- `paimon-reader/` - Apache Paimon support\n- `jdbc-bridge/` - JDBC connectivity for external databases\n- `odps-reader/` - Alibaba ODPS integration\n\n**Extension Framework:**\n- `udf-extensions/` - User-Defined Function framework\n- `common-runtime/` - Shared runtime for extensions\n- `hadoop-ext/` - Hadoop ecosystem integration\n\n📋 **Note:** See `java-extensions/.cursorrules` for detailed extensions breakdown\n\n### Additional Important Directories\n\n**Generated Sources (gensrc/):**\n- `gensrc/proto/` - Protocol buffer definitions\n- `gensrc/thrift/` - Thrift interface definitions\n- `gensrc/script/` - Code generation scripts\n\n**Testing Framework (test/):**\n- `test/sql/` - SQL test cases organized by functionality\n- `test/common/` - Common test utilities\n- `test/lib/` - Test libraries and helpers\n\n**Tools and Utilities:**\n- `tools/` - Diagnostic tools, benchmarks, and utilities\n- `bin/` - Binary executables and scripts\n- `conf/` - Configuration files and templates\n- `build-support/` - Build system support files\n- `docker/` - Docker build configurations\n\n**Other Key Directories:**\n- `thirdparty/` - External dependencies and patches\n- `fs_brokers/` - File system broker implementations\n- `webroot/` - Web UI static files\n- `format-sdk/` - Format SDK for data interchange\n\n## Coding Guidelines\n\n### C++ (Backend)\n```cpp\n// Use modern C++ features (C++17/C++20)\n// Follow Google C++ Style Guide conventions\n// Use RAII for resource management\n// Prefer smart pointers over raw pointers\n// Use const-correctness\n\n// Example: Vectorized processing pattern\nStatus ColumnProcessor::process_batch(const ChunkPtr& chunk) {\n    const auto& column = chunk->get_column_by_name(\"column_name\");\n    auto result_column = std::make_shared<Column>();\n    \n    // Vectorized operation on entire column\n    for (size_t i = 0; i < chunk->num_rows(); ++i) {\n        // Process element\n    }\n    \n    return Status::OK();\n}\n```\n\n### Java (Frontend)\n```java\n// Follow Java coding conventions\n// Use dependency injection where appropriate  \n// Implement proper exception handling\n// Use builder patterns for complex objects\n// Follow existing naming conventions\n\n// Example: Query planning pattern\npublic class ScanNodePlanner extends PlanFragment {\n    @Override\n    public PlanFragment visitLogicalScanOperator(\n            OptExpression optExpression, ExecPlan context) {\n        LogicalScanOperator scanOperator = \n            (LogicalScanOperator) optExpression.getOp();\n        \n        // Create physical scan node\n        ScanNode scanNode = createScanNode(scanOperator);\n        return new PlanFragment(scanNode);\n    }\n}\n```\n\n\n## ⚠️ CRITICAL BUILD SYSTEM WARNING\n**DO NOT attempt to build or run unit tests (UT) for this project unless explicitly requested by the user.**\n\nThe build system is extremely resource-intensive and time-consuming. Building the full project can take hours and requires significant system resources.\n\n**Specific commands and files to AVOID:**\n- `build.sh` - Main build script (extremely resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-be-ut.sh` / `run-fe-ut.sh` / `run-java-exts-ut.sh` - Unit test runners\n- `docker-compose` commands - Heavy resource usage\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\n**Focus on code analysis and targeted changes instead of full builds.**\n\n## Important Guidelines\n\n### Pull Request Requirements\n\n**PR Title Format:**\nMust include category prefix:\n- `[BugFix]` - Bug fixes and error corrections\n- `[Feature]` - New features and capabilities  \n- `[Enhancement]` - Improvements to existing functionality\n- `[Refactor]` - Code refactoring without functional changes\n- `[Test]` - Test-related changes\n- `[Doc]` - Documentation updates\n- `[Build]` - Build system and CI/CD changes\n- `[Performance]` - Performance optimizations\n\n**Example:** `[Feature] Add Apache Paimon table format support`\n\n\n### Code Review Focus Areas\n\n**Performance Considerations:**\n- Query execution efficiency\n- Memory usage patterns\n- Lock contention in concurrent scenarios\n- Network I/O optimization\n\n**Correctness Priorities:**\n- SQL standard compliance\n- Data type handling accuracy\n- Transaction consistency\n- Error handling completeness\n\n**Security Considerations:**\n- Input validation and sanitization\n- Authentication and authorization\n- Resource usage limits\n- Information leak prevention\n\n## Common Development Patterns\n\n### Adding New SQL Functions\n1. Define function signature in `fe/fe-core/src/main/java/com/starrocks/catalog/FunctionSet.java`\n2. Implement evaluation logic in `be/src/exprs/`\n3. Add comprehensive tests in `test/sql/test_functions/`\n\n### Adding New Data Source Connectors\n1. Implement connector interface in `java-extensions/`\n2. Add metadata reader and schema handling\n3. Integrate with query planner in `fe/fe-core/src/main/java/com/starrocks/connector/`\n4. Add integration tests\n\n### Query Optimization Improvements\n1. Analyze optimizer rules in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/rule/`\n2. Update cost model if needed in `fe/fe-core/src/main/java/com/starrocks/sql/optimizer/cost/`\n3. Add test cases in `test/sql/test_optimizer/`\n\n## Documentation References\n\n- **Contributing Guide**: [`CONTRIBUTING.md`](../CONTRIBUTING.md)\n- **Development Setup**: [StarRocks Documentation](https://docs.starrocks.io/docs/developers/)\n- **Architecture Overview**: [README.md](../README.md#architecture-overview)\n- **PR Template**: [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md)\n\n## Quick Reference\n\n**Key File Extensions:**\n- `.cpp`, `.h`, `.cc` - C++ backend code\n- `.java` - Java frontend/extensions code  \n- `.sql` - SQL test cases\n- `.py` - Python test scripts\n- `.proto` - Protocol buffer definitions\n- `.thrift` - Thrift interface definitions\n\n**Important Configuration:**\n- `conf/` - Runtime configuration templates\n- `gensrc/` - Auto-generated code from IDL definitions\n- `thirdparty/` - External dependencies\n\n**Testing Structure:**\n- `test/sql/` - SQL correctness tests organized by functionality\n- `be/test/` - C++ unit tests\n- `fe/fe-core/src/test/` - Java unit tests\n\n**Build System Files to Avoid:**\n- `build.sh` - Main build script (very resource intensive)\n- `build-in-docker.sh` - Docker-based build\n- `run-*-ut.sh` - Unit test runners\n- `Makefile*` - Make build files\n- `pom.xml` - Maven build files (for Java components)\n\nThis project prioritizes **performance**, **correctness**, and **scalability**. When contributing, consider the impact on query performance and ensure changes maintain SQL standard compliance.","category":".github","tokens":2406}]}