Update semantic bridge docs for 3.26.2 by greggyb · Pull Request #357 · TabularEditor/TabularEditorDocs

greggyb · 2026-07-03T10:31:34Z

update dlls and xmldocs for 3.26.2 release
Add Fields-Dimensions clarification doc
- Regarding Databricks's new standard usage of the keyword fields in metric view yaml.
semantic bridge: update sample metric view
- Use v1.1 and more new supported features for translation
- Remove deserialization include, and switch to a tabbed interface to allow a user to download and load or copy and deserialize.
- Shift to a single source of truth for the sample YAML in sample-metricview.yaml, which is transitively included through sample-metricview.md
Remove auto-generated _site/staticwebapp.config.json from git
- This file is automatically generated and only creates noise by being checked in.
Update metric view object model doc
- Include v1.1 properties and translation notes.
Semantic Bridge: split up object model, core, and translation
semantic-bridge.md: now a generic feature intro.
semantic-bridge-metric-view-object-model.md: covers the object model only, but not validation or translation notes
semantic-bridge-metric-view-tabular-translation.md: new, specifically covers all translation details
Semantic bridge: update validation docs
Include back-reference doc in object model.
Update validation to use a new example for a contextual rule (old duplicate name is now invalid)
Update toc
Final prose and naming pass for features/semantic-bridge*
General clean up
rename semantic-bridge-fields-and-dimensions to semantic-bridge-metric-view-fields-and-dimensions (file and uid)
add additional references to feature docs
update toc
Update how-to docs for semantic bridge: prose and source only
Doc cleanup pass for semantic bridge
- Check all docs against source and databricks
Update code block outputs
- Add annotations for WIP code runner, update all output blocks.
Update semantic bridge screenshots

Regarding Databricks's new standard usage of the keyword `fields` in metric view yaml.

Use v1.1 and more new supported features for translation Remove deserialization include, and switch to a tabbed interface to allow a user to download and load or copy and deserialize. Shift to a single source of truth for the sample YAML in sample-metricview.yaml, which is transitively included through sample-metricview.md

This file is automatically generated and only creates noise by being checked in.

Include v1.1 properties and translation notes.

- semantic-bridge.md: now a generic feature intro. - semantic-bridge-metric-view-object-model.md: covers the object model only, but not validation or translation notes - semantic-bridge-metric-view-tabular-translation.md: new, specifically covers all translation details

- Include back-reference doc in object model. - Update validation to use a new example for a contextual rule (old duplicate name is now invalid) - Update toc

- General clean up - rename semantic-bridge-fields-and-dimensions to semantic-bridge-metric-view-fields-and-dimensions (file and uid) - add additional references to feature docs - update toc

Still need to update script outputs

Check all docs against source and databricks

Add annotations for WIP code runner, update all output blocks.

Copilot

Pull request overview

Updates the Tabular Editor documentation set to reflect the Semantic Bridge changes in the 3.26.2 release, including Metric View v1.1 support, the dimensions→fields terminology shift, and expanded guidance on import/validation/translation.

Changes:

Refresh Semantic Bridge feature + how-to documentation to v1.1 examples and updated diagnostics/outputs.
Add new focused docs (translation details, fields vs dimensions clarification, failure handling, import-from-file).
Clean up navigation and generated artifacts (TOCs, roadmap, remove generated _site/staticwebapp.config.json), plus update API XML sources and doc filtering.

Reviewed changes

Copilot reviewed 25 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
content/references/roadmap.md	Updates roadmap items to reflect current Semantic Bridge enhancements and v1.1 support.
content/how-tos/toc.md	Adds new Semantic Bridge how-to entries to the how-to TOC.
content/how-tos/semantic-bridge-validate-simple-rules.md	Updates validation examples to `Field` terminology and v1.1-aware rules.
content/how-tos/semantic-bridge-validate-default.md	Refreshes default validation guidance, samples, and outputs for 3.26.2+.
content/how-tos/semantic-bridge-validate-contextual-rules.md	Updates contextual rule examples to field/join name collision scenarios and new diagnostics structure.
content/how-tos/semantic-bridge-serialize.md	Updates serialization guidance and examples for v1.1 YAML and round-tripping.
content/how-tos/semantic-bridge-rename-objects.md	Reworks rename example to a field-focused workflow using the updated object model.
content/how-tos/semantic-bridge-remove-object.md	Updates removal examples for fields/measures and aligns with new sample include.
content/how-tos/semantic-bridge-metric-view-import-from-file.md	New how-to for importing a Metric View directly from a YAML file.
content/how-tos/semantic-bridge-metric-view-handle-failures.md	New troubleshooting how-to for common failure modes and guard patterns.
content/how-tos/semantic-bridge-load-inspect.md	Updates inspection examples and outputs to v1.1 and `Fields`.
content/how-tos/semantic-bridge-import.md	Updates import workflow, diagnostics reporting, and adds translation-warning example.
content/how-tos/semantic-bridge-how-tos.md	Refreshes Semantic Bridge how-to index and adds troubleshooting section.
content/how-tos/semantic-bridge-add-object.md	Updates add-object patterns for field/join/measure and v1.1 constructs.
content/how-tos/includes/sample-metricview.yaml	Updates the shared sample YAML to v1.1 features (fields, cardinality, formats, display_name).
content/how-tos/includes/sample-metricview.md	Replaces inline YAML with a “download or copy” tabbed include and single-source YAML include.
content/how-tos/includes/sample-metricview-deserialize.md	Removes the older deserialize-only include in favor of the new unified sample include.
content/features/toc.md	Updates feature TOC entries for the split Semantic Bridge documentation set.
content/features/semantic-bridge.md	Updates Semantic Bridge overview, diagnostics snippet, and reorganizes links to new pages.
content/features/semantic-bridge-metric-view-validation.md	Updates validation docs to `Field` terminology and new helper/diagnostic patterns.
content/features/semantic-bridge-metric-view-tabular-translation.md	New detailed translation/limitations page for Metric View → Tabular.
content/features/semantic-bridge-metric-view-object-model.md	Updates object model docs for v1.1 and new `Fields`/API surface.
content/features/semantic-bridge-metric-view-fields-and-dimensions.md	New clarification page documenting `dimensions` vs `fields` and `Dimension`→`Field` API migration.
content/_apiSource/TOMWrapper.xml	Updates API XML surface (new members, renames, stub types) for generated reference docs.
content/_apiSource/TabularEditor3.Shared.xml	Updates shared API XML documentation for new contracts/services/resources.
configuration/filterConfig.yml	Excludes generated Databricks SQL parser namespace from published API docs.
_site/staticwebapp.config.json	Removes an auto-generated build artifact from source control.

Files not reviewed (2)

content/_apiSource/TOMWrapper.xml: Generated file
content/_apiSource/TabularEditor3.Shared.xml: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2026-07-03T10:36:19Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-357.westeurope.azurestaticapps.net

jeroenterheerdt

in general, I'd recommend running this through an AI to make it simpler. These are docs, not prose. It reads like a book sometimes, and I think it can be shorter. AI can be helpful in tightening things up and making it more factual and less "flowerly".

greggyb · 2026-07-07T10:32:38Z

in general, I'd recommend running this through an AI to make it simpler. These are docs, not prose. It reads like a book sometimes, and I think it can be shorter. AI can be helpful in tightening things up and making it more factual and less "flowerly".

@jeroenterheerdt, could you point out specific sections for this? How-tos are intended to be to-the-point and copy+pastable examples. The feature docs are intended to give a thorough background about the feature and user-facing design.

I do not let AI write for me.

All semantic bridge docs have standardized to talk about "Metric View" spec or "Metric View" docs, rather than "Databricks", to avoid confusion when we then link to learn.microsoft.com docs. All learn.microsoft.com links have had the culture (/en-us/...) stripped out, so that these don't default to english, just because I do. Confirm no 'learn.microsoft.com/en-us/' in semantic bridge: ```shell # empty result means no culture portion rg -ni -g 'content/**/semantic-bri*md' 'learn\.microsoft\.com/[a-z]{2,3}-[a-z]{2,4}/' # empty result means no lines saying databricks doc rg -ni -g 'content/**/semantic-bri*md' 'databricks.*doc' # empty result means no lines saying databricks spec; one false positive rg -ni -g 'content/**/semantic-bri*md' 'databricks.*spec' ```

greggyb · 2026-07-07T11:24:29Z

Latest commit addresses all "databricks spec" and "databricks doc" lines, all learn.microsoft links.

github-actions · 2026-07-07T11:27:45Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-357.westeurope.azurestaticapps.net

jeroenterheerdt · 2026-07-07T12:36:08Z

I do not let AI write for me.

I didn't say you did, nor did I mean to imply that :) It read very much like a @greggyb doc :).
However, maybe have it reviewed and tightened by AI could be a good idea.

An example of where I think things could be tighter is here: https://delightful-mud-081affe03-357.westeurope.azurestaticapps.net/en/features/semantic-bridge-metric-view-fields-and-dimensions.html#serialization-and-deserialization. It's not the how-to's actually, it's the normal docs.

* Add GitHub Flow and Octopus Merge pattern article Introduces github-flow.md, a companion to the parallel development guide covering day-to-day GitHub Flow usage and a reference CI/CD pipeline implementing the Octopus Merge pattern for keeping a shared test environment in sync with all open pull requests. Cross-links between the two articles, fixes broken/placeholder links in parallel-development.md, and adds Mermaid diagrams for the branching model, merge flow, job dependencies, and end-to-end workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Fix CI build failure from unresolved BPA/AS CI-CD cross references DocFX only raises UidNotFound for the explicit [text](xref:uid) link form, not the @uid shorthand — and content/todo/{powerbi-cicd,as-cicd} aren't part of the published build, so those two xrefs never resolve. The explicit form used here (unlike the shorthand already used elsewhere for the same pages) triggered the warning, and the build script treats any DocFX warning in the English build as fatal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Just Blindbæk <just@justB.dk> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: Daniel Otykier <otykier@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* build-docs.py: add iterative development conveniences * add standalone dead link checker * Add csharp_doctest tooling and fixtures * parallelize csharp_doctest.py * fix exception handling in csharp_doctest.py * streamline and filter last script output for csharp build scripts * Document the build scripts for validation * Boost parallelism and drop github parallel requests * check_links.py: harden and add C-t, C-c, C-\ handling - Error handling for workers so they can't hang - siginfo, sigquit, sigbreak (C-t, C-\, and C-break) give a status update while running - sigint (C-c) prints stats and exits cleanly * Update reporting for urls and stats * Update README for check_links reporting * Update README with usage and contribution notes * use `python3` in shebang Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * clarify README and comments about stdour/stderr * check_links.py: do not hard-code docs site; use shared config config_loader.py already parses shared config and provides the live site URL. Update check_links.py to import and use config_loader. This requires moving from global shared state to a URL base that gets passed around to appropriate functions. It also changes the dispatch pattern, because command functions have different signatures now. Additionally, update config_loader.py to conform to the `mypy --strict` used in check_links.py.

* Integrate 3.26.3 release notes and update download links * Update 3_26_3.md * Update 3_26_3.md

* New translations table-groups.md (Spanish) [ci skip] * New translations tom-explorer-view.md (Spanish) [ci skip] * New translations downloads.md (Spanish) [ci skip] * New translations release-history.md (Spanish) [ci skip] * New translations whats-new.md (Spanish) [ci skip] * New translations udfs.md (Spanish) [ci skip] * New translations ai-assistant.md (Spanish) [ci skip] * New translations 3_26_2.md (Spanish) [ci skip] * New translations table-groups.md (Chinese Simplified) [ci skip] * New translations tom-explorer-view.md (Chinese Simplified) [ci skip] * New translations refresh-preview-query.md (Chinese Simplified) [ci skip] * New translations downloads.md (Chinese Simplified) [ci skip] * New translations release-history.md (Chinese Simplified) [ci skip] * New translations whats-new.md (Chinese Simplified) [ci skip] * New translations udfs.md (Chinese Simplified) [ci skip] * New translations ai-assistant.md (Chinese Simplified) [ci skip] * New translations 3_26_2.md (Chinese Simplified) [ci skip] * New translations 3_26_2.md (Spanish) [ci skip] * New translations 3_26_2.md (Chinese Simplified) [ci skip] * New translations 3_26_2.md (Spanish) [ci skip] * New translations 3_26_2.md (Chinese Simplified) [ci skip] * New translations te-cli-commands.md (Spanish) [ci skip] * New translations te-cli-config.md (Spanish) [ci skip] * New translations te-cli-limitations.md (Spanish) [ci skip] * New translations te-cli-preview-notice.md (Spanish) [ci skip] * New translations te-cli-automation.md (Spanish) [ci skip] * New translations te-cli-cicd.md (Spanish) [ci skip] * New translations te-cli-install.md (Spanish) [ci skip] * New translations te-cli-interactive.md (Spanish) [ci skip] * New translations te-cli-migrate.md (Spanish) [ci skip] * New translations te-cli.md (Spanish) [ci skip] * New translations te-cli-commands.md (Chinese Simplified) [ci skip] * New translations te-cli-config.md (Chinese Simplified) [ci skip] * New translations te-cli-limitations.md (Chinese Simplified) [ci skip] * New translations te-cli-preview-notice.md (Chinese Simplified) [ci skip] * New translations te-cli-automation.md (Chinese Simplified) [ci skip] * New translations te-cli-cicd.md (Chinese Simplified) [ci skip] * New translations te-cli-install.md (Chinese Simplified) [ci skip] * New translations te-cli-interactive.md (Chinese Simplified) [ci skip] * New translations te-cli-migrate.md (Chinese Simplified) [ci skip] * New translations te-cli.md (Chinese Simplified) [ci skip] * New translations te-cli-commands.md (Spanish) [ci skip] * New translations te-cli-config.md (Spanish) [ci skip] * New translations te-cli-interactive.md (Spanish) [ci skip] * New translations te-cli.md (Spanish) [ci skip] * New translations te-cli-commands.md (Chinese Simplified) [ci skip] * New translations te-cli-config.md (Chinese Simplified) [ci skip] * New translations te-cli-interactive.md (Chinese Simplified) [ci skip] * New translations te-cli.md (Chinese Simplified) [ci skip] * New translations parallel-development.md (Spanish) [ci skip] * New translations github-flow.md (Spanish) [ci skip] * New translations parallel-development.md (Chinese Simplified) [ci skip] * New translations github-flow.md (Chinese Simplified) [ci skip] * New translations downloads.md (Spanish) [ci skip] * New translations release-history.md (Spanish) [ci skip] * New translations 3_26_3.md (Spanish) [ci skip] * New translations downloads.md (Chinese Simplified) [ci skip] * New translations release-history.md (Chinese Simplified) [ci skip] * New translations 3_26_3.md (Chinese Simplified) [ci skip] * New translations te-cli-commands.md (Chinese Simplified) [ci skip] * New translations te-cli-config.md (Chinese Simplified) [ci skip] * New translations te-cli-limitations.md (Chinese Simplified) [ci skip] * New translations te-cli-automation.md (Chinese Simplified) [ci skip] * New translations te-cli-cicd.md (Chinese Simplified) [ci skip] * New translations te-cli-install.md (Chinese Simplified) [ci skip] * New translations te-cli-interactive.md (Chinese Simplified) [ci skip] * New translations te-cli-migrate.md (Chinese Simplified) [ci skip] * New translations te-cli.md (Chinese Simplified) [ci skip] * New translations parallel-development.md (Chinese Simplified) [ci skip] * New translations github-flow.md (Chinese Simplified) [ci skip] * New translations downloads.md (Chinese Simplified) [ci skip] * New translations release-history.md (Chinese Simplified) [ci skip] * New translations 3_26_3.md (Chinese Simplified) [ci skip] * New translations te-cli-commands.md (Spanish) [ci skip] * New translations te-cli-config.md (Spanish) [ci skip] * New translations te-cli-limitations.md (Spanish) [ci skip] * New translations te-cli-automation.md (Spanish) [ci skip] * New translations te-cli-cicd.md (Spanish) [ci skip] * New translations te-cli-install.md (Spanish) [ci skip] * New translations te-cli-interactive.md (Spanish) [ci skip] * New translations te-cli-migrate.md (Spanish) [ci skip] * New translations te-cli.md (Spanish) [ci skip] * New translations parallel-development.md (Spanish) [ci skip] * New translations github-flow.md (Spanish) [ci skip] * New translations downloads.md (Spanish) [ci skip] * New translations release-history.md (Spanish) [ci skip] * New translations 3_26_3.md (Spanish) [ci skip]

Introduce a table to cover all cases of versions and `fields` and `dimensions` keys.

greggyb · 2026-07-15T14:25:04Z

I do not let AI write for me.

I didn't say you did, nor did I mean to imply that :) It read very much like a @greggyb doc :). However, maybe have it reviewed and tightened by AI could be a good idea.

An example of where I think things could be tighter is here: https://delightful-mud-081affe03-357.westeurope.azurestaticapps.net/en/features/semantic-bridge-metric-view-fields-and-dimensions.html#serialization-and-deserialization. It's not the how-to's actually, it's the normal docs.

I updated this one with a summary table for the serialization section.

github-actions · 2026-07-15T14:28:39Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://delightful-mud-081affe03-357.westeurope.azurestaticapps.net

greggyb added 12 commits July 3, 2026 12:22

update dlls and xmldocs for 3.26.2 release

950b014

Add Fields-Dimensions clarification doc

038c532

Regarding Databricks's new standard usage of the keyword `fields` in metric view yaml.

Remove auto-generated _site/staticwebapp.config.json from git

31ca62a

This file is automatically generated and only creates noise by being checked in.

Update metric view object model doc

7e4c908

Include v1.1 properties and translation notes.

Semantic bridge: update validation docs

0f863c3

- Include back-reference doc in object model. - Update validation to use a new example for a contextual rule (old duplicate name is now invalid) - Update toc

Final prose and naming pass for features/semantic-bridge*

8e23833

- General clean up - rename semantic-bridge-fields-and-dimensions to semantic-bridge-metric-view-fields-and-dimensions (file and uid) - add additional references to feature docs - update toc

Update how-to docs for semantic bridge: prose and source only

890e1a4

Still need to update script outputs

Doc cleanup pass for semantic bridge

c3ab75a

Check all docs against source and databricks

Update code block outputs

765afe3

Add annotations for WIP code runner, update all output blocks.

Update semantic bridge screenshots

4dbc566

greggyb requested a review from Copilot July 3, 2026 10:32

Copilot started reviewing on behalf of greggyb July 3, 2026 10:32 View session

Copilot AI reviewed Jul 3, 2026

View reviewed changes

Comment thread content/how-tos/semantic-bridge-import.md

jeroenterheerdt requested changes Jul 7, 2026

View reviewed changes

justBlindbaek and others added 6 commits July 14, 2026 15:08

Integrate 3.26.3 release notes and update download links (#362)

37d45ae

* Integrate 3.26.3 release notes and update download links * Update 3_26_3.md * Update 3_26_3.md

Simplify dimensions and fields serialization prose

0f7313f

Introduce a table to cover all cases of versions and `fields` and `dimensions` keys.

update xml docs source

aea7009

Uh oh!

Conversation

greggyb commented Jul 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

github-actions Bot commented Jul 3, 2026

Uh oh!

jeroenterheerdt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greggyb commented Jul 7, 2026

Uh oh!

greggyb commented Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

jeroenterheerdt commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greggyb commented Jul 15, 2026

Uh oh!

github-actions Bot commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jeroenterheerdt commented Jul 7, 2026 •

edited

Loading