Skip to main content
Last updated on

Dashboard relationships

Preview

This feature is in Private Preview. To try it, reach out to your Databricks contact.

Dashboard relationships enable you to define a semantic model scoped to an AI/BI dashboard — specifying how dashboard datasets relate to each other and creating reusable measures that span multiple datasets. Instead of pre-joining data in SQL or duplicating join logic across datasets, you model relationships once and use them across all visualizations in the dashboard.

Dashboard relationships are dashboard-scoped and do not create a Unity Catalog object. Use them for prototyping, dashboard-specific analysis, or when you want to iterate before promoting logic to Unity Catalog. For metrics that must be governed and shared across dashboards, Genie Spaces, or other tools, use Unity Catalog metric views instead. See Unity Catalog metric views.

Requirements​

To use dashboard relationships, your workspace must meet the following requirements:

  • The Dashboard Relationships preview must be enabled for your workspace. A workspace admin can enable the feature from the Previews portal. See Manage Databricks previews.
  • You must have CAN EDIT permissions on the dashboard.
  • You must have CAN USE permissions on a SQL warehouse.
  • The dashboard must have at least two datasets.

Open the Relationships panel​

To open the Relationships panel:

  1. Open an AI/BI dashboard in edit mode.
  2. Click the Data tab.
  3. Click Relationships on the Data tab.
  4. If the dashboard does not yet have a semantic model, click Get started with Relationships. Databricks initializes a semantic model from the datasets already in the dashboard.

Define a relationship​

A relationship joins two dashboard datasets on compatible fields and defines cardinality so the query engine knows how to combine them correctly.

To create a relationship:

  1. In the Relationships panel, click Add relationship.
  2. Select the left dataset and the join field from that dataset.
  3. Select the right dataset and the join field from that dataset.
  4. Select the cardinality:
    • Many-to-One: Use when the left dataset is a fact table and the right dataset is a dimension table (for example, orders.customer_id = customers.customer_id).
    • One-to-Many: Use when the left dataset is a dimension table and the right dataset is a fact table.
  5. Click Save.

After you save the relationship, the query engine automatically resolves which joins are needed for each visualization at runtime. Filters on dimension tables propagate to related fact tables without requiring manual correlated subqueries in each dataset definition.

Add a cross-dataset measure​

Cross-dataset measures are reusable calculations that reference fields across related datasets. You define them once in the Relationships panel and they are available in the visualization editor for any widget that uses the modeled datasets.

To add a cross-dataset measure:

  1. In the Relationships panel, click Add measure.
  2. Enter a name for the measure.
  3. Define the measure expression, referencing fields from any related dataset.
  4. Click Save.

Cross-dataset measures are only available after at least one relationship is defined between the relevant datasets.

Use the field picker​

When you build a visualization, the field picker surfaces fields from all datasets connected by relationships, grouped by dataset name. As you select fields, the field picker updates availability based on what the query engine can resolve — fields that would result in an ambiguous or unsupported join path are excluded.

Edit in YAML​

You can inspect and edit the full relationship model definition in YAML. Click YAML in the Relationships panel to switch to the YAML editor. The YAML editor is useful for reviewing the complete model, making bulk edits, or copying the definition to another dashboard.

note

The YAML schema for dashboard relationships may change before Public Preview or General Availability.

Limitations​

The following limitations apply to dashboard relationships in this preview:

  • Dashboard-scoped only — relationships are local to the dashboard and are not reusable across other surfaces. Export to Unity Catalog is not available in this preview.
  • Equality joins only — relationships must join two datasets on a single equality condition. Many-to-many joins, cyclical graphs, and ambiguous join paths are not supported.
  • Cardinality is limited to Many-to-One and One-to-Many. Model direct many-to-many relationships using a bridge table instead.
  • At most one semantic model per dashboard.
  • Existing dashboards may require you to initialize the semantic model before relationships are available in the visualization editor.

Next steps​

On this page