# Migrate Databricks Metric Views to Holistics

> Migrate a Databricks Metric View into Holistics, then extend it for AI-assisted analysis, reports, and dashboards.

:::caution Private preview
This workflow is in private preview until it is available end to end. Holistics provides preview access to the CLI and skill. Validate all generated AML before using it in production.
:::

## How it works

The preview workflow retrieves the Metric View definition, gives it to a coding-agent skill, and produces editable Analytics Modeling Language (AML) files for review and publication.

<ReactFlowDiagram id="databricks-metric-view-migration" height={300} fixed />

Start by identifying the governed measures you want to reuse in Databricks Catalog Explorer.

## Before you begin

Prepare the connection, project, and preview tooling before retrieving the definition.

- A working [Databricks connection](/docs/connect/databases/databricks)
- A [local Holistics project](/docs/development/local-agentic-development)
- The [`databricks_metric_views_to_amql` skill](https://github.com/holistics/skills) installed in your coding agent
- Databricks privileges to run `DESCRIBE` on the Metric View

## Migrate a Metric View

Use one Metric View as the migration unit, then review the generated files as you would any other semantic-layer change.

1. Run the skill in your coding agent with the Metric View and Holistics data source you want to migrate:

   ```text
   /databricks_metric_views_to_amql Migrate the `main.default.orders_metric_view` Metric View from `your_databricks_data_source` into Models and a Dataset in the current Holistics project.
   ```

   The skill starts by pulling the Metric View definition into a local migration folder:

   ```bash
   holistics query \
     'describe table extended `main`.`default`.`orders_metric_view` as json' \
     --data-source 'your_databricks_data_source' \
     --output 'metric-view-migration/orders_metric_view/source/raw.json'
   ```

   The returned metadata contains the YAML definition that describes the source, joins, dimensions, and measures.

   

2. Review the generated models, datasets (relationships, metrics, and row-level permissions), AI context, and source mappings. Adjust names and business context before publishing.

Complete the next two steps yourself or ask your coding agent to run them.

3. Validate the project:

   ```bash
   holistics aml validate \
     models/*.model.aml \
     datasets/orders.dataset.aml
   ```

4. Start the local preview sync:

   ```bash
   holistics sync-code .
   ```

   This process keeps running until you press `Ctrl+C`. Preview the Dataset in Reporting and Canvas Dashboards, then use your normal review and publishing workflow when the migration is ready.

### Example source definition

For example, a Databricks Metric View can define nested many-to-one joins and governed measures in YAML.

```yaml
version: 1.1
source: samples.tpch.orders
joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    cardinality: many_to_one
    rely:
      at_most_one_match: true
    joins:
      - name: nation
        source: samples.tpch.nation
        on: customer.c_nationkey = nation.n_nationkey
        cardinality: many_to_one
        rely:
          at_most_one_match: true
measures:
  - name: order_count
    expr: count(1)
    display_name: Order count
    comment: Number of orders
  - name: total_revenue
    expr: sum(source.o_totalprice)
    display_name: Total revenue
    comment: Total order revenue
```

### Example Holistics Dataset

Source tables and joins become Models and Relationships. This excerpt shows the generated Dataset. The skill also generates the referenced `orders`, `customers`, and `nations` Models.

```aml title="orders.dataset.aml"
Dataset orders_dataset {
  label: 'Orders Semantic Layer'
  description: 'Orders with customer and nation context.'
  data_source_name: 'your_databricks_data_source'

  models: [orders, customers, nations]

  relationships: [
    relationship(orders.customer_id > customers.customer_id, true),
    relationship(customers.nation_id > nations.nation_id, true)
  ]

  metric order_count {
    label: 'Order count'
    description: 'Number of orders'
    type: 'number'
    definition: @aql count(orders.order_id);;
  }

  metric total_revenue {
    label: 'Total revenue'
    description: 'Total order revenue'
    type: 'number'
    definition: @aql sum(orders.total_price);;
  }
}
```

## Continue in Holistics

After migration, treat the generated AML as the starting point for normal Holistics development.

- Add [dimensions](/docs/dimensions-in-datasets), [metrics](/docs/metrics-in-datasets), descriptions, and [AI context](/docs/ai/context/semantic-and-reporting-layers).
- Query the Dataset and build reusable analyses in [Reporting](/docs/data-exploration).
- Publish curated experiences as [Canvas Dashboards](/docs/dashboards).

## Validate the migration

Validation should cover both code correctness and business-result parity before the migrated Dataset is shared.

- Confirm the AML compiles with `holistics aml validate`.
- Review relationship keys and cardinality assumptions.
- Compare same-data totals by representative dimensions and a fixed date range.
- Test user permissions against the intended audience.
- Check query performance with representative reports.

`holistics aml validate` checks the AML project, but it does not prove numerical parity with the Databricks Metric View.

## Current limits

Account for these private-preview limits when planning a migration.

| Limit | What to check |
| --- | --- |
| One-time migration | There is no automatic synchronization or round-trip conversion. Rerun and review the migration when the source changes. |
| Advanced measure behavior | Review complex Databricks parameters, windows, and semi-additive behavior manually. |
| Join guarantees | Validate the underlying data before carrying `rely.at_most_one_match` assumptions into relationship cardinality. |
| Multi-catalog sources | Three-part identifiers and sources spanning catalogs may need [Query Models](/docs/query-models). |
| Generated code | The generated AML remains customer-owned and editable. Maintain it as part of your Holistics project. |

## Related resources

Use these guides to set up the workflow and extend the migrated semantic layer.

- [Connect to Databricks](/docs/connect/databases/databricks)
- [Holistics CLI](/docs/cli)
- [Local development with AI agents](/docs/development/local-agentic-development)
- [Models](/docs/data-model)
- [Datasets and metrics](/docs/datasets)
- [Semantic and reporting layers as AI context](/docs/ai/context/semantic-and-reporting-layers)
- [Canvas Dashboards](/docs/dashboards)