feat(ontology): add --skip-property-graph for user-owned graph DDL (#104) (#108)

caohy1988 · web-flow · commit 292320ba126a · 2026-05-02T23:28:08.000-07:00
* feat(ontology): add --skip-property-graph for user-owned graph DDL (#104) Lets users with their own CREATE PROPERTY GRAPH DDL — managed by Terraform, dbt, or hand-authored — populate base tables from BQ AA traces without overwriting the graph object on every run. Changes - ontology_orchestrator.build_ontology_graph gains skip_property_graph: bool = False. When True, phase 5 is not invoked: no OntologyPropertyGraphCompiler is constructed, no CREATE OR REPLACE PROPERTY GRAPH runs. - Result dict gains property_graph_status with values "created" / "failed" / "skipped:user_requested", plus skipped_reason ("user_requested") when phase 5 was skipped. - ontology-build CLI gains --skip-property-graph and threads property_graph_status through to the curated output dict so JSON consumers can distinguish "skipped" from "failed" without parsing stderr. - Exit handling: skipped_reason == "user_requested" exits 0 silently; the existing exit-1-with-error behavior is preserved for actual graph-creation failures. Tests - test_skip_property_graph_does_not_construct_compiler asserts the compiler class is never called (mock.assert_not_called) when the flag is set. - test_property_graph_status_created_on_success and test_property_graph_status_failed_on_compiler_false cover the two default-mode status values. - CLI tests cover exit 0 with status="skipped:user_requested", default skip_property_graph=False threading, and exit 1 with status="failed" on actual creation failure. 135/135 tests in test_ontology_orchestrator.py + test_cli.py pass. * docs+test: ontology-build doc + live skip-property-graph test (#104) Closes the two #104 acceptance gaps flagged on PR #108 review: (1) Docs missing - New docs/ontology/ontology-build.md documents the bq-agent-sdk ontology-build orchestrator end-to-end and the new --skip-property-graph flag. - Includes a status-field reference table mapping property_graph_status (created / failed / skipped:user_requested) to property_graph_created and CLI exit code. - Includes Python API example showing skip_property_graph=True with expected result-dict shape. (2) No gated live integration test - New TestSkipPropertyGraph class in tests/test_integration_ontology_binding.py. - Gated on RUN_LIVE_BIGQUERY_TESTS=1 like the existing live tests. - Sequence: create authored CREATE PROPERTY GRAPH directly via SQL (simulating Terraform/dbt-managed DDL), capture the post-DDL CURRENT_TIMESTAMP(), run build_ontology_graph(..., skip_property_graph=True), then query JOBS_BY_PROJECT for any 'CREATE OR REPLACE PROPERTY GRAPH' jobs in the post-timestamp window — assert zero. Also re-runs the showcase GQL query to confirm the user's graph object still works after the SDK run. - The timestamp is captured AFTER the authored DDL specifically to avoid the false-positive trap called out in #107 cell 1.3. * test+docs: harden live test, add text-format check, link doc (#104) Addresses three review findings on PR #108: (1) Live test now exercises real extraction/materialization - Pass dataset_id=_DATASET, table_id=_TABLE so extraction reads the production agent_events table where YMGO ADCP session data lives. Materializer still writes to scratch_dataset because spec entity sources arrive 3-part-qualified to binding.target.dataset via _qualify_source (resolved_spec.py:141). - Assert sum(rows_materialized.values()) > 0 to catch the silent- empty-graph trap where ontology_graph.py:683 returns an empty ExtractedGraph if extraction fails (e.g. wrong source dataset). (2) JOBS_BY_PROJECT assertion narrowed to the test's own graph - Filter by both 'CREATE OR REPLACE PROPERTY GRAPH' keyword AND the fully-qualified graph reference ({_PROJECT}.{scratch_dataset}.{spec.name}). Prevents false-fail on unrelated CREATE OR REPLACE PROPERTY GRAPH jobs running concurrently in the same project from other tests/developers. (3) docs/README.md gains a row for the new ontology-build doc. (4) New CLI test test_skip_property_graph_status_visible_in_text_format asserts property_graph_status appears in --format=text output, pinning the contract that the status field is not JSON-only. 7/7 ontology-build CLI tests pass. * test+docs: harden DDL-detection filter, soften DDL claims (#104) Addresses three review findings on PR #108: (1) Live test DDL-detection blind spot The previous filter required the regressed CREATE OR REPLACE PROPERTY GRAPH to target _PROJECT.<scratch_dataset>.<spec.name>. But if skip_property_graph regressed, the compiler would actually target _PROJECT._DATASET.<spec.name> (the orchestrator's dataset_id argument is _DATASET in this test, used for extraction of agent_events). The blind spot: a regression could fire DDL that the test would not catch. Fixed by replacing the fully-qualified-graph-ref filter with two narrower constraints that catch the regression in either dataset: - graph name (spec.name) — present in the DDL string regardless of which dataset the compiler targets - sdk_feature='ontology-gql' label — only SDK-issued property-graph jobs carry this label per ontology_property_graph.py:465; the test's setup CREATE PROPERTY GRAPH (issued via direct SQL) does not, so it does not trip the assertion (2) docs/ontology/ontology-build.md: document graph_ref limitation Added a "Known limitation" section noting that result["graph_ref"] reports the extraction dataset, not the binding's target dataset, in split source/target setups. The materialized base tables themselves still go to the binding's target dataset per the resolved spec; only the reported string is affected. (3) docs/ontology/ontology-build.md: soften DDL-options wording "additional indexes, dialect-specific options" was overreaching for BigQuery property graphs; tightened to "custom labels or other DDL details the SDK's compiler doesn't generate." 136/136 tests pass. * test: correct comment on label-filter rationale (#104) The previous comment claimed the test's setup CREATE PROPERTY GRAPH job did not carry the sdk_feature='ontology-gql' label. That was factually wrong: setup goes through OntologyPropertyGraphCompiler.create_property_graph() (line 387), which does carry the label. The test logic was already correct — the setup job is excluded by the post-setup timestamp captured in step 2, not by the label filter. The label filter excludes user-authored raw SQL DDL jobs (without SDK labels), which is its actual purpose. Only the comment needed to change. No code change. * style: apply autoformat to test files Run bash autoformat.sh (isort + pyink). Fixes the Format check CI job that was failing on PR #108. No behavior change.
diff --git a/docs/README.md b/docs/README.md
@@ -36,6 +36,7 @@ architecture, rationale, and implementation plans behind key SDK features.
 | [ontology/compilation.md](ontology/compilation.md) | Compilation — resolving ontology + binding into backend DDL |
 | [ontology/cli.md](ontology/cli.md) | CLI design for the `gm` tool (validate, compile, import-owl) |
 | [ontology/owl-import.md](ontology/owl-import.md) | OWL import — converting OWL ontologies to YAML format |
+| [ontology/ontology-build.md](ontology/ontology-build.md) | `bq-agent-sdk ontology-build` orchestrator + `--skip-property-graph` reference |
 
 ## Deployment Surfaces
 
diff --git a/docs/ontology/ontology-build.md b/docs/ontology/ontology-build.md
@@ -0,0 +1,88 @@
+# `bq-agent-sdk ontology-build` — End-to-End Orchestrator
+
+`bq-agent-sdk ontology-build` runs the SDK's full ontology pipeline end-to-end against a populated `agent_events` table:
+
+1. Load the spec (`--ontology X.yaml --binding Y.yaml`).
+2. Extract an `ExtractedGraph` from agent telemetry via `AI.GENERATE`.
+3. Create physical entity/relationship tables (`CREATE TABLE IF NOT EXISTS`).
+4. Materialize extracted nodes/edges into those tables.
+5. Run `CREATE OR REPLACE PROPERTY GRAPH` to wire the BigQuery property graph object.
+
+The Python entry point is `bigquery_agent_analytics.ontology_orchestrator.build_ontology_graph(...)`. The CLI is a thin wrapper.
+
+## Skipping property-graph DDL
+
+Use `--skip-property-graph` when **the caller owns their own `CREATE PROPERTY GRAPH` DDL** — e.g., the property graph is provisioned via Terraform, dbt, or hand-authored SQL — and only wants the SDK to populate base tables.
+
+```
+bq-agent-sdk ontology-build \
+  --project-id my-project \
+  --dataset-id my-dataset \
+  --ontology my.ontology.yaml \
+  --binding my-bq-prod.binding.yaml \
+  --session-ids sess-1,sess-2 \
+  --skip-property-graph
+```
+
+Behavior with the flag set:
+
+- Phase 5 short-circuits. No `OntologyPropertyGraphCompiler` is constructed, no `CREATE OR REPLACE PROPERTY GRAPH` job runs. The user's existing graph object is unchanged.
+- Phases 1–4 run normally. Tables are created (`CREATE TABLE IF NOT EXISTS` is a no-op against pre-existing tables) and rows are materialized.
+- The CLI exits 0.
+- The output dict reports:
+
+  ```json
+  {
+    "property_graph_created": false,
+    "property_graph_status": "skipped:user_requested",
+    ...
+  }
+  ```
+
+  JSON consumers should read `property_graph_status` (not just `property_graph_created`) to distinguish a deliberate skip from a creation failure.
+
+## Status field reference
+
+The CLI's `property_graph_status` field has three values:
+
+| `property_graph_status` | `property_graph_created` | Exit code | Meaning |
+|---|---|---|---|
+| `"created"` | `true` | 0 | Phase 5 ran and BigQuery confirmed the graph object. |
+| `"failed"` | `false` | 1 | Phase 5 ran but the graph object was not created. The CLI prints "Property Graph creation failed" to stderr. Tables and rows were still materialized. |
+| `"skipped:user_requested"` | `false` | 0 | `--skip-property-graph` was set. Phase 5 did not run. No error message. |
+
+Without `--skip-property-graph`, the existing exit-1 behavior on graph-create failure is preserved exactly.
+
+## When to use this
+
+- **You already manage `CREATE PROPERTY GRAPH` in Terraform / dbt / a SQL file.** The SDK's `CREATE OR REPLACE PROPERTY GRAPH` would clobber your DDL on every run.
+- **Your property graph definition uses DDL details the SDK compiler doesn't emit.** You hand-authored the graph DDL to express custom labels or other DDL details the SDK's compiler doesn't generate.
+- **You want to populate your tables on a different cadence than you redefine the graph.** The graph definition rarely changes; the data is refreshed continuously.
+
+For all other cases, leave the flag off and let the SDK manage the property graph end-to-end.
+
+## Python API
+
+The flag is also available on `build_ontology_graph(...)`:
+
+```python
+from bigquery_agent_analytics.ontology_orchestrator import build_ontology_graph
+
+result = build_ontology_graph(
+    spec=resolved_spec,
+    session_ids=["sess-1"],
+    project_id="my-project",
+    dataset_id="my-dataset",
+    skip_property_graph=True,  # phase 5 skipped
+)
+
+assert result["property_graph_status"] == "skipped:user_requested"
+assert result["skipped_reason"] == "user_requested"
+assert result["property_graph_created"] is False
+```
+
+`skipped_reason` is only present when the phase was skipped; it is omitted when phase 5 ran (whether or not it succeeded).
+
+## Known limitation: `result["graph_ref"]` in split source/target setups
+
+`build_ontology_graph(...)` accepts a single `dataset_id` and uses it both for extraction (where `agent_events` lives) and for the `graph_ref` reported in the result dict (`{project_id}.{dataset_id}.{name}`). When `--skip-property-graph` is set and the caller's actual property graph lives in `binding.target.dataset` (different from the `dataset_id` used for extraction), `result["graph_ref"]` reports the **extraction dataset**, not the user-owned graph's dataset. The materialized base tables themselves still go to `binding.target.dataset` per the resolved spec — this only affects the reported `graph_ref` string. Tracked as a follow-up; not blocking for `--skip-property-graph` itself since the user already knows where their authored graph lives.
diff --git a/src/bigquery_agent_analytics/cli.py b/src/bigquery_agent_analytics/cli.py
@@ -1238,6 +1238,16 @@ def ontology_build(
     no_ai_generate: bool = typer.Option(
         False, help="Skip AI.GENERATE; fetch raw payloads instead."
     ),
+    skip_property_graph: bool = typer.Option(
+        False,
+        "--skip-property-graph",
+        help=(
+            "Skip CREATE OR REPLACE PROPERTY GRAPH. Use when the caller "
+            "owns their own property-graph DDL and only wants the SDK to "
+            "populate base tables. CLI exits 0 with "
+            "property_graph_status='skipped:user_requested'."
+        ),
+    ),
     fmt: str = typer.Option(
         "json",
         "--format",
@@ -1261,6 +1271,7 @@ def ontology_build(
         table_id=table_id,
         endpoint=endpoint,
         use_ai_generate=not no_ai_generate,
+        skip_property_graph=skip_property_graph,
     )
 
     output = {
@@ -1271,9 +1282,19 @@ def ontology_build(
         "tables_created": result["tables_created"],
         "rows_materialized": result["rows_materialized"],
         "property_graph_created": result["property_graph_created"],
+        "property_graph_status": result.get(
+            "property_graph_status",
+            "created" if result["property_graph_created"] else "failed",
+        ),
     }
     typer.echo(format_output(output, fmt))
 
+    # Distinguish "user-requested skip" (exit 0) from "creation failed"
+    # (exit 1). Same property_graph_created=False, different operator
+    # intent — JSON consumers read property_graph_status to tell them
+    # apart without parsing stderr.
+    if result.get("skipped_reason") == "user_requested":
+      return
     if not result["property_graph_created"]:
       typer.echo(
           "Error: Property Graph creation failed. "
diff --git a/src/bigquery_agent_analytics/ontology_orchestrator.py b/src/bigquery_agent_analytics/ontology_orchestrator.py
@@ -300,14 +300,16 @@ def build_ontology_graph(
     endpoint: str = "gemini-2.5-flash",
     use_ai_generate: bool = True,
     location: Optional[str] = None,
+    skip_property_graph: bool = False,
 ) -> dict[str, Any]:
   """Run the full ontology graph pipeline end-to-end.
 
   1. Load the YAML spec (or use pre-loaded ``spec``).
   2. Extract an ``ExtractedGraph`` from agent telemetry.
   3. Create physical tables (if not exists).
   4. Materialize extracted nodes/edges into tables.
-  5. Create the BigQuery Property Graph.
+  5. Create the BigQuery Property Graph (skipped when
+     ``skip_property_graph=True``).
 
   Args:
       session_ids: Sessions to extract from.
@@ -323,10 +325,22 @@ def build_ontology_graph(
       endpoint: AI.GENERATE model endpoint.
       use_ai_generate: If True, uses server-side AI extraction.
       location: BigQuery location.
+      skip_property_graph: When True, skip phase 5 (do not run
+          ``CREATE OR REPLACE PROPERTY GRAPH``). Use this when the
+          caller owns their own property-graph DDL and only wants
+          the SDK to populate base tables. The result dict reports
+          ``property_graph_created=False`` with
+          ``skipped_reason="user_requested"`` and
+          ``property_graph_status="skipped:user_requested"``, which
+          callers (and the CLI) use to distinguish a deliberate
+          skip from a creation failure.
 
   Returns:
       A dict with keys: ``spec``, ``graph``, ``tables_created``,
       ``rows_materialized``, ``property_graph_created``,
+      ``property_graph_status`` (one of ``"created"``, ``"failed"``,
+      ``"skipped:user_requested"``), ``skipped_reason`` (only set
+      when phase 5 was skipped, e.g. ``"user_requested"``),
       ``graph_name``, ``graph_ref``.
   """
   from .ontology_graph import OntologyGraphManager
@@ -391,24 +405,36 @@ def build_ontology_graph(
   rows_materialized = materializer.materialize(graph, session_ids)
   logger.info("Rows materialized: %s", rows_materialized)
 
-  # 5. Create property graph.
-  compiler = OntologyPropertyGraphCompiler(
-      project_id=project_id,
-      dataset_id=dataset_id,
-      spec=spec,
-      location=location,
-  )
-  pg_created = compiler.create_property_graph(graph_name=name)
-
   graph_ref = f"{project_id}.{dataset_id}.{name}"
-  logger.info("Property Graph %r created=%s.", graph_ref, pg_created)
 
-  return {
+  # 5. Create property graph (or skip when caller owns the DDL).
+  result: dict[str, Any] = {
       "spec": spec,
       "graph": graph,
       "tables_created": tables_created,
       "rows_materialized": rows_materialized,
-      "property_graph_created": pg_created,
       "graph_name": name,
       "graph_ref": graph_ref,
   }
+  if skip_property_graph:
+    logger.info(
+        "Property Graph creation skipped (skip_property_graph=True); "
+        "caller owns the DDL for graph %r.",
+        graph_ref,
+    )
+    result["property_graph_created"] = False
+    result["skipped_reason"] = "user_requested"
+    result["property_graph_status"] = "skipped:user_requested"
+  else:
+    compiler = OntologyPropertyGraphCompiler(
+        project_id=project_id,
+        dataset_id=dataset_id,
+        spec=spec,
+        location=location,
+    )
+    pg_created = compiler.create_property_graph(graph_name=name)
+    logger.info("Property Graph %r created=%s.", graph_ref, pg_created)
+    result["property_graph_created"] = pg_created
+    result["property_graph_status"] = "created" if pg_created else "failed"
+
+  return result
diff --git a/tests/test_cli.py b/tests/test_cli.py
@@ -2472,3 +2472,151 @@ def test_bad_spec_path_exit_2(self):
         ],
     )
     assert result.exit_code == 2
+
+  @patch("bigquery_agent_analytics.ontology_orchestrator.build_ontology_graph")
+  def test_skip_property_graph_exits_zero_with_status(self, mock_build):
+    """--skip-property-graph: exit 0, status='skipped:user_requested'."""
+    from bigquery_agent_analytics.ontology_models import ExtractedGraph
+
+    mock_build.return_value = {
+        "graph_name": "g",
+        "graph_ref": "proj.ds.g",
+        "graph": ExtractedGraph(name="test"),
+        "tables_created": {"mako_DecisionPoint": "p.d.decision_points"},
+        "rows_materialized": {"mako_DecisionPoint": 2},
+        "property_graph_created": False,
+        "skipped_reason": "user_requested",
+        "property_graph_status": "skipped:user_requested",
+        "spec": MagicMock(),
+    }
+
+    result = runner.invoke(
+        app,
+        [
+            "ontology-build",
+            "--project-id=proj",
+            "--dataset-id=ds",
+            f"--spec-path={self._SPEC_PATH}",
+            "--session-ids=sess1",
+            "--env=p.d",
+            "--skip-property-graph",
+        ],
+    )
+    assert result.exit_code == 0
+    # Skip path must NOT print the "Property Graph creation failed" stderr.
+    assert "Property Graph creation failed" not in result.output
+    parsed = json.loads(result.output)
+    assert parsed["property_graph_created"] is False
+    assert parsed["property_graph_status"] == "skipped:user_requested"
+
+    # Flag is threaded through to the orchestrator.
+    _, kwargs = mock_build.call_args
+    assert kwargs["skip_property_graph"] is True
+
+  @patch("bigquery_agent_analytics.ontology_orchestrator.build_ontology_graph")
+  def test_default_invocation_omits_skip_flag(self, mock_build):
+    """Default invocation passes skip_property_graph=False."""
+    from bigquery_agent_analytics.ontology_models import ExtractedGraph
+
+    mock_build.return_value = {
+        "graph_name": "g",
+        "graph_ref": "proj.ds.g",
+        "graph": ExtractedGraph(name="test"),
+        "tables_created": {},
+        "rows_materialized": {},
+        "property_graph_created": True,
+        "property_graph_status": "created",
+        "spec": MagicMock(),
+    }
+
+    result = runner.invoke(
+        app,
+        [
+            "ontology-build",
+            "--project-id=proj",
+            "--dataset-id=ds",
+            f"--spec-path={self._SPEC_PATH}",
+            "--session-ids=sess1",
+            "--env=p.d",
+        ],
+    )
+    assert result.exit_code == 0
+    parsed = json.loads(result.output)
+    assert parsed["property_graph_status"] == "created"
+
+    _, kwargs = mock_build.call_args
+    assert kwargs["skip_property_graph"] is False
+
+  @patch("bigquery_agent_analytics.ontology_orchestrator.build_ontology_graph")
+  def test_skip_property_graph_status_visible_in_text_format(self, mock_build):
+    """--format=text exposes property_graph_status to non-JSON consumers.
+
+    Pins the contract that property_graph_status is not JSON-only:
+    --format=table renders dict keys; --format=text falls back to a
+    readable representation. The status string must appear in either.
+    """
+    from bigquery_agent_analytics.ontology_models import ExtractedGraph
+
+    mock_build.return_value = {
+        "graph_name": "g",
+        "graph_ref": "proj.ds.g",
+        "graph": ExtractedGraph(name="test"),
+        "tables_created": {},
+        "rows_materialized": {},
+        "property_graph_created": False,
+        "skipped_reason": "user_requested",
+        "property_graph_status": "skipped:user_requested",
+        "spec": MagicMock(),
+    }
+
+    result = runner.invoke(
+        app,
+        [
+            "ontology-build",
+            "--project-id=proj",
+            "--dataset-id=ds",
+            f"--spec-path={self._SPEC_PATH}",
+            "--session-ids=sess1",
+            "--env=p.d",
+            "--skip-property-graph",
+            "--format=text",
+        ],
+    )
+    assert result.exit_code == 0
+    # The status string must appear in the text-format output so non-
+    # JSON consumers can see why the graph was not created.
+    assert "skipped:user_requested" in result.output
+
+  @patch("bigquery_agent_analytics.ontology_orchestrator.build_ontology_graph")
+  def test_property_graph_failure_status_failed(self, mock_build):
+    """When the orchestrator reports failure, exit 1 with status='failed'.
+
+    Distinguishes the failure path from the user-requested-skip path by
+    asserting the status field, not just the exit code.
+    """
+    from bigquery_agent_analytics.ontology_models import ExtractedGraph
+
+    mock_build.return_value = {
+        "graph_name": "g",
+        "graph_ref": "proj.ds.g",
+        "graph": ExtractedGraph(name="test"),
+        "tables_created": {},
+        "rows_materialized": {},
+        "property_graph_created": False,
+        "property_graph_status": "failed",
+        "spec": MagicMock(),
+    }
+
+    result = runner.invoke(
+        app,
+        [
+            "ontology-build",
+            "--project-id=proj",
+            "--dataset-id=ds",
+            f"--spec-path={self._SPEC_PATH}",
+            "--session-ids=sess1",
+            "--env=p.d",
+        ],
+    )
+    assert result.exit_code == 1
+    assert "Property Graph creation failed" in result.output
diff --git a/tests/test_integration_ontology_binding.py b/tests/test_integration_ontology_binding.py
diff --git a/tests/test_ontology_orchestrator.py b/tests/test_ontology_orchestrator.py
