GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
adk-2.0 consumer: branch_fanout view (cardinality only; branch_concurrency deferred)
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
Parent tracker: #190 (v17 contract).
Wave: 5 — Consumer views.
Blocked by: #195 (`attributes.adk.app_name` + `attributes.adk.source_event_id` identity stamping — both grouped on and gated on), #197 (producer `attributes.adk.branch`), #210 (cross-event deployment plumbing).
## Contract
**First pass = cardinality only.** Per `(JSON_VALUE(attributes, '$.adk.app_name'), user_id, session_id, invocation_id)`, count distinct `attributes.adk.branch` values.
Concurrency is intentionally deferred — a meaningful concurrency metric requires interval data from `WORKFLOW_NODE_STARTING/COMPLETED`, which is still design-required (#207). Once that lands, add a `branch_concurrency` follow-up view.
### Row provenance gate
```sql
WHERE JSON_VALUE(attributes, '$.adk.source_event_id') IS NOT NULL
```
This excludes:
- Pre-2.0 rows (no `attributes.adk` block at all).
- Non-Event-originating callback rows in v2 (`USER_MESSAGE_RECEIVED`, before-model, before-tool, etc.).
`branch` is an ADK `Event` field, so only originating-Event rows have a meaningful read.
### Zero-branch policy
**Emit a row with `distinct_branch_count = 0`** for v2 Event-originating invocations that have no `attributes.adk.branch` on any row. This preserves the invocation in the analytical surface so consumers can compute "% of v2 invocations that branch" and similar metrics. The alternative (no row) would silently hide non-branched invocations from the analytic surface.
## Acceptance
- [ ] One row per `(app_name, user_id, session_id, invocation_id)` with `distinct_branch_count`.
- [ ] Gate uses `source_event_id IS NOT NULL`.
- [ ] **Zero-branch case**: a v2 Event-originating invocation with no branch on any row produces a row with `distinct_branch_count = 0` (not absent).
- [ ] Pre-2.0 rows excluded — no rows produced from invocations that only have pre-2.0 events.
- [ ] Non-Event-originating v2 rows excluded — they don't appear in the view.
- [ ] Follow-up `branch_concurrency` view is filed as a separate issue once #207 lands.
## References
- #190 (v17 consumer view 3; v6 concurrency deferral; v13 source_event_id gate pattern from `scope_cardinality`).
Contributor guide
Assessment
This issue has not been assessed yet.