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. You can specify how dashboard datasets relate to each other and create reusable measures that span multiple datasets. Instead of pre-joining data in SQL or duplicating join logic across datasets, you model relationships 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 Public 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 pane​

To open the Relationships pane:

  1. Open an AI/BI dashboard in edit mode.
  2. Click the Data tab.
  3. Click the ERD icon. relationships icon on the Data tab.
  4. If the dashboard has no 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 pane, 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 the joins each visualization requires 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 in the Relationships pane 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 pane, 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 pane 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 might change before Public Preview or General Availability.

Limitations​

The following limitations apply to dashboard relationships in this Public Preview:

  • Dashboard relationships are scoped to the dashboard and aren't reusable across other surfaces. Export to Unity Catalog is not available in this Public Preview.
  • 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.
  • A dashboard supports at most one semantic model.
  • For existing dashboards, you might need to start the semantic model before relationships are available in the visualization editor.

Next steps​

On this page