GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
adk-2.0 consumer: scope_cardinality view (source_event_id gate, three value columns, fan-out test)
- Dominant language
- Python
- Stars
- 47
- Forks
- 21
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 33
Description
Parent tracker: #190 (v15 contract).
Wave: 5 — Consumer views.
Blocked by: #195 (identity stamping), #198 (producer scope), #210 (cross-event deployment plumbing).
## Contract
### Grain
One row per `(JSON_VALUE(attributes, '$.adk.app_name'), user_id, session_id, invocation_id, scope_kind)` where `scope_kind = COALESCE(JSON_VALUE(attributes, '$.adk.scope.kind'), 'unscoped')`.
### Three value columns (correct units)
One ADK `Event` already fans out into multiple BQAA rows on `on_event_callback` (`STATE_DELTA`, HITL, A2A, `AGENT_RESPONSE` co-emit from one source Event). Naive `COUNT(*)` lies about volume:
- `distinct_scope_count = COUNT(DISTINCT JSON_VALUE(attributes, '$.adk.scope.id'))` — cardinality (null/0 for `unscoped`).
- `source_event_count = COUNT(DISTINCT JSON_VALUE(attributes, '$.adk.source_event_id'))` — distinct ADK Events (primary volume metric).
- `row_count = COUNT(*)` — diagnostic only; do not use as primary volume.
### Gate
`WHERE JSON_VALUE(attributes, '$.adk.source_event_id') IS NOT NULL` — **not** `schema_version IS NOT NULL`. The latter lets non-Event-originating callback rows (`USER_MESSAGE_RECEIVED`, before-model, before-tool) through, and they have no meaningful scope. Pre-2.0 rows fall out of the same gate.
## Acceptance
- [ ] Three value columns named and typed as above.
- [ ] Gate uses `source_event_id IS NOT NULL`.
- [ ] **Fan-out test**: one source Event emitting two BQAA rows (e.g. `STATE_DELTA + AGENT_RESPONSE`) produces `source_event_count = 1, row_count = 2`.
- [ ] Null-safe test: pre-2.0 rows and non-Event-originating v2 rows are both excluded.
- [ ] `'unscoped'` bucket contains only v2 Event-originating rows where ADK emitted `scope = null`.
## References
- #190 (v15 consumer view 6; v13 source_event_id gate; v14 three-column split).
Contributor guide
Assessment
This issue has not been assessed yet.