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
8348d3d2d4600ade47dbbfb05fac36e4e5f2d53b
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

8.2 KiB
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:

Rust style

Follow docs/style-guide.md for Rust style, module design, naming, and reuse guidance.

Read before changing code

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.

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.

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: 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), 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

Reference in New Issue View Git Blame Copy Permalink