Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual

[caohy1988]

Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual

Context

The integration page already exists at docs/integrations/bigquery-agent-analytics.md (≈59 KB, with catalog_title: BigQuery Agent Analytics Plugin, catalog_tags: [observability, google]). It currently scopes to the plugin itself — installing it, writing rows to agent_events, and the auto-schema-upgrade / tool-provenance / HITL features that ship with ADK Python ≥ 1.26.0.

What it does not yet cover is the consumption-layer surface that the blogpost will lean on:

• The scheduled context-graph materializer (currently examples/migration_v5/periodic_materialization/ in the SDK repo — about to be renamed; see SDK companion issue Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282).
• The Cloud Run Job + Cloud Scheduler deployment pattern with the structured JSON log shape and Cloud Monitoring alerts.
• The context-graph concept doc (after the SDK-side consolidation into a single canonical docs/context_graph.md lands).
• The pluggable ontology pipeline (MAKO as load-bearing reference + the "drop in your own TTL" path).

This issue is the planning umbrella for promoting that consumption-layer content into the public adk-docs page so the blogpost can link to a single user-facing manual instead of pointing readers at the SDK repo's examples/ tree.

Coordination with the SDK cleanup (#282)

The SDK repo is being renamed and consolidated in companion issue GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK#282. Specifically:

• examples/migration_v5/ → examples/context_graph_demo/ (Wave 3 of Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282)
• docs/context_graph_v{2,3}_design.md → consolidated docs/context_graph.md + docs/context_graph_design.md (Wave 2 of Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282)
• README rewrite for blogpost narrative (Wave 5 of Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282)

This adk-docs work should land after Wave 3 of #282 is merged so the deep links on adk.dev/integrations/bigquery-agent-analytics/ are stable from day one. Linking the published page at examples/migration_v5/... would break the day the SDK rename merges.

Earlier prep work (page outline, asset migration, mkdocs nav) can happen in parallel; only the cross-repo links should wait.

Page-architecture decision (needs an answer first)

Two options for how the new content lands on the page. Pick before writing prose.

Option A — single-page expansion (recommended for blogpost cadence)

Keep docs/integrations/bigquery-agent-analytics.md as one big page; append new top-level ## sections for the consumption-layer content. Pros: one URL, one deep-link target, simplest to ship for a blogpost; matches the integration-page-per-tool convention the rest of docs/integrations/ follows. Cons: page becomes ~120–150 KB; navigation inside the page relies on the right-side TOC.

Option B — split into a sub-section (more like a real manual)

Convert the integration page into a section index that links into docs/integrations/bigquery-agent-analytics/ (a sub-directory). One file per concern: quickstart.md, configuration.md, periodic-materialization.md, context-graph.md, troubleshooting.md. Pros: proper user-manual navigation. Cons: requires mkdocs nav restructuring, changes the existing canonical URL, breaks existing inbound links.

Recommendation

Option A. The existing URL is already widely linked from the SDK repo (and is the URL the user wants in the blogpost). One large page with clear ## anchors and the right-side mkdocs TOC is the lowest-risk path to ship before the blogpost. If page weight becomes a problem later, the split to Option B can happen as a follow-up without breaking the canonical URL (top-level page becomes an index that links to the per-concern children).

Content scope — sections to add to the existing page

The existing page already covers (per the catalog frontmatter and the first ~2 KB I can see): the plugin itself, ADK version requirements, BigQuery Storage Write API, auto-schema-upgrade, tool-provenance tracking, HITL event tracing. v2 of the page should keep all of that and append these sections (proposed ## anchors in order):

1. **## What you can do with agent_events** — orient the reader. Tie the analytics columns to the questions they answer: token cost, tool fan-out, HITL frequency, A2A interactions, agent-team transfers. (Sourced from SDK.mdandREADME.md` after Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5.)
2. ## The context graph — concept doc. What it is, why it's separate from the row-level events, the ontology → binding → property-graph pipeline. (Sourced from consolidated docs/context_graph.md after Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 2.)
3. ## Schedule it with Cloud Run + Cloud Scheduler (the periodic materializer) — the meat of the user manual. Sourced from examples/context_graph_demo/periodic_materialization/README.md (post-rename). The 9-step customer playbook from that README is the spine. Required content:
   • Prerequisites (APIs, IAM)
   • Datasets (events vs. graph)
   • Local dry-run
   • Recommended schedules
   • Deploy with --smoke
   • Expected JSON log shape
   • Cloud Monitoring alerts on ok=false
   • Inspecting results via the state-table audit log
   • Troubleshooting / failure-mode surface
   • Cleanup and redeploy
4. ## Plug your own ontology in — the pluggable contract from examples/context_graph_demo/README.md. Walks through OntologyConfig, the three OWL-TTL normalizations, the four generated artifacts (ontology.yaml / binding.yaml / table_ddl.sql / property_graph.sql).
5. ## Querying the property graph — sample SQL questions, with the MAKO ontology as the reference example.
6. ## Where to file feedback / issues — links to the SDK repo issues, the public schema migration guide.

Assets

The SDK repo has docs/blog/images/context-graph-flow.png and docs/codelabs/images/context-graph-flow.png (the same image in two places). Copy one into docs/integrations/assets/bigquery-agent-analytics/context-graph-flow.png and reference it from the new "The context graph" section.

The existing docs/integrations/assets/bigquery.png stays as the catalog icon (already referenced from the frontmatter as /integrations/assets/bigquery.png).

If the periodic-materialization "Production shape" ASCII diagram from the SDK README reads cleanly enough, keep it as a code block — no asset migration needed for that one.

mkdocs and nav

• Page is already in mkdocs.yml nav (file exists, page is published). No nav change needed for Option A.
• lychee.toml link-check runs in CI; the new external links into the SDK repo will be checked. Ensure they're stable post-Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282-rename before this PR merges (gated on Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3).
• netlify.toml controls preview deploys; the PR will get a preview URL automatically.

Source-of-truth + sync strategy

The content for the new sections lives in the SDK repo today. Three options for keeping the adk-docs page in sync as the SDK evolves:

Strategy	Maintenance	Sync cadence	Verdict
Manual copy on each SDK release	Heavy	Per-release	Predictable but lossy; the doc rots between releases.
One-time copy + cross-repo link to the SDK README for deep dive	Light	Once	Recommended for the first cut. The adk-docs page covers the stable user-facing surface (concept, periodic-materialization recipe, ontology contract); the SDK README continues to be the authoritative reference.
Automated mirror (CI job that opens a sync PR into adk-docs)	Medium	Continuous	Worth investigating after the first cut ships; over-engineered for v2.

Recommended: one-time copy + clear "for the latest reference, see the SDK repo" pointers in each section. Revisit after we see how often the content drifts in practice.

Pull-request workflow

google/adk-docs is a Google-owned public repo; PRs go through Google's normal review. Two practical considerations:

• The PR should fit in a single reviewable chunk. Estimated diff: ~60 KB added to one file + one asset. That's at the upper bound of what a single reviewer wants to read; consider posting a section-by-section preview PR for sign-off first, then submitting the full version.
• Title format: existing adk-docs PRs use docs: ... prefix.
• The CONTRIBUTING.md in adk-docs lists the conventions (heading style, frontmatter, code-block languages).

Plan — proposed wave order

Wave	Scope	Repo	Depends on
1	Page outline + assets prep (copy context-graph-flow.png into docs/integrations/assets/bigquery-agent-analytics/); draft new sections in a local fork against the existing page.	adk-docs (draft)	—
2	Wait for SDK rename (examples/migration_v5/ → examples/context_graph_demo/) to land.	—	#282 Wave 3
3	Source-content extraction: pull the periodic-materialization README + consolidated context-graph concept doc into the draft.	adk-docs (draft)	#282 Wave 2 + Wave 3
4	Cross-link audit: every link from the new page into the SDK repo points at the post-rename path. Run lychee locally.	adk-docs (draft)	Wave 3
5	Section-by-section preview PR (or thread) for sign-off from the adk-docs maintainers.	adk-docs	Wave 4
6	Full PR: page diff + asset. Address review feedback.	adk-docs	Wave 5
7	Land. Verify preview, then merge. Add a follow-up issue in the SDK repo to keep the README "for the published user manual, see adk.dev/integrations/bigquery-agent-analytics/" pointer up to date.	adk-docs + SDK repo	Wave 6

Acceptance

• docs/integrations/bigquery-agent-analytics.md covers, in order: plugin install + config, what agent_events answers, the context graph concept, the periodic-materialization recipe end-to-end, the pluggable ontology contract, sample queries, where to file feedback.
• A reader who lands on the page from the blogpost can deploy the periodic materializer against their own project without leaving the page.
• All deep links from the page into the SDK repo resolve under the post-rename paths (examples/context_graph_demo/...).
• lychee link-check passes in CI.
• The SDK repo's README.md (post Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5) links to the published user manual.
• One asset (context-graph-flow.png) is committed under docs/integrations/assets/bigquery-agent-analytics/.

Open questions for the team

1. Page architecture — confirm Option A (one big page) vs. Option B (sub-directory of per-concern pages). Recommended Option A.
2. Section order — does putting "periodic materialization" (the operational recipe) before "querying the property graph" (the conceptual payoff) match how operators read this, or should the order flip?
3. Code-sample policy — adk-docs renders Python with === "Python" tabbed code blocks in some integrations. Match that style or use plain python fences?
4. Blogpost timing — what is the publish date the page needs to be live by? That sets how far in advance Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3 has to merge.
5. Sync ownership — who in the team owns the periodic sync after v2 ships? Default: the same person who owns the SDK repo README.

References

• Existing page: docs/integrations/bigquery-agent-analytics.md (~59 KB).
• Source content for the new "Schedule it..." section: examples/migration_v5/periodic_materialization/README.md (to be examples/context_graph_demo/periodic_materialization/README.md post-rename).
• Companion SDK cleanup tracker: Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282.
• adk-docs contribution conventions: CONTRIBUTING.md.

[caohy1988]

Full review against current google/adk-docs + SDK checkouts.

Overall: Option A is a reasonable blogpost-deadline choice, and the page exists exactly where the issue says (docs/integrations/bigquery-agent-analytics.md, 59,036 bytes in the current checkout, with the expected catalog frontmatter). I would tighten the plan in a few places so the published page does not become a huge append-only doc with stale version/link assumptions.

Findings:

1. High: "append six new ## sections" puts the manual in the wrong place. The existing page already has a coherent flow: Use cases, Quickstart, Configuration, Schema, Event types, Storage behavior, Query recipes, Deploy to Agent Runtime, Security, Operations, Additional ways to consume logged data. Appending the context-graph manual after Feedback/Additional resources would bury the blogpost path after deployment/security/ops material and duplicate parts of the current Query recipes. Keep Option A, but integrate rather than append:

   • add/reshape a top-level section after ## Query recipes and before ## Deploy to Agent Runtime with the plugin;
   • make "What you can do with agent_events" an upgrade of the existing Query recipes/Additional ways sections, not a duplicate;
   • keep Feedback and Additional resources at the end.

2. High: merge gating should wait on more than Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3. Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 correctly gates cross-repo deep links on the examples/context_graph_demo/ rename, but the planned page also depends on Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 2 (docs/context_graph.md / docs/context_graph_design.md) and Wave 5 (README front-door language, if it is a source for the "what agent_events can answer" section). Drafting can happen early, but the adk-docs PR should not merge until:

   • Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 2 canonical docs exist;
   • Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3 rename has landed;
   • every SDK deep link points at post-rename paths;
   • any copied content sourced from the README has either landed in Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5 or is explicitly sourced from another stable doc.

3. Medium: do a version-consistency sweep before adding more content. The page top says ADK Python 1.26.0+ for auto-schema/tool-provenance/HITL, but the Agent Runtime section still has an "ADK Python 1.24.0 or higher" warning for deployment flush behavior. That may be historically true, but as a user manual baseline it reads like two different minimum versions. Add a required sweep for version callouts, event-type names, and feature-version labels before expanding the page.

4. Medium: the mkdocs/nav statement should be corrected. The file exists and is published through the integrations catalog (docs/integrations/index.md uses render_catalog('integrations/*.md')). In mkdocs.yml, I only found redirect mappings for old paths to integrations/bigquery-agent-analytics.md, not a direct nav entry for this page. For Option A that likely means no nav change is needed, but the issue should say "catalog/frontmatter already publishes it" rather than "page is already in mkdocs.yml nav."

5. Medium: page size needs an explicit reader-navigation mitigation. The current page is ~59 KB; the proposed copy likely pushes it into the 120 KB range. If Option A stays, add acceptance for a short local table of contents or "On this page" landing block near the top that points to install/config, query recipes, context graph, periodic materialization, security, and troubleshooting. Relying only on the right-side TOC is weak for a blogpost landing page.

6. Low: code-sample style can be decided now from the current page. This page already uses plain fenced python, shell, sql, and text blocks extensively. Other adk-docs pages use === "Python" tabs, but forcing tabs into this integration page would be inconsistent unless the whole page is refactored. Recommendation: keep plain fenced blocks for this v2 expansion; use tabs only if the section truly has language variants.

7. Low: asset placement is fine, but make the path/alt-text acceptance explicit. docs/integrations/assets/ is currently mostly flat; creating docs/integrations/assets/bigquery-agent-analytics/context-graph-flow.png is okay, but add acceptance that the Markdown uses a stable relative or root-relative path and includes useful alt text. The SDK has the image in both docs/blog/images/ and docs/codelabs/images/; pick one source and document it to avoid future "which copy is canonical?" drift.

Suggested acceptance additions:

• The new context-graph section lands before Agent Runtime deployment, not at the very end.
• Existing Query recipes / Additional ways sections are de-duplicated rather than copied around.
• The page passes a version/string sweep for 1.24.0, 1.26.0, 1.27.0+, event-type names, and SDK links.
• Publication is validated through the integrations catalog/frontmatter, plus existing redirect mappings still work.

[caohy1988]

Follow-up after incorporating #277 / PRs #278-#281.

#277 is merged through #281, so the adk-docs manual should make the new one-artifact path the primary story:

bqaa context-graph \
  --project-id ... \
  --dataset-id ... \
  --property-graph property_graph.sql

and treat --ontology + --binding as advanced override mode.

Implications for this issue:

1. The planned section list is stale where it says users plug in OntologyConfig / ontology+binding as the main path. The "Plug your own ontology in" section should be reframed. Primary flow: author/apply table DDL + CREATE PROPERTY GRAPH; the SDK derives ontology+binding from the property-graph DDL plus live table schemas. Advanced appendix: bring explicit ontology/binding when you need descriptions, logical-name overrides, or other metadata the DDL cannot express.

2. The periodic-materialization recipe should not copy the current YAML-mode deployment as-is. Current SDK examples/migration_v5/periodic_materialization/run_job.py still retargets binding.yaml and passes ontology_path/binding_path. Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 now needs to migrate that recipe to --property-graph; this page should wait for that update, not just the directory rename. Otherwise adk.dev would publish the pre-Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 four-artifact workflow right after the SDK gained the simpler path.

3. Add Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277/feat(cli): bqaa context-graph --property-graph derives ontology+binding (issue #277, PR 4) #281 as explicit merge gates. feat(cli): bqaa context-graph --property-graph derives ontology+binding (issue #277, PR 4) #281 is merged, but the docs/codelab/example cleanup that teaches it is not yet done. For Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283, "ready to merge" should require:

   • SDK example path renamed (Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3);
   • periodic materializer example updated to property-graph mode;
   • codelab/docs no longer say bqaa context-graph requires both --ontology and --binding;
   • deep links point to the post-rename, post-Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 recipe.

4. The "what can agent_events answer" and "context graph concept" sections should explain the new derivation boundary. Useful concise framing: agent_events is raw telemetry; property_graph.sql is the user's query surface; the SDK derives the internal ontology/binding needed to extract/materialize rows; explicit ontology/binding files are optional expert controls.

5. Asset/code examples should use one-artifact commands. The current SDK codelab still says the graph schema "cannot populate" the graph and therefore --ontology and --binding are required. That statement is now false after Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277. The user-manual examples should avoid copying it.

Net: #277 improves the adk-docs story substantially, but it also means #283 should be gated on the SDK docs/examples being updated to the property-graph-primary workflow, not only on the migration_v5 directory rename.

[caohy1988]

Full review of the #277 incorporation comment

Verified the prior follow-up against main and the existing adk-docs page. All five points are correct. Additional gaps + concrete recommendations follow.

Claims confirmed

• bqaa context-graph accepts --property-graph today (src/bigquery_agent_analytics/cli.py:1817-1819); both YAML mode (--ontology + --binding) and the new property-graph mode are wired into the same materialize_window command (cli.py:1797-2046). Either path works, and the docs decision is which one to lead with.
• The current periodic deploy is still YAML-only (examples/migration_v5/periodic_materialization/run_job.py:479,499-503; deploy_cloud_run_job.sh:56,569,589-590). If adk-docs copies it today, the published manual will be teaching the pre-Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 workflow.
• The existing page is ~59 KB at docs/integrations/bigquery-agent-analytics.md. Restructuring it to lead with --property-graph is incremental, not a rewrite.

Additional gaps the follow-up did not cover

1. The derivation boundary needs to be a first-class concept on the page, not buried in the periodic-materialization recipe. The new mental model is two layers: physical table DDL + CREATE PROPERTY GRAPH DDL (user surface), and the SDK derives the in-memory Ontology + Binding it consumes internally. Recommendation: add a short "What you author vs. what the SDK derives" section near the top, before any bqaa commands. The existing docs/blog/images/context-graph-flow.png should be replaced by a diagram that shows this boundary:

   property_graph.sql + INFORMATION_SCHEMA.COLUMNS
                         ↓ (property_graph_spec.derive_ontology_binding_from_ddl)
                  in-memory Ontology + Binding
                         ↓ (resolve() → ResolvedGraph)
                  bqaa context-graph
                         ↓
              graph entity/relationship tables
   

2. The bigquery_ontology CLI is a separate authoring surface (src/bigquery_ontology/cli.py — 33.5 KB, commands validate / compile / scaffold / import-owl). The adk-docs page needs to decide where this lives. Recommendation: a short advanced subsection — "Authoring an ontology from OWL TTL" — referencing the bqaa_ontology (or future bqaa ontology) commands. Don't lead with it; advanced users find it when they need it.

3. CLI help / error wording still presents the YAML path equally with the property-graph path (cli.py:1791: "Provide --property-graph PATH, or both --ontology PATH and binding PATH"). The adk-docs page should not blindly copy this — it should reorder so --property-graph is presented first. Worth a note in the writing guidance for whoever drafts the page.

4. The page architecture choice (Option A: single-page) interacts with the "When do I author explicit ontology+binding?" question. With Option A, the advanced "explicit ontology+binding" appendix becomes a ## section near the bottom. Recommended title: "Advanced: bring your own ontology + binding". It explains why someone would: human-readable descriptions, logical-name overrides, decoupling concept names from physical table names, fine-grained validation that the property-graph DDL cannot express alone.

5. The asset list in the issue should be updated. context-graph-flow.png from the SDK was drawn for the pre-Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 four-artifact world. The new derivation-boundary diagram above probably needs to be regenerated. Either replace the asset or commit both (context-graph-flow.png historical, context-graph-derivation.png new).

Recommended body edits

• §Content scope — sections to add: reorder so the page reads (1) plugin install, (2) what agent_events answers, (3) what you author vs. what the SDK derives [new, derivation boundary], (4) context graph concept, (5) schedule it with Cloud Run + Cloud Scheduler [property-graph mode primary], (6) advanced: bring your own ontology + binding [new], (7) querying the property graph, (8) feedback/issues.

• §Content scope, section 4 ("Plug your own ontology in"): rename to "Advanced: bring your own ontology + binding" and move below the periodic-materialization recipe. Primary user flow no longer goes through this section.

• §Coordination with the SDK cleanup: tighten the merge gates. Today the gate is "after Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3 rename". Update to two gates:

  • SDK directory rename (examples/migration_v5/ → examples/context_graph_demo/); and
  • SDK periodic-materializer recipe migrated to --property-graph mode (drop YAML retargeting in run_job.py, drop YAML staging in deploy_cloud_run_job.sh).

  Without the second gate, the adk-docs page would publish a quickstart that contradicts the periodic-materializer recipe it links to.

• §Plan — proposed wave order: split Wave 2's "wait for SDK rename" into "wait for SDK rename and SDK periodic-materializer property-graph migration". Add a Wave 3.5 if necessary so the adk-docs page draft can be sanity-tested end-to-end against the post-Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 periodic deploy before the full PR is opened.

• §Assets: replace context-graph-flow.png with a derivation-boundary diagram, or commit both with the new one as the primary in-page image.

• §Open questions: add a sixth — "Should bqaa ontology (the ontology authoring CLI from src/bigquery_ontology/cli.py) be folded into the product bqaa CLI as a subcommand group, and should the adk-docs page reference the unified CLI or both binaries?" This is a cross-cutting decision with Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 §Audit finding Move ontology reference documentation to docs/ontology/ #8 (two CLIs).

Net

The #277 reality moves the "Plug your own ontology in" section from the primary flow to an advanced appendix and changes which section the blogpost reader hits first. The two SDK-side merge gates above are the real dependency for shipping this page accurately — the directory rename alone leaves the published manual teaching the older workflow even with up-to-date links.

[caohy1988]

Fresh pass after the #277 incorporation review, focused on what the adk-docs manual should wait for before publishing.

The prior review still stands. New issue: the current --property-graph path is ready for the single-dataset codelab shape, but the production periodic-materializer recipe is explicitly split-dataset.

New findings

1. High: add a third SDK merge gate — property-graph mode must support the split events/graph dataset recipe.

   The page should not publish the periodic-materializer recipe as --property-graph primary until the SDK example proves that mode with separate datasets:

   • events dataset: read-only agent_events;
   • graph dataset: entity/relationship tables + _bqaa_materialization_state;
   • property_graph.sql references the graph dataset;
   • the derived in-memory binding targets the graph dataset, not the events dataset.

   Current main does not yet prove that. run_job.py still uses YAML retargeting for the graph dataset, while property_graph_spec.py binds ${DATASET} and the derived binding target to the materializer's dataset_id. In the periodic job, that dataset_id is the events dataset. So the adk-docs merge gate should be:

   1. Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3 directory rename;
   2. periodic materializer migrated to --property-graph;
   3. migrated periodic materializer tested with events dataset != graph dataset.

2. Medium: do not call this a one-file setup.

   Feat: derive ontology + binding from the property-graph DDL so bqaa context-graph no longer requires ontology.yaml/binding.yaml #277 removes hand-written ontology.yaml + binding.yaml from the primary path, but it does not remove the need for physical table DDL and live table schemas. The manual should phrase it as "one semantic graph artifact" or "property-graph-primary flow," not "only one file." The actual user prerequisites remain:

   • table DDL applied first, so INFORMATION_SCHEMA.COLUMNS can recover types;
   • CREATE PROPERTY GRAPH DDL applied / available as property_graph.sql;
   • bqaa context-graph --property-graph property_graph.sql.

3. Medium: document the derived-mode description tradeoff near the derivation boundary.

   DDL + INFORMATION_SCHEMA.COLUMNS can recover table refs, keys, labels, properties, and types, but not ontology descriptions/synonyms/logical-name overrides. Since the CLI default is still ai-fallback, the primary recipe can run with less-guided AI prompts than explicit YAML mode. Suggested wording:

   • property-graph mode is the recommended default for the manual;
   • use compiled-only / reference extractors for deterministic production runs;
   • use explicit ontology+binding as an advanced override when prompt descriptions, logical names, or ontology metadata are important.

4. Medium: use graph-specific placeholders in examples.

   Avoid examples that use ${DATASET} ambiguously. In the periodic recipe, ${DATASET} historically means the events dataset in many BQAA contexts, while graph tables live in BQAA_GRAPH_DATASET_ID. Prefer ${GRAPH_DATASET} or ${BQAA_GRAPH_DATASET_ID} in property_graph.sql snippets and diagrams.

Net: the page can still lead with --property-graph, but the SDK-side recipe needs one more split-dataset hardening pass before adk.dev should publish it as the production path.

[caohy1988]

Validation + additional gaps on the split-dataset finding

Verified the four findings against main. The split-dataset gate is the right addition. Additional adk-docs-specific gaps below.

Validation summary

• Production split-dataset shape is documented in run_job.py:46-49: events dataset is read-only agent_events; graph dataset is the write target for entity/relationship tables + _bqaa_materialization_state. _retarget_binding() at :225-249 is the YAML-mode mechanism that makes this work today.
• property_graph_spec.derive_ontology_binding_from_ddl() collapses dataset_id onto three uses (substitution + schema provider + binding target). Migrating run_job.py to property-graph mode without a new graph-dataset parameter would write graph tables into the events dataset.
• The new "what you author vs what the SDK derives" framing from the prior review is still right — but the manual now has to explain two boundaries: physical table DDL → schema; property-graph DDL → in-memory ontology+binding. Both need to land in the right dataset.

Additional gaps for the adk-docs page

1. The "Schedule it with Cloud Run + Cloud Scheduler" section will need a "decide your two datasets" subsection regardless of the YAML/property-graph question. The existing periodic-materializer README has step 1 "Decide your events vs graph dataset names" as the first customer-facing decision. After the property-graph migration that decision becomes more concrete: it's also which placeholder name the user writes in their property_graph.sql. Page should make the two-dataset shape obvious before the bqaa context-graph command appears, not after.

2. The recommended placeholder convention should be page-wide, not per-section. Whatever the SDK lands in Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 (${GRAPH_DATASET}, ${BQAA_GRAPH_DATASET_ID}, or alias-of-${DATASET}), the page should use that single convention from the first snippet onward. Mixing ${DATASET} in the codelab-style quickstart and ${GRAPH_DATASET} in the production recipe would teach the reader to be confused.

3. Add a "single-dataset vs split-dataset" decision table to the page. Reader-facing recommendation:

   Shape	When	Recommended placeholder
   Single dataset (codelab / dev)	Co-locate agent_events and graph tables; one IAM principal	${DATASET}
   Split datasets (production)	Separate read vs write IAM; archival policies differ	${GRAPH_DATASET} for graph tables, env var for events

   This makes the prior review's "what you author vs what the SDK derives" framing concrete: in single-dataset mode the user can ignore the distinction; in split-dataset mode the user actively chooses dataset roles.

4. Update the merge-gate list to four items. Prior review had three; add the split-dataset regression gate explicitly:

   1. Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3 directory rename.
   2. Periodic materializer migrated to --property-graph.
   3. property_graph_spec + run_materialize_window API supports graph_dataset_id distinct from events_dataset_id (verified by tests/test_property_graph_spec.py regression cases, periodic Cloud Run smoke with events_dataset != graph_dataset).
   4. SDK docs/codelab no longer say --ontology + --binding are required.

5. Description-tradeoff wording (addendum finding 3) interacts with the page's "When do I author explicit ontology+binding?" subsection. Suggested unified framing for that subsection:

   • Default: --property-graph + --extraction-mode=ai-fallback (CLI default). Easiest setup; works for most cases.
   • Production deterministic: --property-graph + --extraction-mode=compiled-only + reference extractors. No AI in the hot path.
   • Advanced override: explicit --ontology + --binding when you need descriptions, synonyms, logical-name overrides, or other metadata the DDL cannot express. (Reference the bqaa_ontology authoring CLI for this path.)

   This gives the reader a clear ladder rather than a binary "default vs. advanced."

6. Restate the single-file framing as "one semantic graph artifact, plus your existing table DDL." Addendum finding 2 is right that "one file" is misleading. The page-wide pitch should be:

   • "Bring your table DDL (you have it already)."
   • "Author one CREATE PROPERTY GRAPH DDL (the query surface)."
   • "Run bqaa context-graph --property-graph property_graph.sql."

   That's three sentences and matches what the reader actually has to do.

Recommended body edits to #283

• §Page architecture / Option A recommendation: keep, but add a callout that the page must adopt a single placeholder convention for graph-dataset throughout (decided in Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 cleanup).
• §Content scope, section 3 ("Schedule it with Cloud Run + Cloud Scheduler"): open with a "Decide your two datasets" subsection (events vs graph) before any bqaa command. Match the SDK periodic-materializer README step 1.
• §Content scope, section 5 (formerly "Advanced: bring your own ontology + binding"): rewrite as the three-rung ladder (default / production deterministic / advanced override) so the page tells operators when to use which mode.
• §Coordination with the SDK cleanup: bump the merge-gate list from 2 to 4 items per the addendum.
• §Open questions: add a seventh — "What is the page-wide convention for the graph dataset placeholder name?" — tied to the Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 cleanup decision.
• §Assets: the proposed derivation-boundary diagram should show two datasets explicitly when in production mode: events dataset on the left, graph dataset on the right, property_graph.sql + graph dataset's INFORMATION_SCHEMA.COLUMNS feeding the derivation, materializer reading events and writing graph.

Net

The page can still lead with property-graph mode, but it should land after the split-dataset hardening in #282 and should be page-wide consistent about which placeholder names the production shape uses. Without that, the manual would teach the codelab single-dataset shape as if it were the production recipe, and operators would discover the gap during their first scheduled deploy.

[caohy1988]

Fresh pass after the split-dataset addendum.

The latest #283 direction is right: the page should wait for the SDK split-dataset hardening and should teach a three-rung workflow ladder. A few doc gates need to be tightened so adk.dev does not publish API names or operational behavior before the SDK has committed them.

Findings

1. High: gate on the final SDK API/CLI shape, not only on "split datasets work."

   Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 still has an open API design question. I recommend keeping --dataset-id as the events dataset and adding --graph-dataset-id, rather than immediately renaming dataset_id to events_dataset_id. Whatever shape lands, Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 should not bake command snippets until that SDK PR is merged.

   Update the merge gates to say:

   • SDK rename landed;
   • periodic materializer migrated to property-graph mode;
   • property-graph mode supports split events/graph datasets;
   • final CLI/API flag names are landed and documented in the SDK README/codelab;
   • codelab no longer says --ontology + --binding are required.

2. High: the manual needs a "first run after migration" operational note.

   Moving the scheduled job from YAML-retargeted binding mode to property-graph-derived binding mode can change the materializer state_key, because the key includes ontology/binding fingerprints. The state table may stay in the graph dataset, but the checkpoint namespace can change.

   Add a short operations/troubleshooting subsection:

   • run a dry-run first and inspect the reported state key/fingerprints;
   • expect a new checkpoint namespace if the derived ontology/binding fingerprint differs from the old YAML artifacts;
   • choose lookback/backfill settings deliberately for the first property-graph-mode run;
   • explain duplicate/idempotent write expectations if the first run reprocesses the overlap/lookback window.

   Without this, operators may read "same state table" as "same checkpoint continuation," which is not necessarily true.

3. Medium: the two-dataset section should include metadata/schema permissions.

   The page already needs to separate events dataset reads from graph dataset writes. Property-graph-derived mode adds another requirement: the materializer reads INFORMATION_SCHEMA.COLUMNS for the graph tables to recover property types. The IAM table should call out metadata/schema lookup on the graph dataset separately from raw event reads.

   Suggested reader-facing wording: the job needs read access to the events table, write access to the graph dataset, and enough metadata access on graph tables for schema derivation/validation.

4. Medium: use graph-specific placeholders everywhere, including the codelab shape.

   To avoid a page-wide split-brain, prefer snippets like:

   • GRAPH_DATASET=my_graph_dataset
   • EVENTS_DATASET=my_events_dataset
   • --dataset-id "$EVENTS_DATASET" --graph-dataset-id "$GRAPH_DATASET"
   • property_graph.sql uses ${GRAPH_DATASET} for graph tables.

   In the single-dataset/codelab case, set both variables to the same value. That keeps one placeholder convention across the page and avoids teaching ${DATASET} in one section and ${GRAPH_DATASET} in another.

5. Low: the three-rung ladder should include the AI/IAM tradeoff.

   The proposed ladder is good:

   • default: --property-graph + ai-fallback;
   • production deterministic: --property-graph + compiled-only + reference extractors;
   • advanced override: explicit ontology + binding.

   Add the practical implication: ai-fallback requires the AI/LLM path and the corresponding project permissions/config; compiled-only avoids AI in the hot path but requires coverage by reference extractors; explicit YAML is for semantic metadata the DDL cannot express.

Recommended body edits

• Add "final SDK CLI/API shape landed" to the Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 merge gates.
• Add a first-run/state-key migration note to the periodic materializer operations section.
• Make ${GRAPH_DATASET} the page-wide placeholder convention; set it equal to the events dataset only in the single-dataset quickstart.
• In the dataset decision table, include schema/metadata lookup on the graph dataset, not only read/write data access.

Net: #283 can still lead with property-graph mode, but it should wait for the actual flag names and state-key migration behavior from #282 before publishing copy-pastable commands.

[caohy1988]

Endorsement + additional gaps

All five findings endorsed. The gate on final SDK CLI/API shape is the right call. Three additional gaps for the page itself.

Validation

• State-key composition confirmed at src/bigquery_agent_analytics/materialize_window.py:36-38 — sha256 of project + dataset + graph_name + events_table + ontology_fingerprint + binding_fingerprint + discovery_mode. YAML→derived migration changes 2 of 7 inputs.
• The same module documents the invalidation contract at :40-44: any predicate / config / mode change automatically forks the checkpoint namespace. The first-run-after-migration story is governed by this existing invariant — not a new behaviour the page has to explain de novo.
• The additive dataset_id / graph_dataset_id shape (per the companion Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 review) is the cleanest match for the page's three-rung ladder: codelab uses dataset_id only; production uses both; the advanced/explicit path uses both plus --ontology + --binding.

Additional gaps

1. The "first run after migration" note should be framed as the same mechanism that already governs config changes, not as a property-graph-mode special case. Suggested wording for the operations subsection:

   What happens on the first scheduled run after the migration. The materializer's checkpoint is namespaced by state_key = sha256(project + dataset + graph_name + events_table + ontology_fingerprint + binding_fingerprint + discovery_mode). Moving from --ontology + --binding to --property-graph changes the ontology and binding fingerprints (the derived in-memory pair is canonicalised differently from the YAML form), so the new run starts a fresh checkpoint and reprocesses the last lookback_hours. This is the same mechanism that auto-invalidates the checkpoint when you swap --completion-event-type, flip --include-active-sessions, or edit your ontology / binding YAML; per-session writes remain idempotent.

   That paragraph belongs near the periodic-materializer section, not in a separate migration appendix. The page should not give the impression that property-graph mode introduces a new failure mode — the mechanism already exists.

2. The two-dataset section should document the metadata-read requirement explicitly. BigQuerySchemaProvider reads INFORMATION_SCHEMA.COLUMNS on the graph dataset to recover property types — that is the new IAM ask --property-graph mode adds on top of "read events, write graph." The IAM table should split the graph-dataset row into two:

   Resource	Permission	Why
   events dataset	bigquery.dataViewer (or tables.getData + tables.list)	read raw agent_events
   graph dataset (data)	bigquery.dataEditor	write entity / relationship tables + state table
   graph dataset (metadata)	implicit via dataEditor, or bigquery.metadataViewer if downgrading data role	schema lookup via INFORMATION_SCHEMA.COLUMNS for the --property-graph derivation
   project	bigquery.jobUser	dispatch query jobs

   Including the metadata-read row makes the IAM ask explicit and lets operators on least-privilege deployments confirm their existing roles cover it.

3. The ladder's middle rung (compiled-only + reference extractors) needs a "how do I generate compiled extractors?" pointer. The three-rung ladder is right but the middle rung is currently the least-documented path. The page should link to the SDK's extractor_compilation/ surface (src/bigquery_agent_analytics/extractor_compilation/) — at minimum to cli_revalidate.py and whichever doc explains how to generate them. Without that pointer, operators reading the ladder may default to ai-fallback because the middle rung looks abstract.

Recommended body edits

• §Content scope, section 3 ("Schedule it with Cloud Run + Cloud Scheduler"): add a "Decide your two datasets" subsection as the first decision. Adopt the IAM table split above; note INFORMATION_SCHEMA.COLUMNS read requirement on the graph dataset.
• §Content scope, section 3: add a "What happens on the first scheduled run after the migration" paragraph using the wording above. Frame as the existing state-key invariant, not a YAML-vs-property-graph quirk.
• §Content scope, section 5 (three-rung ladder): add a one-sentence "how to generate compiled extractors" pointer per rung. Default rung → just run the command. Production rung → link to the extractor_compilation/ surface. Advanced rung → link to the bqaa_ontology authoring CLI.
• §Coordination with the SDK cleanup / merge gates: add a fifth gate — "materialize_window.py:40-44 checkpoint-invalidation contract is referenced from the page; the page does not re-derive a separate migration story." Avoids the page drifting from the SDK's own design doc.
• §Open questions: add an eighth — "Does the IAM table need a dataset.metadataViewer line for operators who downgrade dataEditor to dataViewer on the graph dataset, or is the implicit metadata access via dataEditor enough to leave unmentioned?"

Net

The split-dataset gate plus the additive graph_dataset_id shape from #282 cleanly maps to the page's two-dataset + three-rung architecture. The state-key migration is best framed as the existing invariant (with a citation to materialize_window.py:36-44), not as a new property-graph-mode behaviour. The remaining open item is the IAM metadata-read row, which is small but worth being explicit about so operators on least-privilege builds can self-verify.

[caohy1988]

Fresh pass after the latest #282/#283 alignment.

The page plan is close. I would tighten four items so the published manual does not encode a contradictory placeholder contract or an over-specific checkpoint story.

Findings

1. High: page-wide placeholder convention depends on resolving Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282's ${DATASET} contradiction.

   The latest Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 discussion currently says both ${DATASET} -> events dataset and ${DATASET} -> graph dataset alias. The adk-docs page should wait for the SDK contract, then use one convention everywhere.

   Recommended page convention if Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 lands as proposed:

   • EVENTS_DATASET means the raw agent_events dataset.
   • GRAPH_DATASET means entity/relationship tables, property graph, schema lookup, and state table.
   • DATASET appears only as a legacy/single-dataset alias for GRAPH_DATASET, not as an events-dataset synonym.

   This lets single-dataset quickstarts set EVENTS_DATASET="$GRAPH_DATASET" without changing the meaning of the SQL snippets.

2. High: document where _bqaa_materialization_state lives in split mode.

   The page currently focuses on events reads and graph writes. Once --graph-dataset-id exists, the manual should explicitly say the state table is part of the graph/write side:

   • default: {project}.{GRAPH_DATASET}._bqaa_materialization_state;
   • override: --state-table project.dataset.table;
   • operator can inspect it to audit checkpoint/fingerprint decisions.

   Add this as a merge gate tied to Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282: the SDK must land the default-state-table behavior before the page publishes split-dataset copy-paste commands. Otherwise the page may claim graph-dataset state while the CLI still defaults it to the events dataset.

3. Medium: the checkpoint paragraph should be conditional on fingerprint changes, not input mode alone.

   The page should cite the state-key invariant, but avoid saying "moving from --ontology + --binding to --property-graph always starts a fresh checkpoint" unless the SDK has proven that the specific demo's derived fingerprints differ from the current YAML fingerprints.

   Safer wording:

   The checkpoint namespace includes ontology and binding fingerprints. If the property-graph-derived ontology/binding fingerprints differ from the prior YAML artifacts, the first run starts a fresh checkpoint namespace and reprocesses the configured lookback window. This is the same mechanism used for completion-event changes, active-session debug mode, and ontology/binding edits.

   If the MAKO migration intentionally differs, add one demo-specific sentence after that. Keep the general user-manual rule fingerprint-based.

4. Medium: the compiled-only rung should link to a user-facing SDK doc, not the source package.

   The latest comment suggests linking to src/bigquery_agent_analytics/extractor_compilation/. That is useful for implementers but too raw for adk.dev. The page needs either:

   • a stable SDK README/SDK.md anchor explaining reference extractors / compiled bundles; or
   • a short local subsection that says "compiled-only requires reference extractors; see the SDK docs once Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5 lands."

   Add this to the Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 merge gates if the three-rung ladder is included. Otherwise the middle rung will tell operators to choose a production mode without giving them a supported path to create the required artifacts.

5. Low: use the canonical IAM role name if the metadata-read row is included.

   The open question says dataset.metadataViewer; use the actual role spelling roles/bigquery.metadataViewer (or describe the required permissions without naming a role). The row should stay explicit that dataEditor on the graph dataset covers normal demo deployments, while least-privilege deployments may split data write and metadata read permissions.

Recommended body edits

• Add a merge gate: Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 has landed the final placeholder semantics, including ${DATASET} alias behavior.
• Add a merge gate: Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 has landed/defaulted state-table placement for graph_dataset_id.
• Reword first-run checkpoint docs to be fingerprint-conditional.
• Replace src/.../extractor_compilation/ links in the user manual plan with a requirement for a stable user-facing SDK doc/anchor.

Net: the adk-docs plan should stay blocked on the exact SDK semantics for placeholders and state-table defaulting, not just on the existence of --graph-dataset-id.

[caohy1988]

Endorsement + additional gaps

All five findings endorsed. The page should hold on copy-pastable commands until #282 lands the final placeholder semantics, state-table default, and substitution precedence. Three additional gaps for the page itself.

Validation summary

• Placeholder contract — ${DATASET} aliasing to graph (Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 finding 1) is the only safe contract: property-graph DDL refs are graph tables, not events. A page that mixes ${DATASET} semantics across sections would teach the silent-mistarget failure mode.
• State-table default in graph dataset — currently masked by run_job.py:491 (fully-qualified state table); after --graph-dataset-id exists publicly, CLI users who omit --state-table would silently create _bqaa_materialization_state in the events dataset. The page must not document the graph-dataset location until the SDK CLI default matches.
• Fingerprint-conditional checkpoint story — materialize_window.py:36-38 documents the SHA-256 inputs; :382-385 components = [project_id, dataset_id, graph_name, ...] confirms dataset_id (events) stays in the state-key composition. The state-key invariant is fingerprint-content-derived, not mode-label-derived. The page should not say "switching to property-graph mode rotates the checkpoint" as a categorical claim.
• Compiled-only middle rung — the SDK has no stable user-facing doc on this path today. src/bigquery_agent_analytics/extractor_compilation/ is source. Without a doc, the middle rung tells operators to pick a production mode without giving them a supported way to produce the required artifacts. Wait for Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5 (README/SDK.md reshape) to provide a stable anchor.

Additional gaps

1. The page should document --state-key-suffix as the migration tool for operators who want to preserve historical lineage. materialize_window.py:375-380 documents an existing mechanism: a one-shot run with --state-key-suffix=yaml-archive carves out a separate state-key namespace from the steady-state cron. Operators migrating YAML→property-graph who want the old checkpoint stream archived (rather than abandoned when fingerprints change) can do this cleanly. Add to the periodic-materializer section as a one-sentence pointer near the fingerprint-conditional paragraph; the page doesn't need to teach the full mechanism, only signal it exists for operators who need it.

2. The single-dataset / split-dataset decision table should call out the state-key relationship. Reader-facing wording: in single-dataset shape, EVENTS_DATASET = GRAPH_DATASET, so the state-key includes that one dataset as both. In split shape, the state-key continues to include the events dataset (dataset_id in the SDK API), so adding --graph-dataset-id on its own does not rotate the state-key. This pre-empts the "I added --graph-dataset-id and my checkpoint reset" support question.

3. The IAM table footnote on dataEditor covering metadata reads needs a "verify on your build" caveat. dataEditor on the graph dataset covers INFORMATION_SCHEMA.COLUMNS reads in normal IAM deployments, but Google Cloud has periodically added permission scoping changes that affect metadata-only operations. The page should either:

   • Cite the canonical IAM permissions matrix as the source of truth and let dataEditor stand as the recommended default; or
   • Document the explicit permissions needed (bigquery.tables.list, bigquery.tables.get) for least-privilege deployments.

   The least-privilege path is what operators on hardened deployments actually need; the canonical role list is what most readers want.

Recommended body edits

• §Coordination with the SDK cleanup / merge gates: split the two new gates from the previous review into three:
  1. SDK rename landed (Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 3).
  2. Periodic materializer migrated to property-graph mode (run_job.py + deploy_cloud_run_job.sh).
  3. SDK has finalized ${DATASET} aliasing semantics + state-table default behavior + substitution precedence (property_graph_spec.py + materialize_window.py + tests).
  4. SDK has a user-facing doc for the compiled-only middle rung that the page can link to (gated on Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5).
  5. Codelab no longer says --ontology + --binding are required.
• §Content scope, section 3 ("Schedule it with Cloud Run + Cloud Scheduler") — periodic-materializer subsection text changes:
  • Decide your two datasets: add the state-key-invariance note (the state-key continues to include the events dataset; adding --graph-dataset-id alone does not rotate the checkpoint).
  • State-table location: explicitly say it lives in {project}.{GRAPH_DATASET}._bqaa_materialization_state by default, override via --state-table. Reference the SDK default once Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 lands.
  • What happens on the first scheduled run after the migration: use the fingerprint-conditional wording from the prior review; add one sentence on --state-key-suffix as the lineage-preserving alternative.
• §Content scope, section 5 (three-rung ladder): middle rung links to whichever user-facing SDK doc Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 Wave 5 produces, not to source paths.

Net

The page architecture (single page, three-rung ladder, two-dataset decision) is right. What it can't ship until: the SDK has committed final placeholder semantics, state-table default, substitution precedence, AND a stable user-facing doc on the compiled-only path. All four belong in the merge-gate list; without them the page would either contradict the SDK or send operators to source code for production guidance.

[caohy1988]

Fresh pass after the latest #283 endorsement.

The page gates are close, but two operator-facing statements need tightening so the manual does not overpromise checkpoint stability or overdescribe state_key_suffix.

Findings

1. High: do not tell users that adding --graph-dataset-id alone cannot rotate the checkpoint.

   The latest suggested decision-table note says:

   adding --graph-dataset-id on its own does not rotate the state-key

   That is only true if the derived ontology/binding fingerprints stay the same. In the intended implementation, graph_dataset_id becomes the derived binding.target.dataset. Since the state key includes binding_fingerprint, moving from single-dataset to split-dataset can rotate the checkpoint through the binding fingerprint even though graph_dataset_id is not a direct compute_state_key() component.

   Safer page wording:

   The state key directly includes the events dataset and the ontology/binding fingerprints. --graph-dataset-id is not a direct state-key component, but changing the graph dataset can change the derived binding fingerprint, which starts a fresh checkpoint namespace by design.

   This is the answer operators need when they ask why a split-dataset migration reprocessed the lookback window.

2. Medium: --state-key-suffix should not be described as archiving the old YAML checkpoint stream.

   The suffix creates a separate namespace for the run that uses it. It does not copy or rename old rows. The old YAML-mode checkpoint stream already remains in the append-only state table under its original state_key.

   Recommended page wording:

   • Use --state-key-suffix for backfills, canary re-extractions, or validation runs that should not advance the scheduled checkpoint.
   • To inspect historical YAML-mode state, query the existing state table rows by their original state_key / run time.
   • Do not present suffix as a required migration step or an archive operation.

3. Medium: keep substitutions out of the public manual unless Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 makes it a user-facing API.

   Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 still needs to decide whether reserved substitutions (PROJECT_ID, EVENTS_DATASET, GRAPH_DATASET, DATASET) are allowed to override semantic values or rejected. That is an SDK/API contract. The adk-docs page should teach the stable CLI flags and SQL placeholders only:

   • --dataset-id "$EVENTS_DATASET"
   • --graph-dataset-id "$GRAPH_DATASET"
   • ${GRAPH_DATASET} in property_graph.sql
   • ${DATASET} only as the documented legacy alias after Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 lands it

   Avoid mentioning the lower-level Python substitutions parameter in the user manual.

4. Low: make the checkpoint paragraph name the two paths that can rotate state.

   Suggested final shape:

   A new checkpoint namespace appears when any state-key input changes. For this migration, the likely inputs are the ontology/binding fingerprints, and, if the events table moves, the events dataset/table. The graph dataset can affect the key indirectly through the binding fingerprint because it is part of the derived binding target.

   That is precise without requiring readers to understand every internals detail.

Recommended body edits

• Replace the proposed state-key-invariance note in the single/split dataset table with the indirect-effect wording above.
• Reword the --state-key-suffix paragraph as a backfill/canary isolation tool, not an archive flow.
• Keep the public page centered on CLI flags and placeholders; leave Python substitutions semantics to SDK docs/tests.

Net: the manual should explain that --graph-dataset-id is not directly hashed, but changing it can still rotate state through the binding fingerprint. That prevents a misleading support promise while preserving the useful mental model.

[caohy1988]

Concession + verification + additional gaps

All four findings correct. Reversing two operator-facing statements from my prior comment.

Validation

Finding	Verified at	My prior framing
#1 --graph-dataset-id can rotate checkpoint indirectly	bigquery_ontology/binding_models.py:57-66 — BigQueryTarget.dataset is part of the model. materialize_window.py:387-388 — binding_fingerprint is a direct compute_state_key component. Changing graph_dataset_id in the derived path changes binding.target.dataset → binding_fingerprint → state-key.	Wrong. I told the page to say "adding --graph-dataset-id on its own does not rotate the state-key." False for the common single-dataset → split-dataset migration.
#2 state_key_suffix semantics	materialize_window.py:374-380: "backfill or ad-hoc re-extraction runs can carve out a separate state-key namespace from the steady-state cron — the backfill writes its own _bqaa_materialization_state rows without polluting the steady checkpoint stream."	Wrong. I framed it as the lineage-preserving alternative for archiving old YAML checkpoints. The mechanism creates a separate namespace for the suffixed run; it does not copy, rename, or archive existing rows.
#3 keep substitutions out of the public manual	property_graph_spec.py:99-105 — substitutions only rewrite DDL text; the schema-provider and binding-target defaults are computed from explicit args. The reserved-name semantics are an SDK API contract (#282 is still deciding between "reject" and "compute-from-final-map").	Acceptable; my prior comment did not push substitutions into the page, but the reviewer's gate framing is the right explicit policy.
#4 name both checkpoint-rotation paths	Direct rotation: any of the seven compute_state_key inputs changes (events dataset, graph name, events table, ontology/binding fingerprints, discovery mode). Indirect rotation: graph-dataset / binding-target / ontology semantic changes that flow into binding_fingerprint or ontology_fingerprint.	Acceptable; my prior framing under-named the indirect path.

Additional gaps

1. Single-dataset → split-dataset is the common migration, and the checkpoint rotation is intentional. The page should frame it as expected behavior, not a corner-case warning. Suggested paragraph for the periodic-materializer section:

   What happens to your checkpoint when you move to split datasets. The materializer's checkpoint is namespaced by state_key, a content-derived hash of the events dataset, graph name, events table, ontology and binding fingerprints, and the discovery mode. Adding --graph-dataset-id doesn't appear directly in that hash — but it changes the derived binding.target.dataset, which changes the binding fingerprint, which starts a fresh checkpoint namespace. This is the same mechanism that protects against --completion-event-type swaps, debug-mode flips, and ontology edits: any semantic change to the materialization target gets a clean checkpoint by design. Per-session writes remain idempotent, so reprocessing the configured lookback_hours window on the first split-dataset run is safe.

2. Querying historical YAML-mode state directly is the actual "lineage preservation" answer. The append-only state table keeps every row ever written under its original state_key. Operators who want to inspect the YAML-mode history after migrating run a simple SQL query against _bqaa_materialization_state, filtering by run time or by the historical state_key. The page should mention this in one sentence so operators don't think the migration loses anything. Sample wording:

   Historical YAML-mode runs remain queryable in the same append-only state table — filter by state_key (or by run_started_at before the migration date) to inspect them. The append-only design means the migration cannot lose rows.

3. --state-key-suffix belongs in a different subsection, not in the migration paragraph. The accurate uses are backfills, canary re-extractions, and validation runs — none of which are "migration." Suggested home: a separate "Backfills and ad-hoc re-extractions" subsection that covers the suffix, the carve-out semantics, and the requirement that the suffix run cannot advance the steady checkpoint. Keep the migration paragraph clean.

4. The "fingerprint-conditional" wording should keep the conditional even when the demo is known to differ. Even if MAKO's YAML and derived fingerprints are known to differ today, the docs phrasing should stay general ("if the derived fingerprints differ from the prior YAML fingerprints, the first run starts a fresh checkpoint"). A future SDK change could make a particular ontology's YAML and derived forms fingerprint-equivalent; the docs shouldn't promise rotation in cases where it might not happen. Leave the demo-specific claim to release notes / CHANGELOG.md.

Recommended body edits to #283

• §Content scope, section 3 ("Schedule it with Cloud Run + Cloud Scheduler") — periodic-materializer subsection:
  • Replace the proposed decision-table note ("adding --graph-dataset-id on its own does not rotate the state-key") with the rephrased operator-facing paragraph above. Name both rotation paths (direct compute_state_key input changes; indirect through binding_fingerprint / ontology_fingerprint).
  • Add the one-sentence "historical YAML-mode runs remain queryable" note so operators understand the append-only state table preserves lineage without a separate archive step.
• §Content scope, section 3 — new "Backfills and ad-hoc re-extractions" subsection: cover --state-key-suffix here. Backfill / canary / validation use cases. Suffix carves out a separate namespace; does not advance the steady checkpoint; does not copy or archive existing rows. Keep it distinct from the migration paragraph.
• §Coordination with the SDK cleanup / merge gates: rename gate 3 from "SDK has finalized placeholder semantics" to "SDK has finalized placeholder semantics, including the reserved-name policy for substitutions (reject vs. compute-from-final-map) — final decision documented in the public API contract." That precondition is what blocks teaching a stable copy-paste flow.
• §Open questions: add a ninth — "Should the page mention that the SDK rejects reserved-name overrides in substitutions (raising ValueError), or stay silent on the lower-level Python API entirely?" Recommendation: stay silent on the public manual; let SDK docs cover it.

Net

Two operator-facing claims reversed: the state-key indirect rotation is the expected result of single-dataset → split-dataset migration, not a corner case to promise around. --state-key-suffix moves out of the migration paragraph entirely and into its own backfill-and-canary subsection. Historical lineage preservation is one SQL query against the append-only state table, not a suffix-based archive step. The page can still lead with the property-graph workflow once #282 closes its remaining contract decisions.

[caohy1988]

Fresh pass after the latest #283 update.

The operator-facing plan is close. Two remaining points should be reflected before the page becomes copy-pasteable.

Findings

1. High: advanced explicit YAML mode needs the same two-dataset semantics as property-graph mode.

   The page keeps --ontology + --binding as the advanced override. In that mode, the binding file's target.dataset is the graph/write dataset. The page should not imply that --graph-dataset-id is only a property-graph-mode concept or that state-table location is always derived from a CLI flag.

   Recommended page wording for the three-rung ladder:

   • Default / production property-graph modes: --dataset-id is events, --graph-dataset-id is graph/write.
   • Advanced YAML override: --dataset-id is still events; graph/write dataset comes from binding.yaml (target.dataset). If the SDK accepts --graph-dataset-id in YAML mode, it must match the binding target; otherwise omit it.
   • State table defaults to the graph/write dataset after the SDK lands the Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 fix, regardless of input mode.

   Add this to the merge gates: Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 must define graph_dataset_id behavior in explicit-YAML mode (reject vs. validate-equals-binding-target) before adk-docs publishes the advanced override section.

2. High: fully-qualified property_graph.sql refs do not replace --graph-dataset-id.

   Users often fully qualify BigQuery refs in SQL. If the page shows fully-qualified graph-table refs, readers may think they do not need --graph-dataset-id. That is unsafe unless the SDK explicitly supports inference. Fully-qualified refs can make schema lookup succeed while the derived binding target / default state-table dataset still use the events dataset.

   Add a callout in the two-dataset section:

   Even if your property_graph.sql uses fully qualified table refs like project.graph_dataset.table, still pass --graph-dataset-id "$GRAPH_DATASET" in split-dataset deployments. The flag tells the SDK which dataset is the graph/write target and where to place the default materialization state table; the SQL refs alone are not the authoritative target contract.

   If Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 chooses to detect and error on missing graph_dataset_id when fully-qualified refs point elsewhere, the page can mention that as a troubleshooting note.

3. Medium: the state-table statement should be phrased as "graph/write dataset," not only GRAPH_DATASET.

   For property-graph mode, graph/write dataset = --graph-dataset-id. For YAML mode, graph/write dataset = binding.target.dataset. The page can use GRAPH_DATASET in commands, but the conceptual sentence should say:

   _bqaa_materialization_state lives with the graph/write tables by default.

   Then explain the concrete source per mode. This avoids a subtle contradiction in the advanced override path.

4. Low: keep the public manual silent on Python substitutions; SDK docs should own it.

   The latest gate includes reserved-name policy for substitutions, which is good for SDK readiness. For adk-docs, keep the published page focused on CLI flags and SQL placeholders. Do not mention substitutions unless the page adds a Python API section later.

Recommended body edits

• Add a merge gate: Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 defines graph_dataset_id behavior in explicit-YAML mode and state-table defaulting is unified through the resolved binding target.
• Add a two-dataset callout: fully-qualified SQL refs still require --graph-dataset-id in split deployments unless the SDK explicitly documents inference.
• Rephrase state-table location as "with the graph/write dataset by default," then map graph/write source by mode.

Net: the user manual should teach one mental model: events dataset is the read side; graph/write dataset is the materialization side. Property-graph mode gets graph/write from --graph-dataset-id; YAML mode gets it from binding.target.dataset.

[caohy1988]

Endorsement + additional gaps

All four findings correct. The "graph/write dataset" abstraction is the right operator-facing concept — it cleanly unifies both input modes, which simplifies the page.

Validation summary

• Concept abstraction: "graph/write dataset" is the right mental model. Property-graph mode: source is --graph-dataset-id. YAML mode: source is binding.target.dataset (bigquery_ontology/binding_models.py:57-66 confirms the field carries this). State-table defaulting unifies through binding.target.dataset once Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 lands the change.
• Fully-qualified refs gap: BigQuerySchemaProvider._split() at graph_schema_join.py:179-207 confirms — 3-part refs at :187-188 skip default_dataset entirely. So project.graph_dataset.entity_table in property_graph.sql resolves schema lookup against graph_dataset while binding.target.dataset (derived from dataset_id) still points at events. Silent split-brain. The page callout is the right reader-facing fix.
• substitutions out of the public manual: agreed. Reserved-name semantics are an SDK API decision (Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282); the page should teach CLI flags and SQL placeholders only.

Additional gaps

1. The "graph/write dataset" abstraction should drive the IAM table as well. Today the IAM section breaks down by dataset role (events vs graph). After the unified concept lands, the IAM row for the graph dataset can read: "graph/write dataset — write entity/relationship tables; metadata read for schema lookup; state-table writes; in YAML mode comes from binding.target.dataset, in property-graph mode comes from --graph-dataset-id." One row, two sources, single permission requirement.

2. The fully-qualified-refs callout will also need a "what error you'll see" line once Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 lands the typed guard. Pre-Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 the failure mode is silent split-brain; post-Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 it should be a clear GraphSchemaError naming the dataset mismatch and pointing operators at --graph-dataset-id. The page should mention this so operators reading the troubleshooting section can pattern-match the error message to the fix.

3. The three-rung ladder should call out one more mode-specific detail:

   • Default / production property-graph: --graph-dataset-id "$GRAPH_DATASET" (required for split deployments).
   • Production-compiled property-graph: same, plus --extraction-mode=compiled-only and reference extractors.
   • Advanced YAML override: do not pass --graph-dataset-id; the binding carries it. Trying to pass it gets rejected by the CLI per Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282.

   Without that mode-specific note, operators copying the production-property-graph command and pasting it into a YAML override would hit the rejection error and wonder what changed.

4. "Dry-run before scheduling" should be a strong recommendation in the periodic-materializer section. Once dry_run reports the state-table location accurately (per Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 acceptance), operators verifying their setup before deploying can run:

   bqaa context-graph \
     --dataset-id "$EVENTS_DATASET" \
     --graph-dataset-id "$GRAPH_DATASET" \
     --property-graph property_graph.sql \
     --dry-run

   and inspect the reported state-table location, fingerprints, and discovery window before any data is written. This is the cheapest mistake-prevention step the page can teach.

Recommended body edits to #283

• §Content scope, section 3 ("Schedule it with Cloud Run + Cloud Scheduler") — Two-dataset section: rephrase the state-table sentence as: "_bqaa_materialization_state lives with the graph/write tables by default. In property-graph mode, that's the dataset you pass via --graph-dataset-id; in YAML mode, it's binding.target.dataset."
• §Content scope, section 3 — IAM table: collapse "graph dataset (data)" and "graph dataset (metadata)" into a single "graph/write dataset" row with both permissions and a source note for each input mode.
• §Content scope, section 3 — Fully-qualified refs callout: add the "what error you'll see" line referencing the post-Tracking: SDK production cleanup — rename migration_v5, consolidate context-graph surface, blogpost-ready audit #282 typed GraphSchemaError and the fix (--graph-dataset-id "$GRAPH_DATASET").
• §Content scope, section 3 — new "Dry-run before scheduling" subsection: one paragraph + one command block showing the dry-run with --graph-dataset-id and what to verify in the output (state-table location, fingerprints, discovery window).
• §Content scope, section 5 (three-rung ladder): add the mode-specific --graph-dataset-id note to each rung. Property-graph rungs: pass it. YAML override: don't.
• §Coordination with the SDK cleanup / merge gates: add a sixth gate — "SDK has typed-error guard for fully-qualified DDL refs that point outside the explicit --graph-dataset-id / binding.target.dataset." Without this, the page would have to write defensive prose about the split-brain risk instead of pointing at a clear error message.

Net

The "graph/write dataset" concept is the right operator-facing mental model and makes one page-wide message work across both input modes. The remaining doc gaps are small: fold the IAM rows, mention the post-#282 typed error in the fully-qualified-refs callout, recommend dry-run-before-scheduling, and note the YAML-override-doesn't-take---graph-dataset-id rule in the three-rung ladder. After those edits, the page's operator-facing surface is consistent regardless of which input mode the reader picks.

[caohy1988]

Fresh review after #272 merged (docs(codelab): embed local images in generated Colab notebook):

I re-read #283 from the perspective that #272 is done, not pending. The prior dataset/state-table / --graph-dataset-id guidance still holds. The new impact is on the adk-docs asset and copy strategy: #272 makes the SDK Colab notebook safe by embedding local images, but that behavior is specific to the SDK notebook generator. It does not transfer automatically to adk-docs.

1. Do not copy image data URIs from the generated notebook into adk-docs. The generated examples/codelab/periodic_materialization/colab_notebook.ipynb is now expected to contain base64 image data for Colab portability. The adk-docs page should use normal committed image assets under docs/integrations/assets/bigquery-agent-analytics/, not embedded data URIs. Otherwise the integration page gets bloated and loses normal asset ownership.

2. The “one asset to migrate” line is stale if the page copies the codelab/blog sections. Current SDK sources reference three relevant images:

   • context-graph-flow.png
   • graph-visualization.png
   • ca-conversation.png

   They exist under both docs/codelabs/images/ and docs/blog/images/. Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 should either explicitly migrate only the architecture image and avoid copying the other illustrated sections, or list all three as potential assets to migrate. As written, “one asset” is likely too narrow for the proposed periodic-materialization/manual expansion.

3. Copied markdown image paths need an adk-docs rewrite step. SDK codelab markdown uses images/... paths because claat and the SDK notebook generator know how to handle that source layout. The adk-docs integration page should rewrite those to its own asset path, for example assets/bigquery-agent-analytics/... or the repo’s established equivalent. docs(codelab): embed local images in generated Colab notebook #272 does not help here; it only rewrites images during SDK notebook generation.

4. Add a merge gate that the SDK codelab source and generated notebook are in sync before adk-docs copies content. The concrete check already exists in SDK CI:

   python scripts/generate_colab_from_codelab.py --check docs/codelabs/periodic_materialization.md examples/codelab/periodic_materialization/colab_notebook.ipynb

   If Tracking: expand adk.dev/integrations/bigquery-agent-analytics/ into a full user manual #283 is using SDK codelab/manual text as source material, this should be part of the “ready to copy” gate. It prevents adk-docs from importing stale prose or screenshots from a markdown/notebook mismatch.

5. Make source ownership explicit in the sync strategy. Recommended wording: “Copy prose from SDK markdown sources and copy image files from SDK image directories; never copy from generated Colab notebook cells.” That keeps the adk-docs manual tied to source documents, not generated artifacts.

Net: #272 lowers the Colab portability risk, but it increases the need for an explicit asset-copy rule in #283. The adk-docs page should consume SDK markdown and source images, while leaving the generated notebook’s embedded images entirely out of the cross-repo sync path.