Blog post narrative — Context Graph + Decision Trace for the C-suite (5-min read, zero graph jargon)

## Goal

Write a BigQuery blog post that lands the Context Graph + Decision Trace value proposition with **executive business customers who have zero graph-tech background** and earns a "wow" from a C-suite reader in **five minutes or less**. The post should ship the **minimum product surface** that proves the story — three crisp questions, three screenshots, three numbers — and nothing more.

This issue is the narrative spec + outline. PR-time work is then writing copy, capturing screenshots, and running numbers.

## Product status — Preview disclosures required

Before publish, the post **must** correctly label feature availability. Per current Google Cloud docs:

- **BigQuery Conversational Analytics** is in **Preview** ([docs](https://docs.cloud.google.com/bigquery/docs/conversational-analytics) / [create conversations](https://docs.cloud.google.com/bigquery/docs/create-conversations)). Data agents can use knowledge sources such as tables, views, **graphs**, or UDFs — so graph-backed conversational queries are real, but the post must say "Preview," not "GA" or "now available."
- **BigQuery property graphs / GQL** are also in **Preview** ([graph overview](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/graph-intro) / [CREATE PROPERTY GRAPH](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/graph-schema-statements) / [GRAPH_TABLE](https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/graph-sql-queries)).
- **BigQuery Agent Analytics Plugin** (in ADK) and the **BigQuery Agent Analytics SDK** are not Preview.

The post should treat Preview as a feature, not a footnote — Google Cloud Preview programs are how launch customers get early access. Recommend a single "Available now in Preview" callout near Beat 5 (the CTA) rather than burying Preview disclosures inline beat-by-beat.

**All scenarios in this post are illustrative and synthetic** (mortgage decline, marketing-budget pull, prior-auth) **until Legal + PMM approve a named example.** Add an explicit synthetic-data note in the post (or anonymize) before publish.

## Source materials

- [Issue #158 / the gist](https://gist.github.com/haiyuan-eng-google/8d4e70fec40a355e6d5ac5e66eee51f4) — the existing BQ Decision Trace narrative draft (positioning, framing).
- [PR #155](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/155) — Migration V5 fixture foundation + four-guarantee notebook. Provides the MAKO domain model (`ContextSnapshot → DecisionPoint → Candidate → SelectionOutcome → DecisionExecution`) and the executed evidence (`rows_materialized total=38`, `GRAPH_TABLE count=3`, end-to-end live run on `test-project-0728-467323`).
- [PR #157](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/pull/157) — MAKO reference extractor + tests (17/17 passing). Provides the deterministic-extractor cost story (compiled extractor vs LLM-based extraction) and the `partOfSession` hub-shape traversal.

---

## What ships in this post — the four-product showcase

The post is fundamentally a **product showcase**, framed as a business story. Four BigQuery surfaces work together as one solution; the post names each one explicitly because the executive takeaway is "this is one BigQuery story, not a stack of new things to procure."

### 1. BigQuery Agent Analytics Plugin (in ADK) — the capture layer

**What it does:** Drop-in plugin (`BigQueryAgentAnalyticsPlugin`) that captures every agent event to `agent_events` via the BigQuery Storage Write API. No new instrumentation in your agent code.

**What we ship:** The 16-column `agent_events` schema (timestamp, event_type, agent, session_id, invocation_id, user_id, trace_id, span_id, parent_span_id, content JSON, content_parts REPEATED RECORD, attributes JSON, latency_ms JSON, status, error_message, is_truncated); 20 emitted event types including `LLM_REQUEST`, `LLM_RESPONSE`, `TOOL_STARTING`, `TOOL_COMPLETED`, `HITL_*`, `A2A_INTERACTION`; 17 auto-generated typed views (`v_llm_request`, `v_tool_completed`, `v_a2a_interaction`, …). **OTel-compatible IDs when an OTel provider is configured; standalone BQAA still works with fallback IDs.**

**Post-copy framing:** *"A flight recorder that turns on by itself the moment your agent boots."*

### 2. BigQuery Agent Analytics SDK — Context Graph — the meaning layer

**What it does:** Turns flat trace events into a queryable property graph by describing your decision domain as an ontology + binding. The graph captures **what the agent saw, what it weighed, what it picked, and why** — automatically, every run.

**What we ship (showcase in PRs #155 + #157):**
- TTL → ontology.yaml → binding.yaml → BQ DDL → property-graph SQL pipeline. MAKO demo: 18 ontology entities, 6 binding entities, 7 relationships.
- `ontology-build`, `binding-validate`, and `gm compile --emit-concept-index` CLI surface.
- **Compiled extractors** that swap per-event LLM extraction for deterministic code on the hot path — the cost-savings story.
- **Reference extractor for the 5 MAKO decision-flow tools** (`capture_context`, `propose_decision_point`, `evaluate_candidate`, `commit_outcome`, `complete_execution`) with `AgentSession` + `partOfSession` hub-edge synthesis. 17/17 tests passing.
- **Schema-drift detection** (`binding-validate`) — catches column renames before they corrupt the graph.
- **Concept index** — agents and queries can ask in friendly labels (`"DecisionExecution"`) instead of fully qualified table names.

**Post-copy framing:** *"Decisions don't sit in isolation. They link to the situation that triggered them, the data they read, the action they took, and the consequence that followed."*

### 3. BigQuery property graphs / GQL (Preview) — the storage + traversal layer

**What it does:** BigQuery's graph capability (currently in Preview). Every node and edge is a regular BigQuery table; GQL traverses the relationships, plain SQL hits the same tables, dashboards and IAM stay in place.

**What we ship:** The blog doesn't ship the property-graph engine itself — Google Cloud already shipped it in Preview. The blog ships the **integration story**: agent events → SDK materializer → property-graph DDL → live GQL/SQL queries against your existing BQ project. **No separate graph database.** Engineers can use SQL and GQL in BigQuery; business users can ask in natural language via Conversational Analytics (Preview, see #4).

**Post-copy framing:** *"BigQuery's property-graph support, currently in Preview, means there's no separate graph database to stand up. Engineers query in SQL or GQL; the data, IAM, and billing all stay where they already live."*

### 4. BigQuery Conversational Analytics (Preview) — the access layer

**What it does:** Natural-language interface over BigQuery data. Per the Conversational Analytics docs, data agents can use tables, views, **graphs**, or UDFs as knowledge sources — so business users can ask graph-backed questions in plain English and get a structured answer back.

**What we ship:** The blog showcases BigQuery Conversational Analytics (Preview) configured against the Migration V5 property graph as a knowledge source. The executive in Beat 2 types a plain-English audit question; Conversational Analytics handles the rest and returns a structured answer card. This is **the piece that makes the post viable for a C-suite reader**; without it, the demo requires SQL/GQL literacy and the audience filter fails.

**Suggested copy (PMM-safe):**

> "BigQuery Conversational Analytics, currently in Preview, can use the generated property graph as a knowledge source so business users can ask graph-backed questions in natural language."

The post should describe the result (structured answer card) without claiming a specific generated query language — Conversational Analytics returns text, code, and reasoning, but the exact form of the generated code for graph-backed questions isn't guaranteed to be GQL for every question shape.

### The four-product flow, one diagram

```
Agent runs (ADK)
│
▼
[1] BQ Agent Analytics Plugin ──► agent_events (BigQuery table)
│
▼
[2] BQ Agent Analytics SDK Context Graph
ontology + binding + compiled extractors
│
▼
[3] BigQuery property graphs / GQL (Preview)
│
▼
[4] BigQuery Conversational Analytics (Preview) ──► "Why did agent X do Y?"
│
▼
(Executive reads answer)
```

This diagram is the one mid-post visual (in addition to the three query screenshots). It earns its space because it shows the entire stack on one page and makes the **"no separate graph database, no separate operational stack to procure"** claim concrete. (Note: SQL and GQL are both BigQuery surfaces — both are available to engineers.)

---

## The audience filter

Every sentence in the post must survive this test: "Would a CFO, CISO, or COO with no graph background read this in their feed and care?"

If the sentence requires the reader to know what an ontology / RDF / property graph / GQL / RDF-TTL / triplestore / SPARQL is, **cut it or wrap it in plain language**. The post can name those technologies once, in a single "for the technical readers" sidebar, never in the main flow.

**Exception:** the four product names (BQ Agent Analytics Plugin, BQ Agent Analytics SDK Context Graph, BigQuery property graphs / GQL Preview, BigQuery Conversational Analytics Preview) are named explicitly because the executive recognizes them as BigQuery surface area, not as new things to procure. Preview status is acknowledged where applicable.

---

## The narrative arc — five minutes, six beats

### Beat 0 — The boardroom moment (30 sec)

Open in the C-suite's world. Concrete scenario. One paragraph. **All scenarios below are illustrative / synthetic until Legal + PMM approve.**

- A bank's autonomous credit agent declined 412 mortgage applications last quarter. The audit committee wants the rationale for the 23 that the borrower appealed. Today: "engineering will dig through logs, expect 3-6 weeks."
- A retailer's marketing-planning agent pulled $2.4M of budget out of a campaign mid-flight. The CMO needs to defend the call in tomorrow's earnings prep.
- A health-payer's prior-authorization agent denied 1,800 procedure requests on Friday. By Monday the state regulator is on the phone.

Lead with the **business stakeholder's panic**, not the technology.

### Beat 1 — What changed (60 sec)

The pivot. Three sentences:

> Every decision an AI agent makes — what it saw, what it weighed, what it picked, and why — is now captured automatically as the agent runs, into BigQuery, with no new pipeline. The decisions don't just become searchable; they connect to one another so you can ask, "what led to this?" the same way an investigator would. Your audit team asks the question in English (via BigQuery Conversational Analytics, currently in Preview); the answer comes back in seconds.

The third sentence is the Conversational Analytics hook, with Preview disclosure. It pre-frames Beat 2.

### Beat 2 — The "show me" moment (90 sec) — **THIS IS THE WOW**

**The single most important beat.** Open BigQuery Conversational Analytics (Preview). Type the question in plain English. Screenshot the answer. Under 90 seconds of reading time.

> **What the executive types into BigQuery Conversational Analytics (Preview):**
>
> *"Why did agent A-1188 deny customer 4029-7's loan on March 11?"*
>
> *(All identifiers and figures in this example are synthetic.)*
>
> **What Conversational Analytics returns (one structured answer card):**
>
> - **Context the agent saw:** Customer 4029-7 applied for a $340K mortgage. Credit score 712. Debt-to-income 41%. Two recent late payments flagged.
> - **Decision the agent had to make:** Approve, refer to human review, or decline.
> - **Options the agent weighed:**
> - ✅ **Decline** (chosen — confidence 0.83) — *"DTI exceeds our 40% threshold and two recent late payments fall inside the 90-day risk window."*
> - ❌ Refer to human (0.51) — *"DTI is borderline but recent payment behavior is the harder signal."*
> - ❌ Approve (0.14) — *"DTI breach is structural, not transient."*
> - **What happened next:** Outcome recorded; applicant notified; appeals queue entry created.

**Three things to call out in the copy:**

1. *"That answer was generated in [N] seconds from a question asked in plain English."*
2. *"The same data is also available to your engineering team in SQL and to your data scientists in GQL — all against the same BigQuery dataset."* (Both SQL and GQL named so we don't imply BigQuery has no query language for graphs.)
3. *"Conversational Analytics is reading from a property graph the BigQuery Agent Analytics SDK built for you automatically, the moment the agent ran."*

Show the SQL/GQL **collapsed** below the screenshot — technical readers expand it; executives skip past. (Don't promise in the copy that Conversational Analytics generated GQL specifically; just show whatever query it produced for the technical reader to inspect.)

### Beat 3 — What this actually is (60 sec) — explicit product callout

Four short paragraphs, one per product, plain-language framing with Preview where applicable:

- **BigQuery Agent Analytics Plugin (in ADK).** *"A drop-in plugin for your agent that captures every event — decisions, tool calls, model requests, human approvals — into BigQuery, automatically. Think of it as the flight recorder; it turns on the moment your agent boots. Uses OpenTelemetry-compatible identifiers when your team has OTel configured, and works standalone otherwise."*
- **BigQuery Agent Analytics SDK — Context Graph.** *"Captures aren't enough. The SDK turns those raw events into a connected web: which situation led to which decision, which decision picked which option, which option triggered which outcome. The web is auditable, queryable, and — critically — it understood your business domain because you described it once in a small configuration file."*
- **BigQuery property graphs / GQL (Preview).** *"This web is stored natively in BigQuery (Preview). No separate graph database to operate. Engineers can query in SQL or in GQL — both work against the same BigQuery tables, the same IAM, the same billing, the same dashboards."*
- **BigQuery Conversational Analytics (Preview).** *"And on top of the graph: natural-language access. BigQuery Conversational Analytics (Preview) can use the property graph as a knowledge source, so the audit team asks the question the way they'd ask a colleague — 'why did we decline customer X?' — and gets a structured answer back. The five-week forensic investigation is now a thirty-second meeting question."*

Avoid "ontology" and "graph traversal" in the body. They appear only in the technical sidebar.

### Beat 4 — The numbers (45 sec)

Four concrete numbers in a small table:

| Question the executive asks | Number | Source |
|---|---|---|
| How fast can my audit team answer "why did the agent do that?" | **Seconds, not weeks** | Beat 2 hero query timing |
| What does this cost to run at the agent's scale? | **~X% cheaper than LLM-based extraction** | PR #157 compiled extractors + the savings table in cell 3.7 (post-#156 follow-up) |
| How long to set up for our team? | **One notebook, one afternoon** | PR #155 four-guarantee notebook executed end-to-end |
| What does my organization need to procure? | **No new database or serving stack.** Technical teams keep BigQuery SQL, IAM, billing, and dashboards; executives can use BigQuery Conversational Analytics (Preview). | The four-product story above |

**TBD before publish:** swap "~X%" for a measured number from the savings table once #156 / the follow-up commit on PR #157 lands. Don't ship a placeholder.

### Beat 5 — One call to action (15 sec)

One link. One thing to do. Include a single Preview-availability note.

> **Available now in Preview** — BigQuery property graphs / GQL and BigQuery Conversational Analytics are currently in Preview on Google Cloud. The BigQuery Agent Analytics Plugin and SDK are generally available.
>
> Want to ask the same question of your own agents? Run the notebook → [`examples/migration_v5_demo_notebook.ipynb`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/migration_v5_demo_notebook.ipynb). It spins up a scratch dataset, runs three real agent sessions, materializes the Context Graph, and (when configured against a Preview-enabled project) lets BigQuery Conversational Analytics use the graph as a knowledge source. Under fifteen minutes from clone to first English question.

---

## Minimum product surface — exactly three questions

All three expressed as natural-language questions to BigQuery Conversational Analytics (Preview). Each one has the underlying query collapsed below for technical readers (the post does not claim the generated query is specifically GQL — Conversational Analytics may return SQL, GQL, or a hybrid depending on the question; PMM should confirm the form to display in the screenshot). These three together = the **audit / portfolio / monitor** triad that maps to how regulated industries already think about controls.

### Question 1 — The audit question *("why did the agent do X?")*

Case-level. This is the Beat 2 hero.

> *"Why did agent A-1188 deny customer 4029-7's loan on March 11?"*

Returns the hub-shape traversal: context → decision point → candidates → chosen outcome → rationale → downstream effect. Surfaces PR #155 Beat 4 traversal + PR #157 `complete_execution` synthesis of `DecisionExecution` + `AgentSession` + `partOfSession`.

### Question 2 — The portfolio question *("how many decisions, what did they cost?")*

Aggregate. Triggered when a leader needs to see the agent's footprint across a quarter.

> *"How many declines did our credit agents make last quarter, what was the average confidence score, and which rationale categories drove them?"*

Returns: counts by decision type, distribution of confidence scores, top rationale categories with frequencies, cost per decision in tokens and dollars, latency P50/P95. Aggregation over the `DecisionExecution` node table.

### Question 3 — The monitor question *("alert me when…")*

Continuous. Triggered when governance/risk needs ongoing eyes.

> *"Alert me when any decline cites 'DTI exceeds threshold' for borrowers under 25."*

BQ scheduled query / Looker tile / Cloud Logging filter that fires when the rationale matches a pattern (e.g., fair-lending flag). Ongoing governance, not one-shot forensics.

---

## What the post does NOT include

Cut hard. Anything in this list is a follow-up post:

- Ontology authoring walkthrough.
- TTL / YAML / binding file shapes.
- The four-guarantee framing from the notebook (own / validate / cheap / resolve). Engineering audience.
- Property-graph DDL.
- `gm compile --emit-concept-index` mechanics.
- Schema-drift detection (the `--validate-binding` story in PR #155 Beat 2).
- Comparison vs Neo4j / Neptune / RDF stores.
- GenAI semantic conventions / OTel mapping (issue #153 work).
- Detailed Conversational Analytics query-generation mechanics. Show it working; don't explain the internals.
- GA claims for Preview features.
- Customer names without explicit Legal + PMM approval.

---

## Visuals to capture

**Three primary screenshots + one architecture diagram:**

1. **Beat 2 hero — Conversational Analytics screenshot.** The natural-language question typed in. The structured answer card returned. **Mark Preview clearly on or near the screenshot.** Use realistic but synthetic data. Capture the underlying generated query in a collapsed pane below — but do not pre-label it as GQL in the caption; let the technical reader see what Conversational Analytics actually generated.
2. **Beat 4 numbers table.** Four rows, three columns. Plain table.
3. **Beat 5 CTA tile.** "Run this notebook" card with the GitHub link, the expected runtime, and the Preview availability note.
4. **The four-product architecture diagram.** One page. The flow from Beat 3, rendered as boxes-and-arrows, with Preview tags on boxes 3 and 4. Captioned: *"Four BigQuery surfaces. One story. No new database to stand up."*

**Optional sidebar visuals (technical readers only):**

- A small node-edge diagram showing the six-node MAKO shape.
- A code expander under Question 1 / 2 / 3 showing whatever query Conversational Analytics actually generated (SQL, GQL, or hybrid).

---

## Proof points to gather before publish

- [ ] **Run** the executed notebook (PR #155) end-to-end against a fresh scratch dataset. Confirm Beat 2 hero screenshot renders with realistic synthetic data.
- [ ] **Confirm with PMM** the exact current Preview status of BigQuery Conversational Analytics and BigQuery property graphs / GQL. Capture any flag / opt-in / region restrictions that should appear in the Preview callout.
- [ ] **Confirm with the Conversational Analytics product team** the supported pattern for using a property graph as a knowledge source. The phrasing should match the official docs.
- [ ] **Decide screenshot caption for Beat 2**: show the generated query in a collapsed pane, but don't pre-label its language in the caption — let the actual screenshot speak.
- [ ] **Time** the audit query end-to-end on a representative dataset. Replace "[N] seconds" in Beat 2 with the measured value.
- [ ] **Measure** the cost savings number for Beat 4 row 2 once #156 / the follow-up commit on PR #157 lands. Replace `~X%` with a real measured value.
- [ ] **Mark all examples as synthetic** in the post body, the screenshots, and the figure captions. No real customer data, no real account numbers.
- [ ] **Legal review** on the loan-decline / prior-auth example phrasing — illustrative, but regulated domains.
- [ ] **PMM alignment** with BigQuery Conversational Analytics' launch motion — if their Preview is approaching GA, the post could be timed against that beat.
- [ ] **Publish channel** confirmed (Google Cloud blog, BigQuery vertical).

---

## Sidebar — "for the engineering audience" (one paragraph, end of post)

After the CTA, for technical readers:

> Under the hood this is a BigQuery property graph (Preview) generated from an ontology that describes your decision domain. Agent events are captured by the BigQuery Agent Analytics Plugin (a drop-in ADK plugin, generally available) and materialized into node + edge tables by the BQAA SDK. The SDK ships a deterministic extractor for the MAKO decision-flow shape used here (`ContextSnapshot → DecisionPoint → Candidate → SelectionOutcome → DecisionExecution → AgentSession`) and falls back to an LLM-based extractor for events it doesn't recognize. The graph is queryable in BigQuery's native GQL, in plain SQL, and — through BigQuery Conversational Analytics (Preview) configured with the graph as a knowledge source — in natural language. The four engineering guarantees (own, validate, cheap, resolve) are walked end-to-end in [`examples/migration_v5_demo_notebook.ipynb`](https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/blob/main/examples/migration_v5_demo_notebook.ipynb). Start there.

This is the only place "property graph," "ontology," "GQL," "extractor," and the four-guarantee framing appear. Everywhere else: plain language.

---

## Length and pacing target

| Beat | Words | Reading time |
|---|---|---|
| 0 Boardroom | 80–100 | 30 s |
| 1 What changed | 130–150 | 60 s |
| 2 Show me (Conversational Analytics Preview hero) | 200–240 + screenshot | 90 s |
| 3 What it is (four-product callout, Preview marks) | 220–260 | 60 s |
| 4 Numbers | 110 + table | 45 s |
| 5 CTA + Preview availability note | 60 | 15–20 s |
| Engineering sidebar | 150 | (optional reading) |
| **Total** | **~1,050 words** | **≈5 min** |

---

## Open questions for the team

1. **Which scenario opens?** Banking (mortgage decline), retail (marketing pull), or healthcare (prior-auth). PMM call.
2. **Preview disclosures placement:** single "Available now in Preview" callout near Beat 5 (recommended), or distributed Preview tags through the post?
3. **Joint motion with the BigQuery Conversational Analytics PMM team?** This post is meaningfully better with their Preview integration; their Preview launch is meaningfully better with this proof point. Worth aligning calendars.
4. **Cost savings:** hard percentage (if #156 lands clean) vs directional claim + chart.
5. **Named customer or anonymized for the boardroom scenario.**
6. **Publish channel** — Google Cloud blog, BigQuery vertical; confirm before final draft.

---

## Next steps

1. Get sign-off on this narrative arc + four-product showcase + Preview disclosure approach (this issue).
2. Confirm with PMM the exact Preview status of Conversational Analytics + BQ property graphs / GQL and the supported "graph as knowledge source" configuration.
3. Run the notebook end-to-end and capture the Beat 2 Conversational Analytics hero screenshot.
4. Wait for #156 / the PR #157 follow-up commit to land the savings number.
5. Draft v1 copy against this outline.
6. PMM + Legal review (regulated-domain examples, Preview disclosures, synthetic-data labeling).
7. Publish.

Closing the gap from "BQ AA SDK is technically impressive" to "the CFO understands why this matters in five minutes" is the single highest-leverage marketing motion this product has right now. The narrative above is engineered for that gap — strengthened by naming the four BigQuery surfaces explicitly (Plugin, SDK Context Graph, BigQuery property graphs / GQL **Preview**, BigQuery Conversational Analytics **Preview**) so the takeaway is *"one BigQuery story, no new database to procure."*