v1 getDocuments: tracker for wire-only / not_yet_implemented surfaces from #3654

[QuantumExplorer]

Background

PR #3654 lands the v1 getDocuments SQL-shaped wire surface (SELECT / WHERE / GROUP BY / HAVING / ORDER BY / LIMIT / OFFSET), but ships several pieces as wire-only: the proto carries them so callers can encode the shape and the future server capability can land without another wire-format change, but the server rejects them at routing time with QuerySyntaxError::Unsupported("… is not yet implemented").

This tracker collects every not_yet_implemented introduced by that PR so each can be picked up as a focused follow-up.

Inventory of not_yet_implemented rejections (rs-drive-abci v1 handler)

#	Reject site	Notes
1	HAVING clause is not yet implemented	Non-empty having rejected wholesale. Decoded Vec<HavingClause> already lands in having_clauses_from_proto (currently #[allow(dead_code)]); execution is "flip the gate + thread into the dispatchers."
2	SELECT SUM is not yet implemented	Numeric aggregate executor missing in drive — aggregate_count / carrier_aggregate_count cover COUNT only.
3	SELECT AVG is not yet implemented	Same — needs numeric aggregate executor. Result is f64, response shape needs a polymorphic AggregateValue variant.
4	SELECT MIN is not yet implemented	Per-group/global MIN executor needed (semantically distinct from HavingRanking::Min which is cross-group).
5	SELECT MAX is not yet implemented	Symmetric to MIN.
6	SELECT COUNT(field) is not yet implemented	Counting non-null values of a specific field; today only COUNT(*) (empty field) is evaluated.
7	GROUP BY with SELECT DOCUMENTS is not yet implemented	Documents-fetch path doesn't accept grouping.
8	GROUP BY on field '<x>' which is not constrained by an In or range where clause is not yet implemented	Single-field GROUP BY on a field not present in WHERE.
9	two-field GROUP BY outside the (In, range) compound shape is not yet implemented	Only the canonical compound (in_field, range_field) ordering is wired; other orderings need a new merk walk.
10	GROUP BY with more than two fields is not yet implemented	group_by.len() > 2. Probably permanent in current architecture; flag for confirmation.
11	OFFSET pagination is not yet implemented	Wire-reserved optional uint32 offset = 12;. Cursor pagination via start_after / start_at is the supported path today.
12	multi-projection SELECT is not yet implemented	Wire: repeated Select selects. Today selects.len() > 1 rejected. Response shape needs a parallel repeated AggregateValue values field when this lands.
13	start_after / start_at with SELECT COUNT is not yet implemented	Paginating count results — workaround today is narrowing the range clause.
14	ORDER BY on aggregate keys is not yet implemented	Wire: OrderClause.target.aggregate. Drive's OrderClause only carries a plain field: String; extension needs a new OrderTarget enum at the drive level. Overlaps HavingRanking::Top/Bottom for top-N selection but more general.

Dependencies between items

• (2) (3) (4) (5) all need a shared numeric-aggregate executor in drive + a polymorphic AggregateValue response variant. Land that infrastructure once; then the four functions are mostly individual executor implementations.
• (12) depends on (2)–(5) — multi-projection only matters once there are non-COUNT projections to combine. Also needs the parallel repeated AggregateValue values response shape.
• (14) depends on extending drive's OrderClause shape; once done, HavingRanking::Top/Bottom could potentially be consolidated through this path.
• (1) is independent — the wire decoder is already in conversions.rs::having_clauses_from_proto; only the gate-flip + dispatcher threading is needed.
• (11) is independent — drive already accepts offset on SizedQuery; routing-layer wire-through is the main work.

Suggested first slices

1. (11) OFFSET — smallest contained piece. Probably one PR.
2. (1) HAVING — decoder already in tree; executor design is the main work. One PR.
3. (2)–(5) Numeric aggregates infrastructure — first the AggregateValue response variant + drive executor scaffolding; then SUM as the canonical first function; then AVG / MIN / MAX follow once the shape settles. 2–3 PRs.
4. (14) ORDER BY aggregate — once (2)–(5) land, the ranking infrastructure is reusable. One PR.
5. (12) Multi-projection SELECT — depends on the above. One PR.
6. (7) (8) (9) (10) (13) — GROUP BY / pagination-on-count gaps. Individual PRs as needed.

References

• Wire surface: packages/dapi-grpc/protos/platform/v0/platform.proto (GetDocumentsRequestV1 and its nested messages)
• Routing gate: packages/rs-drive-abci/src/query/document_query/v1/mod.rs (validate_and_route)
• Wire→drive conversions: packages/rs-drive-abci/src/query/document_query/v1/conversions.rs
• Drive types: packages/rs-drive/src/query/{having,projection,conditions,ordering}.rs

[QuantumExplorer]

Adding a 15th item flagged in PR #3654 round-4 review (CodeRabbit comment_id=3253729203):

(15) U128 / I128 indexed-field WHERE clauses round-trip gap — The SDK encodes Value::U128 / Value::I128 as DocumentFieldValue::Text(decimal) (the proto has no 128-bit slot), and the proto-side docstring promises schema-aware coercion on the server. That coercion exists on the v0 SQL-parser path (DocumentPropertyType::value_from_string) but isn't threaded through the v1 typed path: v1/conversions.rs::value_from_proto passes Text through as Value::Text, and the downstream executor's strict Value::to_integer() then rejects it.

No production system contract indexes 128-bit values today so the practical exposure is zero. The fix is to either (a) insert schema-aware coercion between where_clauses_from_proto and from_typed_clauses on the v1 path (analogous to v0's SQL-parser flow), or (b) reject Value::U128 / Value::I128 at SDK encode time with a clear "not yet supported for v1 indexed-field where clauses" error.

Tracked in d8a6136's SDK docstring; flagging here for a focused follow-up.