Document how the schema's columns nest

[Roland Krummenacher (RolandKrummenacher)]

Fixes #2325.

🛠️ Changes

Adds a Column relationships section to the hub database guide, between Key enrichment columns and Example queries, plus its table-of-contents entries.

It covers three things the guide did not state:

• The organization chain — BillingAccountName → SubAccountName → x_ResourceGroupName → ResourceName, a strict tree where each level partitions the one above.
• The two service chains — the FOCUS one and the Azure meter one, side by side rather than as a single six-level path.
• Why they cannot be mixed — a meter category can appear under several service categories, so crossing the chains does not partition anything. A query is included so the reader can confirm it against their own data rather than taking it on faith.

It also notes that ServiceSubcategory and SkuMeter are FOCUS 1.2 columns, so on a hub whose exports predate 1.2 they are present but empty — an empty level meaning "not in this export" rather than "no spend".

✅ Verification

The claim that the service chains do not nest was checked on two unrelated hubs. On both, the query in the new section returns meter categories mapping to more than one service category, some to eight.

Markdown only — no queries or schema are changed, so there is nothing to regress.

📝 Notes

Related and filed separately, since they are different problems: the same guide's Costs() table reference has drifted from the deployed schema. I will open that one after this, to keep the two reviewable on their own.

🤖 Generated with Claude Code

[Roland Krummenacher (RolandKrummenacher)]

Correction to the framing above, after finding prior art I had missed.

src/templates/finops-hub-copilot-studio/knowledge/schema-reference.md already documents both chains — an Organization hierarchy table and a Service hierarchy section carrying the same point in one line: "FOCUS levels (first 3) don't align 1:1 with Azure meter levels (last 3)."

So this content is not new to the toolkit; it is absent from the database guide while living in a template knowledge file. That makes this PR a consolidation step rather than an addition, which is the more useful way to read it: the guide is the shared artifact that the plugins and agents build on, and the template file is a copy that has to be maintained separately.

Two things I would still argue for keeping from this PR over the template's wording:

1. The consequence, not just the fact. "Don't align 1:1" tells a reader the chains differ; it does not tell them that a meter category's total is therefore not a subset of any one service category, which is the part that produces wrong breakdowns.
2. A verification query, so the reader confirms it on their own data instead of trusting either document.

One correction to the template's text while it is in view, which I verified rather than assumed: it says ServiceSubcategory is "Currently blank in Microsoft data." That is version-dependent, not universal. Measured over the same 30-day window on two unrelated hubs, it is populated on every row on one and empty on every row on the other — consistent with it being a FOCUS 1.2 column, present but unfilled where the exports predate 1.2. The note added in this PR states it that way.

[Copilot]

🟡 Changes recommended

Three documentation accuracy issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Documents how organizational and service columns relate in the FinOps hub database guide.

Changes:

• Adds column relationship documentation and table-of-contents entries.
• Explains organization and parallel service hierarchies.
• Adds a validation query and guidance for empty legacy fields.

File summaries

File	Summary	Review findings
src/queries/finops-hub-database-guide.md	Adds the column relationships section and related TOC entries.	Three nit-level updates remain: correct the FOCUS version, filter empty classifications in the validation query, and qualify the resource-name hierarchy guidance.

Review details

Suppressed comments (2)

src/queries/finops-hub-database-guide.md:176

• The validation query includes empty classifications in the dcount. x_SkuMeterCategory is expected to be blank for some charges, and an empty ServiceCategory can also be a distinct string; a blank group can therefore satisfy ServiceCategories > 1 without proving a real category mapping. Filter both columns before summarize.

| where ChargePeriodStart >= startofmonth(ago(30d))
| summarize ServiceCategories = dcount(ServiceCategory) by x_SkuMeterCategory

src/queries/finops-hub-database-guide.md:155

• ResourceName and the other *Name fields are display values, not a strict key hierarchy: this guide later derives ResourceNameUnique with ResourceType, and the data dictionary notes that ResourceName can be empty for purchases. Grouping by this path can therefore merge distinct resources or collect non-resource charges in an empty child, so calling it a strict tree and saying drilling is always safe is misleading. Qualify this as the usual path for resource-backed charges and point readers to IDs or unique fields when identity matters.

A strict tree. Each level partitions the one above it, so drilling down in this order is safe:

BillingAccountName -> SubAccountName -> x_ResourceGroupName -> ResourceName

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Roland Krummenacher (RolandKrummenacher)]

Superseded by #2328 — same commit, moved to a branch in this repo for the same reason as #2327. The prior-art correction I posted below is folded into the new PR's description.

[microsoft-github-policy-service]

All Contributors (@all-contributors) please add Roland Krummenacher (@RolandKrummenacher) for code

[allcontributors]

@microsoft-github-policy-service[bot]

Roland Krummenacher (@RolandKrummenacher) already contributed before to code