docs(mdcode): codelab deploys to Spanner via a binding profile - #364
Merged
libei merged 10 commits intoAug 30, 2026
Conversation
Rework codelab section 5 and update the binding-profiles guide to reflect the Spanner Graph target (GoogleCloudPlatform#361) and binding profiles (GoogleCloudPlatform#358) together. Codelab: - Step 1 now names the deployment target with the first-class `deployment_target` key instead of a GOOGLE custom_extensions JSON string. - Section 5 replaces the `sed` target-swap with a real Spanner binding profile (`sales.profiles/operational.yaml`): different table names, remapped columns (including keys), and an unbound `net_amount` so `revenue` is withheld operationally. It shows `kcmd profiles`' availability report, the generated Spanner DDL, a live deploy, and a GQL query -- every output captured from a live ENTERPRISE Spanner run. Cleanup drops the Spanner database. profiles.md: - Scope note updated: Spanner graphs now deploy (was "non-BigQuery not yet supported"). - Spanner sources use bare table names, not `//spanner.../tables/X` resource URIs, which a Spanner graph cannot reference; added a note on the rule. - `--target` gains `spanner`; command examples deploy the operational (Spanner) profile.
Author the model as a logical model plus a named `analytical` binding profile from the start, instead of an inline single-file binding, so the profile feature is the default path a reader learns. Set it as `default_profile` so steps 3-4 keep using a bare `kcmd push`; section 5 then adds the `operational` Spanner profile as a second binding rather than introducing the concept. Add a "simple case" callout showing the single-file inline binding (the `default` profile) for models that only ever bind to one store. Update the section-5 `kcmd profiles` output to show both profiles side by side (analytical withholds nothing; operational withholds revenue). Verified live: `kcmd profiles`, and `kcmd push --target kc|bq --validate-only` off the split layout produce the documented output.
Reorder the codelab to match how a semantic model is actually adopted, now that a logical-only model can be pushed to Knowledge Catalog (GoogleCloudPlatform#367): 1. Author the logical model (no source, no column, no target) 2. Govern it in Knowledge Catalog -- pure logical, needs no tables or data 3. Deploy to BigQuery -- add the analytical binding, hydrate, query 4. Deploy the same model to Spanner -- add the operational binding The Knowledge Catalog push moves ahead of hydration and binding: it governs meaning, so it needs neither. The analytical binding authoring and the table hydration fold into the BigQuery step, where they are actually required. The "why tables come first" note is rescoped to the BigQuery push, which does validate source tables, unlike the KC push. Deploy prose drops "...Graph" (deploy to BigQuery / to Spanner); the graph names stay in the generated DDL, command output, and feature references. The Spanner leg now states explicitly that Knowledge Catalog is not re-pushed -- a binding profile changes nothing logical.
libei
force-pushed
the
docs/codelab-profiles-spanner
branch
from
August 30, 2026 05:18
bc39cdd to
00b0501
Compare
Verified the codelab end to end against live instances (Knowledge Catalog on autopush, BigQuery, and an ENTERPRISE Spanner instance) and reconciled it with what the commands actually print. - Author the model and both binding profiles under `entities:` rather than `datasets:`, matching the prose, which calls them entities throughout. The two keys are aliases; the OWL-import output still shows `datasets:` (the original spelling) and a note points that out. - Step 2's Knowledge Catalog plan now shows the real output: the `Validating...` framing, the two relationship-name-normalization warnings (with a note that they are expected and repeat on every KC push), and the completion footer. - Step 3's BigQuery DDL block shows the `Pushing...` line, the `-- BigQuery Graph --` banner, and the deployment-target comment it was missing, matching the Spanner block in step 4 and the real console output. Depends on the logical-only KC emitter fix (source.resources) so step 2's govern-before-you-bind push succeeds against the live server.
Collaborator
Author
Update: verified live,
|
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.
Reworks the semantic-model codelab and binding-profiles guide to show the Spanner Graph target (#361) and binding profiles (#358) working together.
Codelab (
docs/semantic-model/codelab.md)deployment_target:key instead of aGOOGLE custom_extensionsJSON string.seddeployment-target swap with a real binding profile (sales.profiles/operational.yaml): a Spanner store with different table names, remapped columns (including keys), and an unboundnet_amountsorevenueis withheld operationally. It showskcmd profiles' availability report, the generated Spanner DDL, a live deploy, and a GQL query.Every command output in section 5 was captured from a live run against an ENTERPRISE Spanner instance.
Binding profiles (
docs/semantic-model/profiles.md)//spanner.../tables/Xresource URIs (which a Spanner graph cannot reference); added a note on the rule in "Sources are URIs".--targetdocumented asbq|spanner|kc|all; command examples deploy the operational (Spanner) profile.Why now
The codelab previously swapped backends with
sed, which is exactly the manual step binding profiles remove. This makes the codelab demonstrate the feature as intended: one logical model, an analytical (BigQuery) binding and an operational (Spanner) binding, switched with--profile.