rust/greptimedb
1
0
Fork 0
mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-11-14 06:46:56 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
dfd052605d760707cc2f869bdd05a3bb0eaddeb4
greptimedb/AGENTS.md
T
discord9 77a7d099e6 docs(promql): add a map for src/promql (#9796) 
* docs(promql): add a map for src/promql

`src/promql` has no guide of its own, and the two things that cost the most to
learn the hard way are not visible from any one file: which of the two
evaluation paths is live, and what has to line up for a new extension node to
reach a datanode at all.

The map records the module layout, that coupling (substrait payload branch,
physical planner branch, `Commutativity` arm), the native model's reachability,
and the gotchas that fail silently: a missing commutativity arm, a label set
that closes twice under one label, a raw frame decoded with a binding other than
the one it was written with.

It describes mechanisms and where they live, not which branch or PR adds what,
so it stays true as the surrounding work lands.

Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com>

* docs(promql): correct what the frame schema does and does not say

Two claims in the map were wrong about the code it describes.

The guide said a raw frame's schema metadata explains how to decode the primary
key. It does not: the metadata carries the format keys only — layout, content,
labels, time — and the decoder compares those and the field list, never a label
identity. `unpack_raw_series` still requires the caller's `RawLabelSource`, so
the guide now says to decode with the binding the stream was produced under,
which is the mistake it exists to prevent. A future decode descriptor can be
described here once it is in the base and this text can describe the API that
actually exists.

The raw-scan gap named one way past the partition problem as though it were the
only one. `RegionScanExec::try_to_series_scan` documents the other — finish
partition preparation before converting — so both are stated now, with the
scanner-side override kept as the actual requirement.

Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com>

* docs(promql): say the storage producer exists and name what is left

The "cannot be planned" bullet listed the scanner-side override as missing,
but mito2 implements `RegionScanner::raw_series_schema` — #9669 landed it, so
the trait's `Ok(None)` default only refuses engines that have not implemented
it. Listing an implemented override as a gap misreads how far the raw path
actually reaches.

Separate the two things: the storage producer is available, and what is missing
is planner wiring plus the partition-preparation order. Merge current narthex in
so the paragraph describes the branch it will land on rather than a stale base.

Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com>

---------

Signed-off-by: discord9 <55937128+discord9@users.noreply.github.com>
2026-10-21 17:02:18 +08:00

166 lines
8.2 KiB
Markdown
Raw Blame History

# AGENTS.md
Guidance for coding agents (Claude Code, Codex, ...) and contributors working in
this repository. `CLAUDE.md` is a symlink to this file. If `.local/AGENTS.md` or
`.local/CLAUDE.md` is present, you **MUST** read it as well — it holds personal
or machine-local overrides (gitignored, not shared). To record a personal or
machine-local override, write it to `.local/AGENTS.md` (create `.local/` and the
file if absent), not to this shared file.
GreptimeDB is an open-source, cloud-native observability database for unified
collection and analysis of metrics, logs, and traces. It is written in Rust and
provides sub-second querying at PB scale with high cost efficiency.
## Core commands
| Task | Command |
| --- | --- |
| Build (debug) | `make build` |
| Build (release) | `make build RELEASE=true` |
| Run standalone | `cargo run -- standalone start` |
| Targeted Rust tests | `cargo nextest run -p <package>` (preferred over `cargo test`) |
| Full local Rust suite | `make test` |
| SQL tests | `cargo sqlness bare` (single case: `cargo sqlness bare -t <name>`) |
| Format | `make fmt` (and `make fmt-toml` for TOML) |
| Lint | `make clippy` (= `cargo clippy --workspace --all-targets --all-features -- -D warnings`) |
| Type check | `make check` |
Toolchain: Rust (stable, pinned by `rust-toolchain.toml`), Protobuf compiler (>= 3.15), C/C++ build essentials.
Install the test runner with `cargo install cargo-nextest --locked`.
## Repo map
GreptimeDB is a Cargo workspace rooted at the repository; most crates live under
`src/` (plus `tests-fuzz`, `tests-integration`, `tests/runner`). Key areas:
- **Frontend / protocol**: `src/frontend/` (request orchestration), `src/servers/`
(wire protocols), `src/sql/` (SQL parsing)
- **Storage engines**: `src/mito2/` (main time-series engine), `src/metric-engine/`
(metrics), `src/file-engine/`
- **Coordination**: `src/meta-srv/` (metadata & cluster control), `src/meta-client/`
- **Execution / statements**: `src/operator/` (DDL/DML, request conversion, procedures)
- **Stream / transform**: `src/flow/` (continuous aggregation), `src/pipeline/`
- **Query / index**: `src/query/`, `src/promql/`, `src/index/`
- **Shared**: `src/common/`, `src/datatypes/`, `src/store-api/` (engine contract),
`src/catalog/`, `src/table/`
Before editing a path, read every `AGENTS.md` from the repository root down to
that path. The root guide always applies; a nested guide adds or overrides rules
for its subtree. Changes spanning multiple subtrees must follow every applicable
guide.
`AGENTS.md` files are maps, not manuals. Keep them short and stable: record
where code lives, important boundaries or change-coupling, high-cost gotchas,
and the validation entry point. Implementation details belong in code. Do not
copy exhaustive test lists or workflow logic; link to the source of truth.
High-change areas and specialized test suites carry their own `AGENTS.md` with
a module map, read/write paths, change-coupling points, and gotchas:
- [`src/common/meta/AGENTS.md`](src/common/meta/AGENTS.md)
- [`src/query/AGENTS.md`](src/query/AGENTS.md)
- [`src/servers/AGENTS.md`](src/servers/AGENTS.md)
- [`src/operator/AGENTS.md`](src/operator/AGENTS.md)
- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)
- [`src/promql/AGENTS.md`](src/promql/AGENTS.md)
- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)
- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)
- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)
- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)
- [`tests-integration/AGENTS.md`](tests-integration/AGENTS.md)
- [`tests/compatibility/AGENTS.md`](tests/compatibility/AGENTS.md)
- [`tests/perf/AGENTS.md`](tests/perf/AGENTS.md)
## Rust style
Follow [`docs/style-guide.md`](docs/style-guide.md) for Rust style, module
design, naming, and reuse guidance.
## Read before changing code
- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —
repo-wide rules that are easy to violate and expensive to get wrong (persisted/
wire format compatibility, crate layering, async runtimes, error handling,
feature gating, the DataFusion fork).
- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated
artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,
Grafana dashboards, proto).
- [`docs/style-guide.md`](docs/style-guide.md) — code style.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.
## High-signal entry points
- Main binary: `src/cmd/src/bin/greptime.rs`
- Configuration: `src/common/config/`, example TOMLs in `config/`
- Error handling: `src/common/error/` (`ErrorExt`, `StatusCode`)
- Protocol implementations: `src/servers/src/`
## Worktree safety
- Check `git status --short` before editing. Preserve unrelated tracked changes
and untracked files; re-read files changed by another process.
- Do not rewrite history, force-push, or remove files in bulk unless the user
explicitly requests it.
- Update generated artifacts only through the generators documented in
[`.agents/generated-files.md`](.agents/generated-files.md).
## Validation by change type
Use the narrowest command that covers the change, then expand only when its
blast radius requires it.
| Change | Minimum validation |
| --- | --- |
| One Rust crate | `cargo nextest run -p <package>` |
| Cross-workspace Rust behavior | `make test`; inspect `.github/workflows/rust.yml` when CI parity matters |
| SQL parsing, planning, execution, or output | `cargo sqlness bare -t <case>`; inspect regenerated `.result` files |
| Persisted metadata or wire format | Add/run a case under `tests/compatibility/`; follow its `README.md` and `AGENTS.md` |
| Public configuration | Update example TOMLs, loading/serialization snapshots, and docs; run `make config-docs` |
| Query regression harness or DSL | Follow `tests/perf/AGENTS.md` |
| Enterprise-gated code | Build/test with `--features enterprise` where applicable and run `make check-enterprise-license` |
For import/export, COPY, or snapshot-storage changes, follow the Windows
portability and validation guidance in
[`tests-integration/AGENTS.md`](tests-integration/AGENTS.md).
## Before opening a PR
1. If you added a `.rs`, `.py`, or `.ts` file, apply and verify its license
header with `hawkeye format` followed by `hawkeye check`. Use the inception
year from `licenserc.toml`, not the current year.
2. `make fmt`
3. `make clippy`
4. `make test`
5. `make check-udeps` (run `make fix-udeps` if it reports unused dependencies).
6. If you added or changed a public configuration option, update the applicable
example TOMLs, configuration-loading and serialized-config snapshot tests,
and related user-facing documentation. Run `make config-docs` (needs Docker)
and commit the regenerated `config/config.md`.
7. If you changed a persisted or wire format, add a compatibility test case (see
`.agents/architecture-invariants.md`).
8. If you added or gated an enterprise-only file, give it the enterprise license
header, list it in `licenserc-enterprise.toml` (`includes`) and
`licenserc.toml` (`excludes`), and run `make check-enterprise-license`.
9. Use a conventional-commit title, sign off commits (`git commit -s`), and sign
the CLA.
10. When creating or updating a pull request, follow
[`.github/pull_request_template.md`](.github/pull_request_template.md): include
the CLA statement, fill the change-intention section with enough detail, and
update checklist items accurately. "This PR requires documentation updates"
refers to the official docs site repository
([`GreptimeTeam/docs`](https://github.com/GreptimeTeam/docs)), not to rustdoc
or comments in this repo. Check it only when that site would be wrong or
incomplete without a matching change; a change users cannot observe does not
need it.
11. If the change must also land on release branches, add the matching
`backport-<target>` labels (e.g. `backport-v1.3` targets `release/v1.3`). The
Backport workflow (`.github/workflows/backport.yml`) cherry-picks a merged PR
onto each target branch and opens a backport PR automatically; on conflicts
it aborts and files an issue for a manual backport.
## More
- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))
- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)
- How-to guides: [`docs/how-to/`](docs/how-to/)
Reference in New Issue View Git Blame Copy Permalink