feat: Add opt-in OffsetPageInfo metadata for paginated GraphQL queries

[velo]

What

Adds opt-in pagination metadata for user-authored GraphQL schemas. A query whose result type is a page wrapper — an object with a list field plus a OffsetPageInfo field — returns its rows plus pagination metadata computed from a companion COUNT(*) query.

type Query {
  activityLogs(fromTime: DateTime!, toTime: DateTime!, limit: Int = 100, offset: Int = 0): ActivityLogEntryPage!
}
type ActivityLogEntryPage {
  results: [ActivityLogEntry!]
  pagination: OffsetPageInfo
}

The standard OffsetPageInfo type is auto-injected when referenced but not defined (and validated for an exact match when the user defines it):

type OffsetPageInfo {
  totalRecords: Long!
  pageSize: Int!
  currentPage: Int!
  totalPages: Int!
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  nextOffset: Int          # null when no next page; feeds straight back into `offset`
  prevOffset: Int          # null on first page
  firstEventTime: DateTime # MIN(rowtime col); null if the result has no rowtime column
  lastEventTime: DateTime  # MAX(rowtime col)
}

How

• Opt-in. Existing list queries are untouched. For inferred/no-schema mode, the new compiler setting compiler.api.paginated-results (default false) generates <Type>Page {results, pagination} wrappers plus the OffsetPageInfo type for every multi-row query and relationship; with the default the inferred schema is unchanged.
• Detection is shape-based (flexible field names): an object with exactly two fields — one a list of an object type, one of type OffsetPageInfo. Only valid for MANY query functions that declare limit/offset.
• Compiler (sqrl-planner): GraphqlSchemaWalker sees through the wrapper and validates/walks the element type against the table-function row type; GraphqlModelGenerator emits two companion aggregate queries over FROM (<baseSql>) x: countSql (COUNT(*) only) and countWithEventTimesSql (COUNT(*) + MIN/MAX over the rowtime column, absent when the result has no rowtime). OffsetPageInfoUtil injects/validates the standard type.
• Runtime (sqrl-server): SqlQuery gains nullable countSql/countWithEventTimesSql (@JsonInclude(NON_NULL) → old vertx.json still loads, existing snapshots unchanged). VertxQueryExecutionContext computes metadata lazily from the selection set: the aggregate query only runs when totalRecords/totalPages (count variant) or firstEventTime/lastEventTime (count+MIN/MAX variant) are selected, and runs in parallel with the data query. When only hasNextPage/nextOffset are selected, no aggregate runs — the data query fetches LIMIT+1 rows and the extra row is trimmed. Selecting only results (or only offset-derived fields like currentPage/hasPreviousPage) adds no extra work at all. Metadata math is a pure static method.

Tests

• PaginationMetadataTest — 7 unit cases for the metadata math (empty, first/middle/last/beyond-end pages, limit=0, event-time passthrough).
• UseCaseCompileTest/DAGWriterJsonTest — new clickstream/package-paginated.json usecase snapshots the generated paginated schema (wrappers, OffsetPageInfo, count SQL with bound parameters); all other usecase snapshots are byte-identical, proving the default is backwards compatible.
• PagedQueryIT — real-Postgres test with a recording SqlClient proving the lazy execution: no aggregate query when only results or offset-derived fields are selected, LIMIT+1 (and trimming) for hasNextPage alone, plain-COUNT variant for totals, COUNT+MIN/MAX variant for event times.
• GraphQLValidationTest — 6 new schema cases: 2 positive (auto-injected type; user-defined type with non-conventional field names + a paged relationship) and 4 negative (wrong pagination type, missing limit/offset, paged subscription, unknown element field).
• All touched-module unit tests pass; the 3 aggregate validation snapshots changed only because they enumerate every input .graphqls.

Follow-up

Runtime execution (count query + wrapper assembly) is exercised by unit tests and consistent with the existing list path, but a full-pipeline usecase under FullUseCaseIT (Postgres/Flink/Kafka containers) asserting OffsetPageInfo payloads across page boundaries is a recommended follow-up — it needs the heavy container harness.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 28.66894% with 209 lines in your changes missing coverage. Please review.
✅ Project coverage is 16.70%. Comparing base (1a5a4fb) to head (3a461bb).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...n/java/com/datasqrl/server/OffsetPageInfoUtil.java	0.00%	69 Missing ⚠️
...atasqrl/plan/global/PagedRowtimeIndexRewriter.java	0.00%	31 Missing ⚠️
...java/com/datasqrl/server/GraphqlSchemaFactory.java	0.00%	31 Missing ⚠️
...tasqrl/server/jdbc/VertxQueryExecutionContext.java	73.68%	24 Missing and 6 partials ⚠️
...ava/com/datasqrl/server/GraphqlModelGenerator.java	0.00%	15 Missing ⚠️
.../java/com/datasqrl/server/GraphqlSchemaWalker.java	0.00%	14 Missing ⚠️
...va/com/datasqrl/server/GraphqlSchemaValidator.java	0.00%	10 Missing ⚠️
.../java/com/datasqrl/compile/CompilationProcess.java	0.00%	4 Missing ⚠️
.../main/java/com/datasqrl/server/PaginationType.java	0.00%	2 Missing ⚠️
...ava/com/datasqrl/config/CompilerApiConfigImpl.java	0.00%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #2191      +/-   ##
============================================
+ Coverage     16.34%   16.70%   +0.35%     
- Complexity     1027     1061      +34     
============================================
  Files           618      620       +2     
  Lines         17910    18164     +254     
  Branches       2193     2241      +48     
============================================
+ Hits           2928     3034     +106     
- Misses        14683    14826     +143     
- Partials        299      304       +5     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[mbroecheler]

I like the idea to add this. Would be nice if we could also generate this GraphQL schema code.

Couple of thoughts:

1. I would prefer a neutral name like OffsetPageInfo instead of SqrlPagination. Since this needs to be hardcoded, we don't want sqrl to be leaking through user's API schema.
2. A critical aspect that OffsetPageInfo is computed lazily based on what users are actually selecting in their queries. In particular first/lastEventTime is expensive to compute and should only be retrieved when it is actually needed. Same for hasNextPage - which I assume is computed by fetching LIMIT +1 - we don't need to fetch that extra record if that field isn't queried. Same goes for totalRecords / totalPages.

[velo]

Would be nice if we could also generate this GraphQL schema code.

I think we would need a hint for that right?!

Or do we want to always generate as paginated?

[mbroecheler]

I think we would need a hint for that right?!

Or do we want to always generate as paginated?

Yes, but not a hint - it would be a compiler config setting to generated paginated, default false (for now to be backwards compatible).

[velo]

Neutral name OffsetPageInfo ✔️
Lazy on OffsetPageInfo fields ✔️
Configuration to enable OffsetPageInfo ✔️

[ferenc-csaky]

These changes in this class are write-only AI code completely and i do not like it one single bit.

The newly introduced OffsetPageInfo reuses the LIMIT_AND_OFFSET code and it results in some weird mixed execution I do not want to debug 3months from now.

I suggested to introduce a new pagination type in my other comment. We should use that here and separate the executions, possibly reusing any common logic needed for LIMIT_AND_OFFSET, but we need clear abstraction layers and an execution flow that a human can debug without losing their sanity.