{"owner":"GreptimeTeam","repo":"greptimedb","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for coding agents (Claude Code, Codex, ...) and contributors working in\nthis repository. `CLAUDE.md` is a symlink to this file. If `.local/AGENTS.md` or\n`.local/CLAUDE.md` is present, you **MUST** read it as well — it holds personal\nor machine-local overrides (gitignored, not shared). To record a personal or\nmachine-local override, write it to `.local/AGENTS.md` (create `.local/` and the\nfile if absent), not to this shared file.\n\nGreptimeDB is an open-source, cloud-native observability database for unified\ncollection and analysis of metrics, logs, and traces. It is written in Rust and\nprovides sub-second querying at PB scale with high cost efficiency.\n\n## Core commands\n\n| Task | Command |\n| --- | --- |\n| Build (debug) | `make build` |\n| Build (release) | `make build RELEASE=true` |\n| Run standalone | `cargo run -- standalone start` |\n| Targeted Rust tests | `cargo nextest run -p <package>` (preferred over `cargo test`) |\n| Full local Rust suite | `make test` |\n| SQL tests | `cargo sqlness bare` (single case: `cargo sqlness bare -t <name>`) |\n| Format | `make fmt` (and `make fmt-toml` for TOML) |\n| Lint | `make clippy` (= `cargo clippy --workspace --all-targets --all-features -- -D warnings`) |\n| Type check | `make check` |\n\nToolchain: Rust nightly, Protobuf compiler (>= 3.15), C/C++ build essentials.\nInstall the test runner with `cargo install cargo-nextest --locked`.\n\n## Repo map\n\nGreptimeDB is a Cargo workspace rooted at the repository; most crates live under\n`src/` (plus `tests-fuzz`, `tests-integration`, `tests/runner`). Key areas:\n\n- **Frontend / protocol**: `src/frontend/` (request orchestration), `src/servers/`\n  (wire protocols), `src/sql/` (SQL parsing)\n- **Storage engines**: `src/mito2/` (main time-series engine), `src/metric-engine/`\n  (metrics), `src/file-engine/`\n- **Coordination**: `src/meta-srv/` (metadata & cluster control), `src/meta-client/`\n- **Execution / statements**: `src/operator/` (DDL/DML, request conversion, procedures)\n- **Stream / transform**: `src/flow/` (continuous aggregation), `src/pipeline/`\n- **Query / index**: `src/query/`, `src/promql/`, `src/index/`\n- **Shared**: `src/common/`, `src/datatypes/`, `src/store-api/` (engine contract),\n  `src/catalog/`, `src/table/`\n\nBefore editing a path, read every `AGENTS.md` from the repository root down to\nthat path. The root guide always applies; a nested guide adds or overrides rules\nfor its subtree. Changes spanning multiple subtrees must follow every applicable\nguide.\n\n`AGENTS.md` files are maps, not manuals. Keep them short and stable: record\nwhere code lives, important boundaries or change-coupling, high-cost gotchas,\nand the validation entry point. Implementation details belong in code. Do not\ncopy exhaustive test lists or workflow logic; link to the source of truth.\n\nHigh-change areas and specialized test suites carry their own `AGENTS.md` with\na module map, read/write paths, change-coupling points, and gotchas:\n\n- [`src/common/meta/AGENTS.md`](src/common/meta/AGENTS.md)\n- [`src/query/AGENTS.md`](src/query/AGENTS.md)\n- [`src/servers/AGENTS.md`](src/servers/AGENTS.md)\n- [`src/operator/AGENTS.md`](src/operator/AGENTS.md)\n- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)\n- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)\n- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)\n- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)\n- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)\n- [`tests/compatibility/AGENTS.md`](tests/compatibility/AGENTS.md)\n- [`tests/perf/AGENTS.md`](tests/perf/AGENTS.md)\n\n## Read before changing code\n\n- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —\n  repo-wide rules that are easy to violate and expensive to get wrong (persisted/\n  wire format compatibility, crate layering, async runtimes, error handling,\n  feature gating, the DataFusion fork).\n- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated\n  artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,\n  Grafana dashboards, proto).\n- [`docs/style-guide.md`](docs/style-guide.md) — code style.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.\n\n## High-signal entry points\n\n- Main binary: `src/cmd/src/bin/greptime.rs`\n- Configuration: `src/common/config/`, example TOMLs in `config/`\n- Error handling: `src/common/error/` (`ErrorExt`, `StatusCode`)\n- Protocol implementations: `src/servers/src/`\n\n## Worktree safety\n\n- Check `git status --short` before editing. Preserve unrelated tracked changes\n  and untracked files; re-read files changed by another process.\n- Do not rewrite history, force-push, or remove files in bulk unless the user\n  explicitly requests it.\n- Update generated artifacts only through the generators documented in\n  [`.agents/generated-files.md`](.agents/generated-files.md).\n\n## Validation by change type\n\nUse the narrowest command that covers the change, then expand only when its\nblast radius requires it.\n\n| Change | Minimum validation |\n| --- | --- |\n| One Rust crate | `cargo nextest run -p <package>` |\n| Cross-workspace Rust behavior | `make test`; inspect `.github/workflows/rust.yml` when CI parity matters |\n| SQL parsing, planning, execution, or output | `cargo sqlness bare -t <case>`; inspect regenerated `.result` files |\n| Persisted metadata or wire format | Add/run a case under `tests/compatibility/`; follow its `README.md` and `AGENTS.md` |\n| Public configuration | Update example TOMLs, loading/serialization snapshots, and docs; run `make config-docs` |\n| Query regression harness or DSL | Follow `tests/perf/AGENTS.md` |\n| Enterprise-gated code | Build/test with `--features enterprise` where applicable and run `make check-enterprise-license` |\n\n## Before opening a PR\n\n1. If you added a `.rs`, `.py`, or `.ts` file, apply and verify its license\n   header with `hawkeye format` followed by `hawkeye check`. Use the inception\n   year from `licenserc.toml`, not the current year.\n2. `make fmt`\n3. `make clippy`\n4. `make test`\n5. `make check-udeps` (run `make fix-udeps` if it reports unused dependencies).\n6. If you added or changed a public configuration option, update the applicable\n   example TOMLs, configuration-loading and serialized-config snapshot tests,\n   and related user-facing documentation. Run `make config-docs` (needs Docker)\n   and commit the regenerated `config/config.md`.\n7. If you changed a persisted or wire format, add a compatibility test case (see\n   `.agents/architecture-invariants.md`).\n8. If you added or gated an enterprise-only file, give it the enterprise license\n   header, list it in `licenserc-enterprise.toml` (`includes`) and\n   `licenserc.toml` (`excludes`), and run `make check-enterprise-license`.\n9. Use a conventional-commit title, sign off commits (`git commit -s`), and sign\n   the CLA.\n10. When creating or updating a pull request, follow\n   [`.github/pull_request_template.md`](.github/pull_request_template.md): include\n   the CLA statement, fill the change-intention section with enough detail, and\n   update checklist items accurately.\n\n## More\n\n- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))\n- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)\n- How-to guides: [`docs/how-to/`](docs/how-to/)\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for coding agents (Claude Code, Codex, ...) and contributors working in\nthis repository. `CLAUDE.md` is a symlink to this file. If `.local/AGENTS.md` or\n`.local/CLAUDE.md` is present, you **MUST** read it as well — it holds personal\nor machine-local overrides (gitignored, not shared). To record a personal or\nmachine-local override, write it to `.local/AGENTS.md` (create `.local/` and the\nfile if absent), not to this shared file.\n\nGreptimeDB is an open-source, cloud-native observability database for unified\ncollection and analysis of metrics, logs, and traces. It is written in Rust and\nprovides sub-second querying at PB scale with high cost efficiency.\n\n## Core commands\n\n| Task | Command |\n| --- | --- |\n| Build (debug) | `make build` |\n| Build (release) | `make build RELEASE=true` |\n| Run standalone | `cargo run -- standalone start` |\n| Targeted Rust tests | `cargo nextest run -p <package>` (preferred over `cargo test`) |\n| Full local Rust suite | `make test` |\n| SQL tests | `cargo sqlness bare` (single case: `cargo sqlness bare -t <name>`) |\n| Format | `make fmt` (and `make fmt-toml` for TOML) |\n| Lint | `make clippy` (= `cargo clippy --workspace --all-targets --all-features -- -D warnings`) |\n| Type check | `make check` |\n\nToolchain: Rust nightly, Protobuf compiler (>= 3.15), C/C++ build essentials.\nInstall the test runner with `cargo install cargo-nextest --locked`.\n\n## Repo map\n\nGreptimeDB is a Cargo workspace rooted at the repository; most crates live under\n`src/` (plus `tests-fuzz`, `tests-integration`, `tests/runner`). Key areas:\n\n- **Frontend / protocol**: `src/frontend/` (request orchestration), `src/servers/`\n  (wire protocols), `src/sql/` (SQL parsing)\n- **Storage engines**: `src/mito2/` (main time-series engine), `src/metric-engine/`\n  (metrics), `src/file-engine/`\n- **Coordination**: `src/meta-srv/` (metadata & cluster control), `src/meta-client/`\n- **Execution / statements**: `src/operator/` (DDL/DML, request conversion, procedures)\n- **Stream / transform**: `src/flow/` (continuous aggregation), `src/pipeline/`\n- **Query / index**: `src/query/`, `src/promql/`, `src/index/`\n- **Shared**: `src/common/`, `src/datatypes/`, `src/store-api/` (engine contract),\n  `src/catalog/`, `src/table/`\n\nBefore editing a path, read every `AGENTS.md` from the repository root down to\nthat path. The root guide always applies; a nested guide adds or overrides rules\nfor its subtree. Changes spanning multiple subtrees must follow every applicable\nguide.\n\n`AGENTS.md` files are maps, not manuals. Keep them short and stable: record\nwhere code lives, important boundaries or change-coupling, high-cost gotchas,\nand the validation entry point. Implementation details belong in code. Do not\ncopy exhaustive test lists or workflow logic; link to the source of truth.\n\nHigh-change areas and specialized test suites carry their own `AGENTS.md` with\na module map, read/write paths, change-coupling points, and gotchas:\n\n- [`src/common/meta/AGENTS.md`](src/common/meta/AGENTS.md)\n- [`src/query/AGENTS.md`](src/query/AGENTS.md)\n- [`src/servers/AGENTS.md`](src/servers/AGENTS.md)\n- [`src/operator/AGENTS.md`](src/operator/AGENTS.md)\n- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)\n- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)\n- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)\n- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)\n- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)\n- [`tests/compatibility/AGENTS.md`](tests/compatibility/AGENTS.md)\n- [`tests/perf/AGENTS.md`](tests/perf/AGENTS.md)\n\n## Read before changing code\n\n- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —\n  repo-wide rules that are easy to violate and expensive to get wrong (persisted/\n  wire format compatibility, crate layering, async runtimes, error handling,\n  feature gating, the DataFusion fork).\n- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated\n  artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,\n  Grafana dashboards, proto).\n- [`docs/style-guide.md`](docs/style-guide.md) — code style.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.\n\n## High-signal entry points\n\n- Main binary: `src/cmd/src/bin/greptime.rs`\n- Configuration: `src/common/config/`, example TOMLs in `config/`\n- Error handling: `src/common/error/` (`ErrorExt`, `StatusCode`)\n- Protocol implementations: `src/servers/src/`\n\n## Worktree safety\n\n- Check `git status --short` before editing. Preserve unrelated tracked changes\n  and untracked files; re-read files changed by another process.\n- Do not rewrite history, force-push, or remove files in bulk unless the user\n  explicitly requests it.\n- Update generated artifacts only through the generators documented in\n  [`.agents/generated-files.md`](.agents/generated-files.md).\n\n## Validation by change type\n\nUse the narrowest command that covers the change, then expand only when its\nblast radius requires it.\n\n| Change | Minimum validation |\n| --- | --- |\n| One Rust crate | `cargo nextest run -p <package>` |\n| Cross-workspace Rust behavior | `make test`; inspect `.github/workflows/rust.yml` when CI parity matters |\n| SQL parsing, planning, execution, or output | `cargo sqlness bare -t <case>`; inspect regenerated `.result` files |\n| Persisted metadata or wire format | Add/run a case under `tests/compatibility/`; follow its `README.md` and `AGENTS.md` |\n| Public configuration | Update example TOMLs, loading/serialization snapshots, and docs; run `make config-docs` |\n| Query regression harness or DSL | Follow `tests/perf/AGENTS.md` |\n| Enterprise-gated code | Build/test with `--features enterprise` where applicable and run `make check-enterprise-license` |\n\n## Before opening a PR\n\n1. If you added a `.rs`, `.py`, or `.ts` file, apply and verify its license\n   header with `hawkeye format` followed by `hawkeye check`. Use the inception\n   year from `licenserc.toml`, not the current year.\n2. `make fmt`\n3. `make clippy`\n4. `make test`\n5. `make check-udeps` (run `make fix-udeps` if it reports unused dependencies).\n6. If you added or changed a public configuration option, update the applicable\n   example TOMLs, configuration-loading and serialized-config snapshot tests,\n   and related user-facing documentation. Run `make config-docs` (needs Docker)\n   and commit the regenerated `config/config.md`.\n7. If you changed a persisted or wire format, add a compatibility test case (see\n   `.agents/architecture-invariants.md`).\n8. If you added or gated an enterprise-only file, give it the enterprise license\n   header, list it in `licenserc-enterprise.toml` (`includes`) and\n   `licenserc.toml` (`excludes`), and run `make check-enterprise-license`.\n9. Use a conventional-commit title, sign off commits (`git commit -s`), and sign\n   the CLA.\n10. When creating or updating a pull request, follow\n   [`.github/pull_request_template.md`](.github/pull_request_template.md): include\n   the CLA statement, fill the change-intention section with enough detail, and\n   update checklist items accurately.\n\n## More\n\n- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))\n- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)\n- How-to guides: [`docs/how-to/`](docs/how-to/)\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for coding agents (Claude Code, Codex, ...) and contributors working in\nthis repository. `CLAUDE.md` is a symlink to this file. If `.local/AGENTS.md` or\n`.local/CLAUDE.md` is present, you **MUST** read it as well — it holds personal\nor machine-local overrides (gitignored, not shared). To record a personal or\nmachine-local override, write it to `.local/AGENTS.md` (create `.local/` and the\nfile if absent), not to this shared file.\n\nGreptimeDB is an open-source, cloud-native observability database for unified\ncollection and analysis of metrics, logs, and traces. It is written in Rust and\nprovides sub-second querying at PB scale with high cost efficiency.\n\n## Core commands\n\n| Task | Command |\n| --- | --- |\n| Build (debug) | `make build` |\n| Build (release) | `make build RELEASE=true` |\n| Run standalone | `cargo run -- standalone start` |\n| Targeted Rust tests | `cargo nextest run -p <package>` (preferred over `cargo test`) |\n| Full local Rust suite | `make test` |\n| SQL tests | `cargo sqlness bare` (single case: `cargo sqlness bare -t <name>`) |\n| Format | `make fmt` (and `make fmt-toml` for TOML) |\n| Lint | `make clippy` (= `cargo clippy --workspace --all-targets --all-features -- -D warnings`) |\n| Type check | `make check` |\n\nToolchain: Rust nightly, Protobuf compiler (>= 3.15), C/C++ build essentials.\nInstall the test runner with `cargo install cargo-nextest --locked`.\n\n## Repo map\n\nGreptimeDB is a Cargo workspace rooted at the repository; most crates live under\n`src/` (plus `tests-fuzz`, `tests-integration`, `tests/runner`). Key areas:\n\n- **Frontend / protocol**: `src/frontend/` (request orchestration), `src/servers/`\n  (wire protocols), `src/sql/` (SQL parsing)\n- **Storage engines**: `src/mito2/` (main time-series engine), `src/metric-engine/`\n  (metrics), `src/file-engine/`\n- **Coordination**: `src/meta-srv/` (metadata & cluster control), `src/meta-client/`\n- **Execution / statements**: `src/operator/` (DDL/DML, request conversion, procedures)\n- **Stream / transform**: `src/flow/` (continuous aggregation), `src/pipeline/`\n- **Query / index**: `src/query/`, `src/promql/`, `src/index/`\n- **Shared**: `src/common/`, `src/datatypes/`, `src/store-api/` (engine contract),\n  `src/catalog/`, `src/table/`\n\nBefore editing a path, read every `AGENTS.md` from the repository root down to\nthat path. The root guide always applies; a nested guide adds or overrides rules\nfor its subtree. Changes spanning multiple subtrees must follow every applicable\nguide.\n\n`AGENTS.md` files are maps, not manuals. Keep them short and stable: record\nwhere code lives, important boundaries or change-coupling, high-cost gotchas,\nand the validation entry point. Implementation details belong in code. Do not\ncopy exhaustive test lists or workflow logic; link to the source of truth.\n\nHigh-change areas and specialized test suites carry their own `AGENTS.md` with\na module map, read/write paths, change-coupling points, and gotchas:\n\n- [`src/common/meta/AGENTS.md`](src/common/meta/AGENTS.md)\n- [`src/query/AGENTS.md`](src/query/AGENTS.md)\n- [`src/servers/AGENTS.md`](src/servers/AGENTS.md)\n- [`src/operator/AGENTS.md`](src/operator/AGENTS.md)\n- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)\n- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)\n- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)\n- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)\n- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)\n- [`tests/compatibility/AGENTS.md`](tests/compatibility/AGENTS.md)\n- [`tests/perf/AGENTS.md`](tests/perf/AGENTS.md)\n\n## Read before changing code\n\n- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —\n  repo-wide rules that are easy to violate and expensive to get wrong (persisted/\n  wire format compatibility, crate layering, async runtimes, error handling,\n  feature gating, the DataFusion fork).\n- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated\n  artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,\n  Grafana dashboards, proto).\n- [`docs/style-guide.md`](docs/style-guide.md) — code style.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.\n\n## High-signal entry points\n\n- Main binary: `src/cmd/src/bin/greptime.rs`\n- Configuration: `src/common/config/`, example TOMLs in `config/`\n- Error handling: `src/common/error/` (`ErrorExt`, `StatusCode`)\n- Protocol implementations: `src/servers/src/`\n\n## Worktree safety\n\n- Check `git status --short` before editing. Preserve unrelated tracked changes\n  and untracked files; re-read files changed by another process.\n- Do not rewrite history, force-push, or remove files in bulk unless the user\n  explicitly requests it.\n- Update generated artifacts only through the generators documented in\n  [`.agents/generated-files.md`](.agents/generated-files.md).\n\n## Validation by change type\n\nUse the narrowest command that covers the change, then expand only when its\nblast radius requires it.\n\n| Change | Minimum validation |\n| --- | --- |\n| One Rust crate | `cargo nextest run -p <package>` |\n| Cross-workspace Rust behavior | `make test`; inspect `.github/workflows/rust.yml` when CI parity matters |\n| SQL parsing, planning, execution, or output | `cargo sqlness bare -t <case>`; inspect regenerated `.result` files |\n| Persisted metadata or wire format | Add/run a case under `tests/compatibility/`; follow its `README.md` and `AGENTS.md` |\n| Public configuration | Update example TOMLs, loading/serialization snapshots, and docs; run `make config-docs` |\n| Query regression harness or DSL | Follow `tests/perf/AGENTS.md` |\n| Enterprise-gated code | Build/test with `--features enterprise` where applicable and run `make check-enterprise-license` |\n\n## Before opening a PR\n\n1. If you added a `.rs`, `.py`, or `.ts` file, apply and verify its license\n   header with `hawkeye format` followed by `hawkeye check`. Use the inception\n   year from `licenserc.toml`, not the current year.\n2. `make fmt`\n3. `make clippy`\n4. `make test`\n5. `make check-udeps` (run `make fix-udeps` if it reports unused dependencies).\n6. If you added or changed a public configuration option, update the applicable\n   example TOMLs, configuration-loading and serialized-config snapshot tests,\n   and related user-facing documentation. Run `make config-docs` (needs Docker)\n   and commit the regenerated `config/config.md`.\n7. If you changed a persisted or wire format, add a compatibility test case (see\n   `.agents/architecture-invariants.md`).\n8. If you added or gated an enterprise-only file, give it the enterprise license\n   header, list it in `licenserc-enterprise.toml` (`includes`) and\n   `licenserc.toml` (`excludes`), and run `make check-enterprise-license`.\n9. Use a conventional-commit title, sign off commits (`git commit -s`), and sign\n   the CLA.\n10. When creating or updating a pull request, follow\n   [`.github/pull_request_template.md`](.github/pull_request_template.md): include\n   the CLA statement, fill the change-intention section with enough detail, and\n   update checklist items accurately.\n\n## More\n\n- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))\n- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)\n- How-to guides: [`docs/how-to/`](docs/how-to/)\n","category":"root","tokens":1820}]}