plan: triage and plan #16 bucket-oriented v2 query client

[craigmcchesney]

Plan-only PR for #16 (the bucket-oriented v2 query, queryBuckets / queryBucketsStream). Merging this does not close the issue; the implementation lands in PR A (client, conversions, unit tests) and PR B (live tests, docs, Closes #16).

Refs #16

What triage found

The ticket was AI-drafted and filed before #6 and #17 landed. Its request-side analysis holds; the rest needed correcting against dp-service main (08c2038):

• Most of the conversion layer already exists (data_frame_conversions, expand_data_timestamps(), data_frame._slice_frame()). A DataBucket is one PV's column over one axis, so the work is wrapping, per-PV assembly, and trimming.
• sampleStatusSelector is rejected on buckets (not "future"); the client refuses it at request-build time.
• useSerializedColumns is inert on buckets, contrary to query.proto; serialized buckets are user data, passed through raw and refused in pandas. Upstream docs fix: queryBuckets: correct useSerializedColumns docs, and document byte-cut pages, token scope, and result order dp-grpc#167 (sub-issue of 2.0 API modernization data-platform#104).
• limit counts buckets, pages are also cut by bytes (with a token), and excludeColumnMetadata works on buckets, so this is the first live read-back of provenance.
• No other open dp-python-lib ticket folds in: handle changes to queryRequestStatus() to add paging #68 waits on dp-grpc#165 / dp-service#302, Adopt typed gRPC stubs from dp-grpc (dp-grpc#158) #61 step 5 on the next dp-grpc release.

Resolved questions (2026-09-30)

• Q1: pandas output is one DataFrame per PV.
• Q2: trimming is exact and opt-in.
• Q3: two implementation PRs.
• Q4: upstream contradictions filed as dp-grpc#167.

Flagged for review

Decisions taken without a question: D2 (refuse, not drop, the status filter), D4 (no dedup across overlapping buckets), D6 (serialized pass-through), D7 (per-bucket metadata in df.attrs["buckets"]), D8 (no streaming pandas convenience), D9 (one shared stream sender for both query kinds).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CajTMkjkkzeoWXLSgMpn5k

[Copilot]

Copilot review overview

🟡 Changes recommended

The trimming design lacks range validation and cannot correctly handle the promised unsorted timestamp axes.

Review effort: Balanced
Findings: 2

Open (2)

• Validate that trimming intervals have begin less than end · New
• Reject unsorted axes before contiguous range slicing · New

What changed in this PR

Plans issue #16’s bucket-oriented v2 query client and conversion layer.

Changes:

• Documents verified server behavior and design decisions.
• Splits implementation into client/unit-test and integration/docs PRs.

File	Description
plan/​tickets/​16/​plan.md	Defines triage findings, API design, implementation tasks, and sequencing.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.