Skip to content

Refresh FinOps hub upgrade procedure for multi-version FOCUS adoption #2123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flanakin wants to merge 6 commits into
base: flanakin/focus14
Choose a base branch
from
+27 −4
Open

Refresh FinOps hub upgrade procedure for multi-version FOCUS adoption #2123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2c6fa8f
Refresh FinOps hub upgrade procedure for multi-version FOCUS adoption…
flanakin May 6, 2026
063eaaf
Drop conformance regen from FOCUS upgrade procedure
flanakin May 6, 2026
c886d19
Address PR #2123 feedback: clarify preview-status rule
flanakin May 7, 2026
6053f28
Apply suggestions from code review
flanakin May 17, 2026
8ee2d63
chore: Update ms.date in docs-mslearn files
github-actions[bot] May 17, 2026
463c273
Fix typos and wording in FOCUS upgrade docs
flanakin Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions docs-mslearn/toolkit/hubs/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: FinOps hubs data model
description: Learn about the tables and functions available in FinOps hubs to build your own queries, reports, and dashboards.
author: flanakin
ms.author: micflan
ms.date: 04/01/2026
ms.date: 07/15/2026
ms.topic: reference
ms.service: finops
ms.subservice: finops-toolkit
Expand Down Expand Up @@ -52,15 +52,22 @@ Note the use of "Data Explorer" covers both Azure Data Explorer and Microsoft Fa

## Schema version

One of the goals of the FinOps hubs data model is to guarantee backwards compatibility. To support this, each FinOps hub release uses a specific schema version which aligns to a specific FOCUS version. The **schema version** defines the columns, data types, and allowed values in the tables and functions for each [managed dataset](#managed-datasets-in-finops-hubs).
One of the goals of the FinOps hubs data model is to guarantee backwards compatibility. To support this, each FinOps hub release uses a specific schema version which aligns to a specific FOCUS version. For instance, the `v1_4` schema version aligns with FOCUS 1.4 and the `v1_2` schema with FOCUS 1.2. The **schema version** defines the columns, data types, and allowed values in the tables and functions for each [managed dataset](#managed-datasets-in-finops-hubs).

Data is transformed to the latest supported FOCUS version during ingestion. For instance, if you ingested FOCUS 1.0 data into the `v1_4` schema, it would be converted to FOCUS 1.4 during ingestion. Older data remains in its originally ingested format. For instance, if you previously ingested FOCUS 1.0 data into the `v1_2` schema, it would remain in the `v1_2` format even after upgrading to a newer schema version.

The functions in the `Hub` database pull from all tables and transform them into a specific version. For instance, `Costs_v1_0` will convert `v1_4` and `v1_2` data back to the `v1_0` format, ensuring backwards compatibility despite upgrading to newer versions. When you're ready to upgrade, you can selectively upgrade each report or integration to use `Costs_v1_2` or `Costs_v1_4` without breaking others. However, if you want a quick, convenience function that always returns the latest version, you can use the unversioned functions, like `Costs` and `Prices`. Unversioned functions are recommended for ad hoc use while versioned functions are recommended for integration points that require a consistent format after upgrades.

The following table indicates the schema version for each FinOps hub release and which FOCUS version they align to.

| Release | Schema | FOCUS version |
| ------- | ------ | ------------- |
| 12+ | `v1_2` | 1.2 |
| 15+ | `v1_4` | 1.4 |

@RolandKrummenacher RolandKrummenacher Jun 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forward-dated content in a published Learn page: this adds a 15+ -> v1_4 -> 1.4 row (and v1_4/Costs_v1_4 examples on line 55) before 1.4 support has shipped. If docs-mslearn publishes on merge rather than gated to the 1.4 release, this page would publicly state 1.4 is supported ahead of release. Consider holding the v1_4 row/examples for a later phase, or confirm the publish cadence makes this safe.

| 12-14 | `v1_2` | 1.2 |
| 0.7-11 | `v1_0` | 1.0 |

Cost Management export availability for a given FOCUS version is separate from FinOps hub support for that version. FinOps hubs transforms older export formats to the supported schema version (forward or backward, depending on your FinOps hub release).

<br>

## Managed datasets in FinOps hubs
Expand Down
18 changes: 17 additions & 1 deletion src/templates/finops-hub/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,11 @@
- Each versioned function unions data from versioned tables in the Ingestion database and transforms it to that FOCUS version for back compat.
- Consumers should use the unversioned function for the latest and the versioned functions for back compat.

To add a new FOCUS versions:
To add a new FOCUS version:

0. Confirm dependencies
1. Ensure the FOCUS specification has been ratified for the target version. Support for working draft FOCUS versions should not be shipped before official ratification to prevent customer churn since FOCUS working drafts may change without notice.
2. Check whether Microsoft Cost Management has shipped a matching FOCUS export dataset version. The hub depends on a `focuscost_X.Y.json` schema mapping file in [Microsoft.CostManagement/Exports/schemas](../modules/Microsoft.CostManagement/Exports/schemas/) when ingesting from Cost Management. If the export is not yet available, the hub schema can still ship as GA. Note the gap in the changelog so adopters know what additional setup will be required.

@RolandKrummenacher RolandKrummenacher Jun 29, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR summary says step 0 should instruct shipping hub support as preview when the Cost Management export is not yet available, but this line says ship as GA (and data-model.md has no preview-convention text). Please reconcile the description with what shipped here. The body also lists "steps 5-8" but only 5-7 landed.

1. Add schema mapping file
1. Create new schema mapping file for the Cost Management export dataset version in the schemas folder
2. Add file to file upload list in [storage.bicep](../modules/storage.bicep)
Expand All @@ -41,3 +44,16 @@ To add a new FOCUS versions:
2. Update the KQL reports to use the new versioned functions
3. Update the ADX dashboard to use the new versioned functions
4. Update the FOCUS queries in the best practices library to use the new versioned functions
5. Update open-data metadata
1. Create a `FocusCost_<version>.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version.
2. Create a `FinOpsHubs_<dataset>_<schema-version>.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each FinOps hub managed dataset schema version.
3. Mirror the schema details (columns, types, descriptions) from the matching Cost Management export or FinOps hubs schema so downstream consumers see consistent metadata.
6. Update plugin skill files
1. Refresh the FOCUS schema and function references in the following files so plugin guidance does not go stale:
- [src/templates/agent-skills/finops-toolkit/references/finops-hubs.md](../../agent-skills/finops-toolkit/references/finops-hubs.md)
- [src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md](../../agent-skills/finops-toolkit/references/finops-hubs-deployment.md)
- [src/templates/agent-skills/azure-cost-management/references/azure-cost-exports.md](../../agent-skills/azure-cost-management/references/azure-cost-exports.md)
- [src/templates/claude-plugin/agents/ftk-database-query.md](../../claude-plugin/agents/ftk-database-query.md)
- [src/templates/claude-plugin/output-styles/ftk-output-style.md](../../claude-plugin/output-styles/ftk-output-style.md)
7. Update changelog
1. Add an entry under the next version in [docs-mslearn/toolkit/changelog.md](../../../../docs-mslearn/toolkit/changelog.md) describing the new FOCUS version support and any preview status.
Loading