Skip to content

feat(nql): GROUP BY aggregates + VALID AS OF + TRACE in browser mock parser#2

Open
Eth-Interchained wants to merge 1 commit into
masterfrom
hyperagent/nightly-2026-06-15-nql-groupby-trace
Open

feat(nql): GROUP BY aggregates + VALID AS OF + TRACE in browser mock parser#2
Eth-Interchained wants to merge 1 commit into
masterfrom
hyperagent/nightly-2026-06-15-nql-groupby-trace

Conversation

@Eth-Interchained

Copy link
Copy Markdown
Owner

Summary

  • Extends src/lib/nql.ts mock NQL parser to handle three clauses the engine has supported since v1.0.0 but the browser parser rejected with "unexpected trailing input": GROUP BY + aggregates, VALID AS OF (both positions), and TRACE [REVERSE].
  • Plan interface grows five new fields: validAsOf, trace, traceReverse, groupBy, aggregate.
  • executeNql now runs all five aggregate functions (COUNT, SUM, AVG, MIN, MAX) against seed data in-browser.
  • TRACE executes a forward/reverse linked-list walk via the named field in mock mode; adds a note directing users to the live engine for full sealed causal chains.
  • VALID AS OF adds an informational note in mock mode (full valid-time indexing needs nedbd).
  • Grammar docstring updated to reflect the full v1.0.4 engine grammar.
  • Updates COMMITS.md and ideas.md for the next maintenance turn.

Why this matters

Queries like FROM orders GROUP BY status COUNT or FROM events TRACE caused_by REVERSE are valid NQL that the live engine handles correctly. Before this PR they threw a parse error in Studio mock/offline mode, breaking the playground experience for these three clause families. Post-PR, Group By aggregations execute fully in-browser; VALID AS OF and TRACE pass through with informational notes.

Engine impact

None — pure Studio TypeScript change, no nedbd routes affected.

Studio impact

  • src/lib/nql.ts — parser + executor extended; Plan type widened.
  • Downstream code that uses Plan benefits immediately: the console no longer shows red parse errors for GROUP BY / VALID AS OF / TRACE queries.

Tests run

25 new mock tests pass (Node ESM, no build step required):

  • 12 parse-level checks: all new clauses, combinations, full kitchen-sink query
  • 3 error-path checks: missing field, missing SUM argument, trailing garbage
  • 10 execute-level checks: COUNT/SUM/AVG/MIN/MAX aggregation, WHERE + GROUP BY, group count
Result: 25 passed, 0 failed

TypeScript types are consistent — no new any casts introduced; AggFunc union type exported for downstream use.

Follow-up work

  1. Files API proxy — expose nedbd /files + /files/:filename + /files/:filename/root through Studio Express; add Files tab in Databases page (Merkle root display enables ITC/BSC anchoring).
  2. Checkpoint buttonPOST /:name/checkpoint proxy + UI button in Database detail view.
  3. Engine: reconcile pyproject.toml license — still declares Apache-2.0 but LICENSE is BSL; fix metadata to avoid package-index confusion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant