AT1DB

The query planner — EXPLAIN with exact bytes

What turns a query API into a database is a planner. AT1DB's has something incumbents don't: a measured cost model. The cost of a scan is the exact bytes the query touches — computed from the per-row-group zone maps stored in the .at1 file — not an estimate from row-count histograms. EXPLAIN prints the predicted bytes per plan node; after execution the actual bytes read are attached, and for zone-map-skippable predicates the two match, because the planner and the executor use the same block math.

What the planner does

  • Predicate pushdown — sargable WHERE terms become zone-map range/equality skips, so whole row-groups are never read.
  • Projection prune — only the columns a query needs are decoded, never the whole row.
  • Cost-first join order — joins are ordered by predicted bytes/rows (build the hash table on the cheaper side, probe with the larger), left-deep.
  • EXPLAIN — predicted bytes per node, then actual bytes after the run: the cost model is checkable, not a guess.

EXPLAIN — predicted equals actual

Here a Jan–Feb date range on a date-ordered orders table skips 2 of 3 row-groups (groups 1/3), so the scan reads 39,435 bytes of a 123,431-byte file — and that is exactly the number EXPLAIN predicted.

at1db plan explain \
  "SELECT c_nation, SUM(o_totalprice) AS rev
   FROM orders JOIN customer ON o_custkey = c_custkey
   WHERE o_orderdate BETWEEN 20240101 AND 20240228
   GROUP BY c_nation ORDER BY rev DESC" \
  --table customer=customer.csv --table orders=orders.csv

EXPLAIN  (cost = bytes the query actually touches; predicted from zone maps)
  Scan customer [customer]  groups 1/1  proj ['c_custkey','c_nation']  pushdown: none
      predicted_bytes=431  (of 1,301 file)   actual_bytes=431 == predicted   rows=500
  Scan orders [orders]  groups 1/3  proj ['o_custkey','o_orderdate','o_totalprice']
      pushdown: o_orderdate in (20240101, 20240228)
      predicted_bytes=39,435  (of 123,431 file)   actual_bytes=39,435 == predicted   rows=2,252
  Join order (cost-first, left-deep): customer |><| orders
  TOTAL predicted_bytes=39,866 of 124,732 (68.0% skipped by pushdown)
  TOTAL actual_bytes=39,866

Measured, not promised

On a TPC-H-lite workload the planner is 100% correct versus DuckDB, the .at1 tables are ~1.5× smaller than Parquet-zstd, and each query touches 1.5–2.3× fewer bytesthan Parquet's own row-group-pruned read — the same zone-map method, measured apples-to-apples. The prototype executor's wall-clock currently trails DuckDB's vectorized C++ engine (the execution backend is being moved to the vectorized/C and GPU-warm-tier paths); the planner, pushdown, join-ordering and exact-bytes EXPLAIN are the part that's done and verified.

Reads and EXPLAIN need no account; running a query is metered against the connected account — same as the rest of AT-1.