Retrieving the current filter state in Embedded Dashboards

In my previous blogpost, we explored different ways to set and manage filter state when embedding a Superset dashboard into your application. That’s half the story: often, you’ll also want to know what the current state of the dashboard is. For example, maybe you want to save the exact filter configuration for a later session, or sync it with other parts of your app.

Superset currently supports two different ways to retrieve this information:

1. Listening to auto-emitted dataMask changes (PR #31331)
2. Using the getDataMask function on demand (PR #32997)

Let’s break down how each of these work and when you’d want to use them.

1. Auto-emitted dataMask changes

With this approach, the embedded dashboard SDK automatically emits events whenever the dataMask (aka the filter state) changes. This happens after any interaction — whenever a user applies a new filter, clears one, or changes a value.

First, you need to enable this flow in the SDK:

const myLightDashboard = presetSdk.embedDashboard({
  id: dashboardId,
  supersetDomain: supersetDomain,
  mountPoint: document.getElementById("dashboard-container"),
  fetchGuestToken: async () => fetchGuestTokenFromBackend(),
  dashboardUiConfig: {
    emitDataMasks: true, // Set it to true to emit filter state changes
  }
});

You can then subscribe to these updates using the observeDataMask method:

function processDataMaskChange(dataMaskConfig) {
  console.log("Received a data mask change from the dashboard:");
  console.log(dataMaskConfig);
}

myLightDashboard.then(dashboardElement => {
  dashboardElement.observeDataMask(processDataMaskChange);
});

The advantage here is that you get a real-time stream of every filter interaction. This is useful if you want to build something like live analytics of user behavior, or if you need to keep another part of your application perfectly in sync with the dashboard.

The downside is: it can get noisy. If the user is experimenting with filters (clicking around a lot), you’ll be getting a high frequency of events. You’ll need to decide whether that’s useful or if it creates unnecessary overhead.

2. Getting the filter state on demand with getDataMask

Sometimes, you don’t need every micro-interaction. Instead, you just want to know “what’s the current state of filters right now?”. That’s exactly what getDataMask provides.

const dataMask = await embeddedDashboard.getDataMask();
console.log("Current filter state:", dataMask);

This method is especially handy when you want to:

• Save the dashboard state at a certain point in time (e.g., when a user clicks “Save View”).
• Sync filter state across different dashboards, but only on explicit user actions.
• Use the state to generate a permalink or shareable link.

Can you send dataMask directly to the permalink API?

Yes! The dataMask object you retrieve (from either observeDataMask or getDataMask) is already in the correct format to be sent directly to Superset’s permalink API. You don’t need to massage or transform it — just pass it through.

This makes it super straightforward to implement “Save & Share” functionality in your application.

Which approach should you use?

• Use observeDataMask if you want continuous tracking of filter changes. It’s noisier, but great if your app needs to react in real time.
• Use getDataMask if you want a snapshot at a specific moment. This is the simpler option when building features like “Save current filters” or generating permalinks.

Wrapping up

By combining the ability to set filter state (from the previous blogpost) with these new methods to retrieve it, you now have full control of how your embedded dashboards interact with your application.

Whether you’re tracking every click or just saving a snapshot, Superset provides the building blocks to integrate dashboards seamlessly into your workflows.

All the features of Superset (and more) without the hassles of scaling/managing/upgrading, with plenty of time to grow into it. Free for five users, forever.