docs(semantic-model): audit the deploy guide for binding profiles + Spanner Graph - #365
Draft
libei wants to merge 12 commits into
Draft
docs(semantic-model): audit the deploy guide for binding profiles + Spanner Graph#365libei wants to merge 12 commits into
libei wants to merge 12 commits into
Conversation
libei
force-pushed
the
worktree-user-guide-update
branch
from
August 30, 2026 03:58
33aaa00 to
f5404e8
Compare
libei
changed the title
libei
force-pushed
the
worktree-user-guide-update
branch
from
August 30, 2026 04:34
1a36de2 to
295b3fa
Compare
…link profiles guide
…only Binding-profile guide predated Spanner push (GoogleCloudPlatform#361): its scope note and example said only a BigQuery-bound profile deploys. A profile now routes to whichever backend its deployment target names, so the operational (Spanner) profile deploys too. Update the scope note, the source-URI explanation (final-segment reduction now works for a spanner:// source), the example prose, the CLI comment, and the availability/validation notes (the live source probe is BigQuery-only).
… doc's own metric example
…rget - Scope: drop the non-existent 'non-graph store merged-but-not-deployed' path; deployment target must name BigQuery Graph or Spanner Graph. - Command line: add --target spanner; the graph backend is fixed by the profile's deployment_target, so --target is not a free redirect. - Notes: expressions are GoogleSQL emitted as written (--transpile converts vendor SQL), not lowered per-store by a runtime engine.
Reorder into a three-part arc: a short concept intro (mental model folded in), the concrete two-binding walkthrough early, the two rules (contract + availability), then reference (command line, source URIs, merge rules, validation, details). Collapse the 'profile = physical binding' idea from four restatements to one, fold 'How it works' and 'File layout' into the intro and walkthrough, and move the unbound-vs-null / explicit-unbound nuance into a Details reference section.
Keep the product names at a high level in narrative prose (BigQuery, Spanner) rather than BigQuery Graph / Spanner Graph. The fuller feature names stay in the walkthrough/example sections, code comments, program output, and the codelab, where a concrete example names the concrete feature.
The intro and the 'different backends' bullet cited a 'revenue' metric the doc never defines; use order_count, which the walkthrough model declares and which both bindings can answer.
…rm#367/GoogleCloudPlatform#368) A --target kc push now accepts a purely logical model (no bindings, no deployment target) and publishes it to Knowledge Catalog. Update the guide: - README: deployment target and sources are required only for a graph leg; a --target kc push governs the logical model and needs neither. - reference: the deployment-target and live-source checks are graph-scoped; the KC leg accepts a logical-only model (an omitted source publishes with no linked resource; an unbound: placeholder is written verbatim). - owl-import: an imported model can be published to Knowledge Catalog as-is; binding is required only to deploy a graph.
The codelab and profiles guide already author with the first-class `deployment_target:` key and the `entities:` alias (loader sugars from GoogleCloudPlatform#361). Bring the README authoring walkthrough and the reference class-hierarchy example onto the same readable form, and note that the equivalent GOOGLE custom_extensions deploymentTargets block still works.
libei
force-pushed
the
worktree-user-guide-update
branch
from
August 30, 2026 06:52
2894a3a to
7872ede
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Holistic audit + revision of the non-codelab semantic-model user guide against
the semantic-model / Spanner-deploy PRs merged today (#357/#358 binding
profiles, #361 Spanner Graph target, #363 physical-column KEYs, #366 source-URI
reduction). Docs only. Rebased onto
main(includes #366), so every claimis backed by landed code.
README / reference.md
--profile; correct--target(an explicit
--target spanner/bqwith no matching model is a hard error,not a quiet no-op); state the Spanner-native resource-name
sourceissupported, not "planned."
profiles.md — reconciled with Spanner deployment
deployed" path that has no implementation. A deployment target must name a
BigQuery Graph or Spanner Graph URI (
validate.ts:38-53); those are the twograph backends.
--target spanner; corrected the orthogonalityframing — the graph backend is fixed by the profile's
deployment_target, so--target bqon a Spanner-bound profile is an error, not a redirect; only--target kcis universal.sourceURI resolves per backend(BigQuery keeps the full path; Spanner reduces to the bare table name);
replaced the aspirational "engine lowers each expression at runtime" with what
actually happens (GoogleSQL emitted as written;
--transpileconverts vendorSQL at push).
consolidated the follow-on prose and fixed an off-example metric to the doc's
own
AVG(Customer.lifetimeValue).Verification
Claim-by-claim audit against the code (commands.ts, loader.ts, validate.ts,
resolve_profiles.ts, spanner.ts, bigquery.ts). Everything else in the guide
verified CONFIRMED. Spanner unit tests 17/17 on the rebased branch.