chdb AGENTS.md

AGENTS.md — chDB

This file captures the design and testing principles of the chdb-ds (DataStore) layer for AI coding agents working on this repository and follows the agents.md open standard.

For setup, build commands, the modify-then-test workflow, PR conventions, CI matrix, security, and other contributor mechanics, see CONTRIBUTING.md.

---

1. Fully lazy execution architecture

• All methods returning DataFrame or Series should return Lazy objects (such as DataStore, LazySeries).
• Defer execution until results are actually needed.
• Preserve the ability to select the optimal execution engine (pandas vs chDB / SQL) at execution stage.
• API style does not determine execution engine — pandas-style, Pythonic, SQL terminology should all compile to the same optimised backend execution.
• Final execute stage selects pandas or chDB ExecutionEngine based on the config system.

2. Natural execution triggering (explicit calls prohibited)

• Prohibit explicit calls to _execute().
• Avoid explicit conversions like to_df(), to_list(), to_pandas() as much as possible.
• Execution is triggered through natural means:
  • .columns — get column names
  • len() — get length
  • .index — get index
  • repr() / print() — display results
  • __iter__ — iteration
  • .equals() — comparison

3. Unified architecture, simplicity first

• Do not consider backward compatibility — first priority is architectural simplicity and elegance.
• Don't create split class hierarchies for different execution engines.
• ColumnExpr uniformly wraps all expression types.
• Handle lazy execution through unified LazySeries, LazyGroupBy, etc.
• LazyOp uniformly manages all lazy operations.
• Avoid duplicate definitions; keep code structure clear with single responsibility.

4. Testing principles

Philosophy:

• Discovered problems are opportunities to improve the library.
• Analyse problems from an architectural perspective — don't easily modify tests just to pass them.
• Using reset_index() in tests to mask problems = DataStore bug, not correct test writing.
• Don't obsess over container type differences between DataFrame and DataStore.