From 2c6fa8fdd794785d584fb37d2df2521f808d9720 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Wed, 6 May 2026 02:41:06 -0700 Subject: [PATCH 01/11] Refresh FinOps hub upgrade procedure for multi-version FOCUS adoption (#2121) Update the canonical "add a new FOCUS version" procedure to reflect the six additional steps surfaced during FOCUS 1.4 scoping (Cost Management dependency check, open-data metadata, conformance regen, plugin updates, changelog) and add guidance for handling two FOCUS versions in one cycle (GA + preview). Clarify the hub-schema-to-FOCUS-version relationship and preview convention in data-model.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs-mslearn/toolkit/hubs/data-model.md | 6 ++++- src/templates/finops-hub/docs/README.md | 30 ++++++++++++++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index e06a19519..60f3e02c7 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 05/06/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit @@ -54,6 +54,8 @@ Note the use of "Data Explorer" covers both Azure Data Explorer and Microsoft Fa 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). +The hub schema version mirrors the FOCUS specification version it natively ingests. For example, `v1_2` ingests FOCUS 1.2 exports without transformation. Older data ingested under prior schema versions is automatically up-converted by the unversioned functions (`Costs()`, `Prices()`, etc.) so consumers always see the latest schema regardless of when the data was ingested. + The following table indicates the schema version for each FinOps hub release and which FOCUS version they align to. | Release | Schema | FOCUS version | @@ -61,6 +63,8 @@ The following table indicates the schema version for each FinOps hub release and | 12+ | `v1_2` | 1.2 | | 0.7-11 | `v1_0` | 1.0 | +When hub support ships ahead of a FOCUS specification ratifying or ahead of Cost Management exporting a version, the hub schema is labeled **preview**. Preview schemas may change without notice between releases. The unversioned functions remain pinned to the latest GA schema until the preview promotes to GA, ensuring production reports stay stable while early adopters validate the new version. +
## Managed datasets in FinOps hubs diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index 2cff88bf9..1c46a8ca4 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -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. Verify 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/). + 2. If the Cost Management export is not yet available, ship hub support as **preview** and call out the upstream dependency in the changelog and the [data model documentation](../../../../docs-mslearn/toolkit/hubs/data-model.md). 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) @@ -41,3 +44,28 @@ 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. Drop a new `FocusCost_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/). + 2. Mirror the schema details (columns, types, descriptions) from the matching Cost Management export schema so downstream consumers see consistent metadata. +6. Regenerate conformance reports + 1. Run `pwsh src/scripts/Build-FocusConformance.ps1 -Branch ` to refresh [docs-mslearn/focus/conformance-full-report.md](../../../../docs-mslearn/focus/conformance-full-report.md) and [conformance-summary.md](../../../../docs-mslearn/focus/conformance-summary.md). +7. 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) +8. 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. + +### Handling multiple FOCUS versions in one cycle + +Occasionally, the toolkit needs to support two FOCUS versions in a single release – for example, a newly ratified version alongside a working draft of the next version. When that happens: + +- The older version follows the standard `_v1_X` naming and ships as generally available (GA). +- The newer version uses the next `_v1_Y` suffix and is labeled **preview** in user-facing documentation, including [data-model.md](../../../../docs-mslearn/toolkit/hubs/data-model.md) and [changelog.md](../../../../docs-mslearn/toolkit/changelog.md). +- Preview schemas may change without notice between releases. Treat them as opt-in for early adopters only. +- The unversioned functions (`Costs()`, `Prices()`, etc.) alias to the latest **GA** schema, not the preview. The aliases promote to the newer version only after it transitions from preview to GA. + +This guarantees backwards compatibility for production consumers while still enabling early validation of the next FOCUS version. From 063eaaf0175cfeacdebf0096b2fcf57a79759118 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Wed, 6 May 2026 03:17:00 -0700 Subject: [PATCH 02/11] Drop conformance regen from FOCUS upgrade procedure Conformance reports are generated only against official Microsoft Cost Management FOCUS releases, not as part of adding a new FOCUS version to FinOps hubs. Removing the step keeps the procedure scoped to the hub-specific workstream. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/templates/finops-hub/docs/README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index 1c46a8ca4..4129901b8 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -47,16 +47,14 @@ To add a new FOCUS version: 5. Update open-data metadata 1. Drop a new `FocusCost_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/). 2. Mirror the schema details (columns, types, descriptions) from the matching Cost Management export schema so downstream consumers see consistent metadata. -6. Regenerate conformance reports - 1. Run `pwsh src/scripts/Build-FocusConformance.ps1 -Branch ` to refresh [docs-mslearn/focus/conformance-full-report.md](../../../../docs-mslearn/focus/conformance-full-report.md) and [conformance-summary.md](../../../../docs-mslearn/focus/conformance-summary.md). -7. Update plugin skill files +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) -8. Update changelog +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. ### Handling multiple FOCUS versions in one cycle From c886d193177151764d681946104c206546486a17 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Thu, 7 May 2026 03:40:50 -0700 Subject: [PATCH 03/11] Address PR #2123 feedback: clarify preview-status rule - Reword data-model.md:66 grammar (per Copilot). - Decouple hub preview status from Cost Management export availability. Preview now means the FOCUS spec is still working draft. Cost Management lag is a separate operational concern that does not gate hub GA. - Update README step 0 to match. Co-Authored-By: copilot-pull-request-reviewer Co-Authored-By: Claude Opus 4.7 (1M context) --- docs-mslearn/toolkit/hubs/data-model.md | 6 ++++-- src/templates/finops-hub/docs/README.md | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 60f3e02c7..7ad45c674 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 05/06/2026 +ms.date: 05/07/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit @@ -63,7 +63,9 @@ The following table indicates the schema version for each FinOps hub release and | 12+ | `v1_2` | 1.2 | | 0.7-11 | `v1_0` | 1.0 | -When hub support ships ahead of a FOCUS specification ratifying or ahead of Cost Management exporting a version, the hub schema is labeled **preview**. Preview schemas may change without notice between releases. The unversioned functions remain pinned to the latest GA schema until the preview promotes to GA, ensuring production reports stay stable while early adopters validate the new version. +When hub support ships ahead of FOCUS specification ratification, the hub schema is labeled **preview**. Preview schemas may change without notice between releases because the underlying spec is still working draft. The unversioned functions remain pinned to the latest GA schema until the preview promotes to GA, ensuring production reports stay stable while early adopters validate the new version. + +Cost Management export availability for a given FOCUS version is a separate concern. A hub schema can be GA even if Cost Management has not yet shipped a matching export; in that case, the hub is ready to ingest the new format as soon as the export ships. This is documented in the [hub upgrade procedure](https://github.com/microsoft/finops-toolkit/tree/dev/src/templates/finops-hub/docs/README.md) so adopters know which scenarios require additional setup once an export is available.
diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index 4129901b8..a084adff2 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -20,8 +20,8 @@ To add a new FOCUS version: 0. Confirm dependencies - 1. Verify 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/). - 2. If the Cost Management export is not yet available, ship hub support as **preview** and call out the upstream dependency in the changelog and the [data model documentation](../../../../docs-mslearn/toolkit/hubs/data-model.md). + 1. Mark the hub schema as **preview** if the FOCUS specification is still working draft (not yet ratified). Preview schemas may change without notice between releases. + 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 — the hub will ingest the new format as soon as the export ships. Note the gap in the changelog so adopters know what additional setup will be required. 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) From 6053f2849045ac13bce58d3039a6fa6471803fc3 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Sun, 17 May 2026 13:16:22 -0700 Subject: [PATCH 04/11] Apply suggestions from code review --- docs-mslearn/toolkit/hubs/data-model.md | 13 +++++++------ src/templates/finops-hub/docs/README.md | 20 +++++--------------- 2 files changed, 12 insertions(+), 21 deletions(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 7ad45c674..62e0590eb 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -52,20 +52,21 @@ 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). -The hub schema version mirrors the FOCUS specification version it natively ingests. For example, `v1_2` ingests FOCUS 1.2 exports without transformation. Older data ingested under prior schema versions is automatically up-converted by the unversioned functions (`Costs()`, `Prices()`, etc.) so consumers always see the latest schema regardless of when the data was ingested. +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 it 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 | +| 12-14 | `v1_2` | 1.2 | | 0.7-11 | `v1_0` | 1.0 | -When hub support ships ahead of FOCUS specification ratification, the hub schema is labeled **preview**. Preview schemas may change without notice between releases because the underlying spec is still working draft. The unversioned functions remain pinned to the latest GA schema until the preview promotes to GA, ensuring production reports stay stable while early adopters validate the new version. - -Cost Management export availability for a given FOCUS version is a separate concern. A hub schema can be GA even if Cost Management has not yet shipped a matching export; in that case, the hub is ready to ingest the new format as soon as the export ships. This is documented in the [hub upgrade procedure](https://github.com/microsoft/finops-toolkit/tree/dev/src/templates/finops-hub/docs/README.md) so adopters know which scenarios require additional setup once an export is available. +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).
diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index a084adff2..4a12b9d1c 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -20,8 +20,8 @@ To add a new FOCUS version: 0. Confirm dependencies - 1. Mark the hub schema as **preview** if the FOCUS specification is still working draft (not yet ratified). Preview schemas may change without notice between releases. - 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 — the hub will ingest the new format as soon as the export ships. Note the gap in the changelog so adopters know what additional setup will be required. + 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 sinc 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. 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) @@ -45,8 +45,9 @@ To add a new FOCUS version: 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. Drop a new `FocusCost_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/). - 2. Mirror the schema details (columns, types, descriptions) from the matching Cost Management export schema so downstream consumers see consistent metadata. + 1. Create a `FocusCost_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. + 2. Create a `FinOpsHubs__.json` file into [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) @@ -56,14 +57,3 @@ To add a new FOCUS version: - [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. - -### Handling multiple FOCUS versions in one cycle - -Occasionally, the toolkit needs to support two FOCUS versions in a single release – for example, a newly ratified version alongside a working draft of the next version. When that happens: - -- The older version follows the standard `_v1_X` naming and ships as generally available (GA). -- The newer version uses the next `_v1_Y` suffix and is labeled **preview** in user-facing documentation, including [data-model.md](../../../../docs-mslearn/toolkit/hubs/data-model.md) and [changelog.md](../../../../docs-mslearn/toolkit/changelog.md). -- Preview schemas may change without notice between releases. Treat them as opt-in for early adopters only. -- The unversioned functions (`Costs()`, `Prices()`, etc.) alias to the latest **GA** schema, not the preview. The aliases promote to the newer version only after it transitions from preview to GA. - -This guarantees backwards compatibility for production consumers while still enabling early validation of the next FOCUS version. From 8ee2d63dff18a538c3dfee0563643fc3b0ec71e2 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 17 May 2026 20:17:08 +0000 Subject: [PATCH 05/11] chore: Update ms.date in docs-mslearn files --- docs-mslearn/toolkit/hubs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 62e0590eb..ecbe779f8 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 05/07/2026 +ms.date: 05/17/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit From 463c27355fbfc1f14381709e6cb1a16092865433 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Wed, 15 Jul 2026 12:37:19 -0700 Subject: [PATCH 06/11] Fix typos and wording in FOCUS upgrade docs Addresses PR #2123 review nits: "sinc" -> "since", "file into" -> "file in" (x2), and "transform it" -> "transform them" for grammatical agreement with "tables". Also refreshes ms.date on the modified docs-mslearn page. Co-Authored-By: Claude Fable 5 --- docs-mslearn/toolkit/hubs/data-model.md | 4 ++-- src/templates/finops-hub/docs/README.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index ecbe779f8..7ea35c761 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 05/17/2026 +ms.date: 07/15/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit @@ -56,7 +56,7 @@ One of the goals of the FinOps hubs data model is to guarantee backwards compati 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 it 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 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. diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index 4a12b9d1c..f5f8ed380 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -20,7 +20,7 @@ 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 sinc FOCUS working drafts may change without notice. + 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. 1. Add schema mapping file 1. Create new schema mapping file for the Cost Management export dataset version in the schemas folder @@ -45,8 +45,8 @@ To add a new FOCUS version: 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_.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. - 2. Create a `FinOpsHubs__.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each FinOps hub managed dataset schema version. + 1. Create a `FocusCost_.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. + 2. Create a `FinOpsHubs__.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: From 92f11785890fa00b125d4539a7f0e446ece2756f Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Sat, 25 Jul 2026 11:15:43 -0700 Subject: [PATCH 07/11] Update docs-mslearn/toolkit/hubs/data-model.md --- docs-mslearn/toolkit/hubs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 7ea35c761..7c77f9391 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -56,7 +56,7 @@ One of the goals of the FinOps hubs data model is to guarantee backwards compati 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 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 convenient 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. From e24f5f079cc97fc0c32ab6e424134c7b251bf8dd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 25 Jul 2026 18:16:20 +0000 Subject: [PATCH 08/11] chore: Update ms.date in docs-mslearn files --- docs-mslearn/toolkit/hubs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 7c77f9391..15b9a3408 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 07/15/2026 +ms.date: 07/25/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit From 8d022844650a86b7b1b5284b83272807493a29bc Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Sat, 25 Jul 2026 13:15:58 -0700 Subject: [PATCH 09/11] docs: clarify ingestion transform model and fix versioned-function wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback on the FOCUS multi-version docs refresh: - data-model.md: reword the "Schema version" ingestion paragraph to say data is transformed to the current release's schema version (not the "latest FOCUS version"), and that older data stays in the schema version it was originally ingested into. Removes the apparent ingestion-vs-query contradiction while matching the actual KQL update-policy behavior. - data-model.md: tighten the Cost Management export-availability note by dropping the vague "(forward or backward, depending on your release)" parenthetical. - data-model.md: fix copy-paste error — "Unversioned functions, like Costs_v1_0()" should read "Versioned functions". - README.md: note the `-preview` suffix convention for working-draft FOCUS versions in the open-data metadata step. Co-Authored-By: RolandKrummenacher Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-mslearn/toolkit/hubs/data-model.md | 6 +++--- src/templates/finops-hub/docs/README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index 15b9a3408..b17d85785 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -54,7 +54,7 @@ Note the use of "Data Explorer" covers both Azure Data Explorer and Microsoft Fa 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. +During ingestion, data is transformed to the schema version of your current FinOps hub release, regardless of the FOCUS version of the source data. For instance, if your hub uses the `v1_4` schema, incoming FOCUS 1.0 data is converted to FOCUS 1.4 as it's ingested. Data ingested by an earlier release stays in the schema version it was originally ingested into. For instance, data ingested when your hub used the `v1_2` schema remains in the `v1_2` format even after you upgrade 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 convenient for ad hoc use while versioned functions are recommended for integration points that require a consistent format after upgrades. @@ -66,7 +66,7 @@ The following table indicates the schema version for each FinOps hub release and | 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). +Cost Management export availability for a given FOCUS version is separate from FinOps hub support for that version. FinOps hubs transforms export data to the schema version of your current release during ingestion, whether the export uses an older or newer FOCUS version than that schema.
@@ -88,7 +88,7 @@ Managed datasets also include the following assets for FinOps hubs with Data Exp - An unversioned function in the **Hub** database (for example, **Costs()**). - A table in Power BI KQL reports that wraps the corresponding versioned function. -During data ingestion, FinOps hubs transform data to the latest supported [schema version](#schema-version). Unversioned functions, like **Costs()**, use the latest schema version. Unversioned functions, like **Costs_v1_0()**, are backwards compatible, should remain consistent, and do not need to change when upgrading your FinOps hub instance. To learn more about the data ingestion process, see [How data is processed in FinOps hubs](data-processing.md). +During data ingestion, FinOps hubs transform data to the latest supported [schema version](#schema-version). Unversioned functions, like **Costs()**, use the latest schema version. Versioned functions, like **Costs_v1_0()**, are backwards compatible, should remain consistent, and do not need to change when upgrading your FinOps hub instance. To learn more about the data ingestion process, see [How data is processed in FinOps hubs](data-processing.md). When querying data in FinOps hubs, always use the **Hub** database and avoid working with the tables and functions in the **Ingestion** database. Use unversioned functions for ad-hoc analysis or reports that do not require long-term backwards compatibility. Use the versioned functions for reports or systems that do require backwards compatibility and you do not want to be impacted by FinOps hub updates, which may change column names, data types, and values. diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index f5f8ed380..a25a7314d 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -45,7 +45,7 @@ To add a new FOCUS version: 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_.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. + 1. Create a `FocusCost_.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. Use a `-preview` suffix for working draft FOCUS versions (for example, `FocusCost_1.2-preview.json`), matching the existing files. 2. Create a `FinOpsHubs__.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 From 626ecd8e1f5375e5bae749855fd5c27aa9292eb6 Mon Sep 17 00:00:00 2001 From: Michael Flanakin Date: Sun, 26 Jul 2026 09:54:34 -0700 Subject: [PATCH 10/11] Fix schema file naming reference --- src/templates/finops-hub/docs/README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/templates/finops-hub/docs/README.md b/src/templates/finops-hub/docs/README.md index a25a7314d..a639316eb 100644 --- a/src/templates/finops-hub/docs/README.md +++ b/src/templates/finops-hub/docs/README.md @@ -2,10 +2,10 @@ ## Data ingestion workflow -- All data is ingested into tables named "*_raw". +- All data is ingested into tables named "\*\_raw". - Raw tables are declared in [IngestionSetup_raw.kql](../modules/scripts/IngestionSetup_raw.kql). - These tables have a union schema to support multiple sources and versions. -- All data is transformed to the latest FOCUS schema using an update policy into a "*_final_vX_Y" table named after the version (for example, "1.0" = "_v1_0"). Final tables, Transform functions, and update policies are in the versioned setup files: +- All data is transformed to the latest FOCUS schema using an update policy into a "\*\_final_vX_Y" table named after the version (for example, "1.0" = "\_v1_0"). Final tables, Transform functions, and update policies are in the versioned setup files: - [IngestionSetup_v1_0.kql](../modules/scripts/IngestionSetup_v1_0.kql) - Data ingestion from previous version of hubs will remain in the versioned tables. - Data is read from versioned functions in the Hub database. See HubSetup_vX_Y.kql in the [modules/scripts folder](../modules/scripts) for details. @@ -26,26 +26,26 @@ To add a new FOCUS version: 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) 2. Update ingestion database scripts - 1. Add new columns to the *_raw tables per dataset in [IngestionSetup_RawTables.kql](../modules/scripts/IngestionSetup_RawTables.kql) + 1. Add new columns to the \*\_raw tables per dataset in [IngestionSetup_RawTables.kql](../modules/scripts/IngestionSetup_RawTables.kql) 2. Save a copy of the latest version of the IngestionSetup_vX_Y.kql using the latest FOCUS version - If updating the same version, increment the release number (e.g., `r2`) 3. Rename all functions, tables, and policies in the new file to the new version (leave the old as-is) - 4. Update the *_final_vX_Y tables to account for any new columns - 5. Update the *_transform_vX_Y functions to account for any new columns - 6. Update the script to delete the old update policy for the *_raw tables + 4. Update the \*\_final_vX_Y tables to account for any new columns + 5. Update the \*\_transform_vX_Y functions to account for any new columns + 6. Update the script to delete the old update policy for the \*\_raw tables 7. Confirm the new file has the update policy set to use the latest version of the transform function and final table 3. Update hub database scripts 1. Add new FOCUS version section after the latest version section and before existing version sections - 2. Create new *_vX_Y functions per dataset that transforms older data to the new FOCUS version - 3. Update the unversioned functions to use the new *_vX_Y functions - 4. Update older versioned functions to also pull from the new *_vX_Y functions and transform to the old schema + 2. Create new \*\_vX_Y functions per dataset that transforms older data to the new FOCUS version + 3. Update the unversioned functions to use the new \*\_vX_Y functions + 4. Update older versioned functions to also pull from the new \*\_vX_Y functions and transform to the old schema 4. Update reports and dashboards 1. Update the storage reports to use the new columns 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_.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. Use a `-preview` suffix for working draft FOCUS versions (for example, `FocusCost_1.2-preview.json`), matching the existing files. + 1. Create a `FocusCost_.json` file in [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version. `` must match the precise Cost Management export version, including `-preview`, if applicable (for example, `FocusCost_1.2-preview.json`). 2. Create a `FinOpsHubs__.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 From 32632710b6605cbafdd5209b6303003a13037748 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 26 Jul 2026 16:55:17 +0000 Subject: [PATCH 11/11] chore: Update ms.date in docs-mslearn files --- docs-mslearn/toolkit/hubs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-mslearn/toolkit/hubs/data-model.md b/docs-mslearn/toolkit/hubs/data-model.md index b17d85785..d9b5cf6c8 100644 --- a/docs-mslearn/toolkit/hubs/data-model.md +++ b/docs-mslearn/toolkit/hubs/data-model.md @@ -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: 07/25/2026 +ms.date: 07/26/2026 ms.topic: reference ms.service: finops ms.subservice: finops-toolkit