{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["callout","cards","card","img","faq","faq-item","partial"]},"type":"markdown"},"seo":{"title":"Migrate legacy metrics with the migration tool","description":"Move legacy metrics onto datasets in a few guided steps, with every dashboard and report reference updated for you automatically.","siteUrl":"https://help.databox.com","llmstxt":{"title":"Databox Knowledge Base","description":"Databox is a business analytics platform that consolidates data in one place, enabling real-time performance tracking and insights by mixing and matching data from various sources for a comprehensive view.","details":{"content":"This knowledge base covers everything from account setup and integrations to building Databoards, creating custom metrics, and using AI-powered features."},"sections":[{"title":"General","includeFiles":["docs/general/*.md","docs/general/visualization-types/*.md","docs/general/templates/*.md"],"excludeFiles":[]},{"title":"AI","includeFiles":["docs/ai/*.md"],"excludeFiles":[]},{"title":"Account Management","includeFiles":["docs/account-management/**/*.md"],"excludeFiles":[]},{"title":"Databoards","includeFiles":["docs/databoards/**/*.md"],"excludeFiles":[]},{"title":"Data Management","includeFiles":["docs/data-management/**/*.md"],"excludeFiles":[]},{"title":"Metrics","includeFiles":["docs/metrics/**/*.md"],"excludeFiles":[]},{"title":"Forecasts","includeFiles":["docs/forecasts/*.md"],"excludeFiles":[]},{"title":"Goals","includeFiles":["docs/goals/*.md"],"excludeFiles":[]},{"title":"Reports","includeFiles":["docs/reports/*.md"],"excludeFiles":[]},{"title":"Notifications","includeFiles":["docs/notifications/*.md"],"excludeFiles":[]},{"title":"Pricing and Billing","includeFiles":["docs/pricing-and-billing/*.md"],"excludeFiles":[]},{"title":"Mobile","includeFiles":["docs/mobile/*.md"],"excludeFiles":[]},{"title":"Support","includeFiles":["docs/support/*.md"],"excludeFiles":[]},{"title":"Integrations","includeFiles":["docs/integrations/**/*.md"],"excludeFiles":[]}],"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migrate-legacy-metrics-with-the-migration-tool","__idx":0},"children":["Migrate legacy metrics with the migration tool"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Legacy ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-sql-metrics-to-datasets"},"children":["SQL"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-spreadsheet-metrics-to-datasets"},"children":["spreadsheet"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-api-v0-to-databox-api-v1"},"children":["Legacy API (v0)"]}," metrics are being deprecated. The in-app migration tool re-creates each one as a dataset-based metric, checks that the migrated data matches the original, and repoints every reference across your Databoards, reports, and calculated metrics, so nothing breaks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"warning"},"children":["Creating new legacy SQL, spreadsheet, and Legacy API (v0) metrics is no longer supported. Your existing legacy metrics will keep working for now, but they're being deprecated. Migrate them so content is unaffected once legacy metrics are retired."]}," ","Jump to the workflow for your metric type:"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":3,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Spreadsheet metrics","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"center","variant":"elevated","to":"#migrate-spreadsheet-metrics"},"children":[]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"SQL metrics","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"center","variant":"elevated","to":"#migrate-sql-metrics"},"children":[]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Legacy API (v0) metrics","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"center","variant":"elevated","to":"#migrate-legacy-api-v0-metrics"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"open-the-migration-tool","__idx":1},"children":["Open the migration tool"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.databox.com/data-manager/connected"},"children":["Data Manager"]},", any data source with legacy metrics is marked with a warning triangle. Open the migration modal in one of two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Hover the warning triangle"]}," and click the link in the tooltip."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Click the down arrow"]}," (",{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/chevron-down.dfd0e90adc6eb576be32262463090aae7c7f5408ed7975e3795f69775e36d174.419bb737.svg","alt":"chevron-down"},"children":[]},") next to the data source and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migrate legacy metrics"]},"."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_1.6ebeedf2e6322b8eaf943a2071b567c68e02e7e877096855d3c8a521054a4d25.4783b0ec.png","alt":"data-source-list-migrate-legacy-metrics-menu","framed":false,"withLightbox":true,"className":"ss-img","style":"margin-bottom: 10px;"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tool opens as a short, guided wizard, already showing the legacy metrics for the data source you chose. From there (or from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data Source"]}," step first, if you arrived via a direct link) you select the metrics to migrate, review the proposal, run the migration, and replace the old references. Legacy API (v0) sources add an extra ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Code"]}," step before ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"work-in-the-metrics-step","__idx":2},"children":["Work in the Metrics step"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metrics"]}," step is the heart of the tool and works the same way for all three metric types, so the workflows below refer back here. The header shows the data source name, its type, and the subtitle ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Select the custom metrics you want to migrate"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the metrics you want with the row checkboxes (or the header checkbox to select all visible rows), then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," to move to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Proposal"]}," step."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-the-list","__idx":3},"children":["Filter the list"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Filter"]}," dropdown to narrow what's shown:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["All metrics"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metrics with usages"]},": metrics used somewhere (Databoards, reports, etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metrics without usages"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migrated metrics"]},": already migrated (name begins with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[MIGRATED]"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replaced metrics"]},": already replaced (name begins with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[REPLACED]"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"row-actions","__idx":4},"children":["Row actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each row has a strip of icons on the right. Each opens a tool for that metric; availability depends on the metric type."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"class":"table-header","className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Metric types"},"children":["Metric types"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lists every place the metric appears, grouped by type (Databoards, reports, notifications, metric anomalies, forecasts, goals, and more), each with a count and an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Open"]}," link that jumps to that specific item (Databoard, report, goal, team, and so on). A crossed-out eye means the metric has no usages."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Compare"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lets you pick a data source and metric to validate this legacy metric against. The tool checks the two across several date ranges and reports matches and mismatches."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lets you repoint this metric's usages onto another metric."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metric"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Displays the processed data the metric returns (up to 200 rows)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Raw"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Displays the underlying raw source rows behind the metric (up to 200 rows)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ingestion snippet for the metric, plus the option to back-fill its historical data."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Legacy API (v0)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["History"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Copies the metric's accumulated history into a new dataset so it's preserved."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SQL and spreadsheet"]}]}]}]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_2.aa2dbb6978a0a0cda0178e3a957fe490464b34b204925aa654c795205862b61e.4783b0ec.png","alt":"metrics-step-row-actions","framed":false,"withLightbox":true,"className":"ss-img"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migrate-spreadsheet-metrics","__idx":5},"children":["Migrate Spreadsheet metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Legacy spreadsheet metrics read values from a source document on every refresh. Migrating them to datasets loads the whole sheet once and lets you build many metrics, dimensions, and calculations on top of it. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-spreadsheet-metrics-to-datasets"},"children":["Migrate from legacy spreadsheet metrics to datasets"]}," for the full rationale."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"select-the-metrics","__idx":6},"children":["Select the metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the spreadsheet metrics you want to migrate and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]},". For columns, filters, selection, and the per-row icons on this screen, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#work-in-the-metrics-step"},"children":["Work in the Metrics step"]},". For spreadsheet metrics, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Measure"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Date"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dimension"]}," columns show which cells each metric reads."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"review-the-proposal","__idx":7},"children":["Review the proposal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tool groups your metrics by their source tab (one proposal group per tab). For each group:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header row"]}," selector (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["0"]}," for no header, or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3"]},") tells the tool which row in the spreadsheet holds your column names. Choosing the correct header row determines how legacy metrics map to the new dataset columns and directly affects whether the migration succeeds. Changing it re-runs the preview."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each metric shows a live column mapping between the legacy metric and the new metric, for example ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Measure · col D → \"Revenue\""]},". It turns green when the column resolves to a valid type and red when it doesn't."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Preview data"]}," to see the resolved columns and sample rows (up to 200 rows)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Approve all"]}," checkbox, or the per-metric checkboxes, to choose what gets migrated. Uncheck anything you want to skip."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Metrics whose columns can't be mapped automatically are collected in an amber ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatic migration not viable"]}," list and aren't migrated automatically. You can handle those later using the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#row-actions"},"children":["row actions"]},"."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_3.ff9833c95ec49759c36a542450de400db0cbba606865cf7e8b0ac903bdcac761.4783b0ec.png","alt":"spreadsheet-migration-proposal","framed":false,"withLightbox":true,"className":"ss-img","style":"margin-top: 10px;"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"run-the-migration","__idx":8},"children":["Run the migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The migration runs automatically, showing one section per source tab, labeled by tab name (for example, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tab: Marketing Data"]},"), each with ordered steps and a status icon: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creating dataset → Setting up query → Waiting for dataset → Creating metric → Validating metric → Renaming legacy metric"]},". The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validating metric"]}," step compares the new dataset metric against the original across several date ranges and reports how many data points match. The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Renaming legacy metric"]}," step prefixes the original metric with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[MIGRATED]"]}]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stop Migration"]}," halts the run; any in-progress step becomes a warning."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each finished section has a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]}," button that undoes it, deleting the new dataset and restoring the legacy metric's name."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When every section finishes, a green ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migration Complete"]}," panel shows a table mapping each legacy metric to its new metric."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"replace-references","__idx":9},"children":["Replace references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}," step repoints every usage of each legacy metric onto its new dataset-backed metric, then renames the legacy metric with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[REPLACED]"]}," prefix so it's easy to spot."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Legacy metric → New metric"]}," table. Each pair shows its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usages"]}," count, and metrics that have usages are pre-selected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To check where a metric is used first, click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Usages"]}," icon on its row."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace Selected"]},". For each pair, the tool re-checks usages, rewrites the references, and renames the legacy metric. A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stop All"]}," button is available while it runs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a pair completes, you can click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]}," to undo it, or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete legacy"]}," to remove the old metric permanently. Deleting asks you to type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," to confirm."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_4.52a7b7ddd57617ca580bab4101ae027a814ef947268b3c60b9cf5850d6338ae8.4783b0ec.png","alt":"custom-push-migration-proposal","framed":false,"withLightbox":true,"className":"ss-img"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migrate-sql-metrics","__idx":10},"children":["Migrate SQL metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Legacy SQL metrics run a separate database query for every metric on every refresh: 200 metrics means 200 queries each time data refreshes. With datasets, one query can power dozens or hundreds of metrics, cutting database load and speeding up refreshes. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-sql-metrics-to-datasets"},"children":["Migrate from legacy SQL metrics to datasets"]}," for the full rationale."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"select-the-metrics-1","__idx":11},"children":["Select the metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the SQL metrics you want to migrate and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#work-in-the-metrics-step"},"children":["Work in the Metrics step"]}," for the columns, filters, selection, and per-row icons. For SQL metrics, the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SQL Query"]}," column shows each metric's query. Hover to see it in full."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"review-the-proposal-1","__idx":12},"children":["Review the proposal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tool proposes how to consolidate your metrics into shared datasets, grouping metrics that a single query can serve. A green banner reports how the metrics were grouped. For each consolidation group:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Consolidated SQL Query"]}," editor shows the SQL that will define the dataset, which you can edit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Preview data"]}," to run the query and see up to 200 rows with column types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Approve all"]}," or the per-metric checkboxes to include or exclude metrics."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migrate individually"]}," to pull a metric out of a group into its own dataset, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Move back to group"]}," to undo. Individually migrated metrics appear in their own section, each with an editable query."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A blue ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Existing dataset"]}," badge means a matching dataset already exists and will be reused instead of creating a new one."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," once at least one metric will be migrated and every group has SQL."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"warning"},"children":["The consolidation plan may be generated by AI, in which case an amber banner appears and the SQL carries a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generated by AI"]}," badge. Always review AI-generated queries before continuing: edit the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Consolidated SQL Query"]}," and use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Preview data"]}," to confirm the results."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"run-the-migration-and-replace-references","__idx":13},"children":["Run the migration and replace references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Execute"]}," step behaves exactly as it does for spreadsheet metrics (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#run-the-migration"},"children":["Run the migration"]},"). It works through ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creating dataset → Setting up query → Waiting for dataset → Creating metric → Validating metric → Renaming legacy metric"]},", with per-section status icons, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stop Migration"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]},". Reused datasets show ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using existing dataset…"]}," instead of creating a new one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}," step is also identical (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#replace-references"},"children":["Replace references"]},"). Review the Legacy → New pairs, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace Selected"]},", and optionally ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete legacy"]}," afterward."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migrate-legacy-api-v0-metrics","__idx":14},"children":["Migrate Legacy API (v0) metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Legacy Legacy API (v0) metrics send pre-aggregated values to Databox. Migrating to the Databox API (v1) moves you to a dataset-based architecture that separates data ingestion from metric creation: you send raw records, then build metrics on top. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/migrate-from-legacy-api-v0-to-databox-api-v1"},"children":["Migrate from Legacy API (v0) to Databox API (v1)"]}," for the full rationale."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because you send data to Legacy API (v0) metrics from your own code, this workflow adds an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Code"]}," step before ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}," so your integration keeps sending data to the new dataset."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"select-the-metrics-2","__idx":15},"children":["Select the metrics"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select the Legacy API (v0) metrics you want to migrate and click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#work-in-the-metrics-step"},"children":["Work in the Metrics step"]}," for the shared behavior. A few things are specific to Legacy API (v0): the table shows only the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metric Name"]}," column, and each row has an extra ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Code"]}," action that opens ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update client code"]}," for that single metric."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"review-the-proposal-2","__idx":16},"children":["Review the proposal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tool creates one dataset per metric key."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key check"]},": a green banner confirms an API key was found. An API key is required to migrate your historical data into the new ingestion dataset."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data source"]},": choose where the new datasets live.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use existing data source"]},": reuse a Databox API source already on your account (no new billed source)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create new data source"]},": enter a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New data source name"]}," and confirm that this creates a new, billed Databox API data source."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Per-key dataset cards"]},": one card per metric key. Each lists its legacy metrics (uncheck any to exclude) and a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Preview historical data"]}," button showing the first 20 records that would be ingested."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," once the API key is present, at least one metric is included, and you've chosen (or named and acknowledged) a data source."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"note"},"children":["You need a Databox API key to continue. If none is found, an amber banner explains how to create one under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account → Password & Security → API keys"]},"; create it, then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Re-check for API key"]},"."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_5.88a4a08b4bf9a8c81ba0ded0d6bc3802094d6687ebcf785249d184937ae68915.4783b0ec.png","alt":"custom-push-update-code-step","framed":false,"withLightbox":true,"className":"ss-img"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"run-the-migration-1","__idx":17},"children":["Run the migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The migration creates (or reuses) the chosen Databox API data source, creates one dataset per metric key, and back-fills your historical data into each dataset. Progress shows as sections (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creating data source → Creating dataset → Waiting for dataset → Back-filling history → Waiting for ingestion → Finalizing → Creating metric → Validating metric → Renaming legacy metric"]},"), each with the usual status icons, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stop Migration"]},", and per-dataset ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When it finishes, the green ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migration Complete"]}," panel appears. Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," to move to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update Code"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-your-push-code","__idx":18},"children":["Update your push code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your historical data is now in a new dataset, but your integration is still pushing to the old endpoint. This step gives you the code to point it at the new dataset."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A language toggle switches the code snippet between curl and the other supported languages."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each dataset card shows the resolved ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DATASET_ID"]}," and a code snippet with a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Copy"]}," button. In the snippet, replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<YOUR_API_KEY>"]}," with your own Databox API key, send the same columns the migration used, and note that you can ingest up to 500 records per request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update historical data"]}," panel lets you append any additional push rows for the chosen metrics: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update selected"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update all related metrics"]},". Existing rows are preserved."]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/migrate-legacy-metrics-with-the-migration-tool_6.50e9177f099a438e2c9ab3b27bf78caeb3cb5423133959702fcb54bf5293c233.4783b0ec.png","alt":"custom-push-update-code-step","framed":false,"withLightbox":true,"className":"ss-img"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"replace-references-1","__idx":19},"children":["Replace references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your code is updated, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue"]}," to reach ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]},". This step is identical to the other workflows (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#replace-references"},"children":["Replace references"]},"). Review the Legacy → New pairs, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace Selected"]},", and optionally ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rollback"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delete legacy"]}," afterward."]},{"$$mdtype":"Tag","name":"Faq","attributes":{},"children":[{"$$mdtype":"Tag","name":"FaqItem","attributes":{"question":"Can I migrate my metrics in batches instead of all at once?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes, and it's a good idea to start small. Migrate a single metric or a small batch first so you can see the full flow (migration, validation, and replacement) and confirm the results. Once you're confident, select larger batches, or all metrics at once, with the row checkboxes, and use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Filter"]}," dropdown (including ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migrated metrics"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replaced metrics"]},") to track what's done and pick up where you left off."]}]},{"$$mdtype":"Tag","name":"FaqItem","attributes":{"question":"What happens to my legacy metrics after they're migrated?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Migrating renames each one with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[MIGRATED]"]}," prefix; replacing its references then changes that to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[REPLACED]"]},". Either way they're easy to spot, and they stay in your account until you remove them. You can delete a legacy metric permanently from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}," step, which asks you to type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," to confirm."]}]},{"$$mdtype":"Tag","name":"FaqItem","attributes":{"question":"Will my Databoards and reports break during migration?"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. The tool re-creates each metric on a dataset and validates it against the original before the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Replace"]}," step rewrites any references. You can review usages and roll back at each stage, so your content keeps working throughout."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[" "]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":4,"cardMinWidth":160},"children":[{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Ask Genie","icon":"genie","to":"https://app.databox.com/genie","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get instant answers or help with your data using the in-app AI assistant."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Talk to an expert","icon":"assistance","to":"https://meetings.hubspot.com/databox-meeting/account-management","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For customers: Get help with your setup, strategy, or making the most of Databox."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Book a demo","icon":"eye-open","to":"https://meetings.hubspot.com/databox-meeting/ref-knowledge-base","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New to Databox? See how it works and get guidance on getting started."]}]},{"$$mdtype":"Tag","name":"FooterCard","attributes":{"title":"Send an email","icon":"help","to":"mailto:help@databox.com","variant":"elevated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reach out to support for help with your account, data, or technical issues."]}]}]}]},"headings":[{"value":"Migrate legacy metrics with the migration tool","id":"migrate-legacy-metrics-with-the-migration-tool","depth":1},{"value":"Open the migration tool","id":"open-the-migration-tool","depth":2},{"value":"Work in the Metrics step","id":"work-in-the-metrics-step","depth":2},{"value":"Filter the list","id":"filter-the-list","depth":3},{"value":"Row actions","id":"row-actions","depth":3},{"value":"Migrate Spreadsheet metrics","id":"migrate-spreadsheet-metrics","depth":2},{"value":"Select the metrics","id":"select-the-metrics","depth":3},{"value":"Review the proposal","id":"review-the-proposal","depth":3},{"value":"Run the migration","id":"run-the-migration","depth":3},{"value":"Replace references","id":"replace-references","depth":3},{"value":"Migrate SQL metrics","id":"migrate-sql-metrics","depth":2},{"value":"Select the metrics","id":"select-the-metrics-1","depth":3},{"value":"Review the proposal","id":"review-the-proposal-1","depth":3},{"value":"Run the migration and replace references","id":"run-the-migration-and-replace-references","depth":3},{"value":"Migrate Legacy API (v0) metrics","id":"migrate-legacy-api-v0-metrics","depth":2},{"value":"Select the metrics","id":"select-the-metrics-2","depth":3},{"value":"Review the proposal","id":"review-the-proposal-2","depth":3},{"value":"Run the migration","id":"run-the-migration-1","depth":3},{"value":"Update your push code","id":"update-your-push-code","depth":3},{"value":"Replace references","id":"replace-references-1","depth":3}],"frontmatter":{"slug":"migrate-legacy-metrics-with-the-migration-tool","seo":{"title":"Migrate legacy metrics with the migration tool","description":"Move legacy metrics onto datasets in a few guided steps, with every dashboard and report reference updated for you automatically."},"keywords":{"includes":["metric migration tool","migration wizard","migrate legacy metrics to datasets","legacy metrics deprecated","replace legacy metrics","rollback migration","migrate SQL metrics","migrate spreadsheet metrics","migrate legacy api metrics","legacy metrics banner","convert metric to dataset","how to migrate metrics","migrate metrics without breaking dashboards"]}},"lastModified":"2026-07-14T08:59:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/migrate-legacy-metrics-with-the-migration-tool","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}