Show how old a dashboard's source data is ("Data as of"), configured per dataset

[Brian-Kariu]

Motivation

Superset tells users when a query last ran ("Cached 5 minutes ago", and "Last queried at" from #36934). It doesn't tell them how old the data behind the query is. Most of our dashboards read warehouse tables that a pipeline rebuilds every hour or two, so a chart queried two minutes ago can still show data from six hours ago. Users can't tell the two apart, and "is this up to date?" is the question we get most often.

Most teams already know the answer, because their pipeline records it: a _loaded_at column on each table, a run log, or dbt source freshness. What's missing is a place in Superset to say where that timestamp lives, and somewhere to show it.

Proposal

Make the timestamp a dataset setting, roll it up to the dashboard, and show it beside the existing cache-age text.

1. Global config (superset_config.py)

FEATURE_FLAGS = {
    "DATA_FRESHNESS": True,  # off by default
}

# How long a freshness answer is cached, in seconds.
DATA_FRESHNESS_CACHE_TIMEOUT = 900

# Zone used to display the timestamp. None means the viewer's browser zone.
DATA_FRESHNESS_DISPLAY_TIMEZONE = None  # e.g. "Africa/Nairobi"

2. Dataset setting (Edit dataset → Settings), stored in the dataset's extra JSON

This follows the same pattern as certification and warning_markdown. Each dataset gets one of two options:

{
  "freshness": {
    "column": "_loaded_at",
    "warn_after_minutes": 120
  }
}

or, when the timestamp lives somewhere else:

{
  "freshness": {
    "sql": "SELECT MAX(loaded_at) FROM analytics.table_freshness WHERE table_name = 'sales.invoices'",
    "warn_after_minutes": 120
  }
}

• column → Superset runs SELECT MAX(<column>) on the dataset.
• sql → Superset runs the query on the dataset's database and expects a single timestamp back. Jinja is allowed, as in other dataset SQL.
• warn_after_minutes is optional. Once the data is older than this, the label switches to a warning style, the same idea as dbt's warn_after.

3. Dashboard setting (Dashboard properties), stored in json_metadata

{
  "show_data_freshness": true
}

The dashboard's "data as of" is the oldest freshness value across the datasets its charts use. A dashboard is only as current as its stalest input. Datasets with no freshness setting are skipped.

4. UI

• Dashboard header: "Data as of 19:28, 29 Oct". The tooltip lists each dataset and its own time. It turns to a warning style if any dataset has passed its warn_after_minutes.
• Chart menu: a "Data as of …" line next to the existing "Cached … ago".
• No answer: if the freshness query fails or returns nothing, the label is hidden, not shown as an error.

5. API and embedded SDK

• GET /api/v1/dashboard/<id_or_slug>/freshness returns:

  {
    "data_as_of": "2026-10-29T16:28:00Z",
    "datasets": [
      { "id": 12, "name": "invoices", "data_as_of": "2026-10-29T16:28:00Z", "stale": false }
    ]
  }

• Embedded SDK: dashboardUiConfig: { showDataFreshness: true }, so host apps can turn the header label on or off like hideTitle.

• The same endpoint lets a host app read the value and show it in its own layout.

Example

Our pipeline writes one row per warehouse table into a freshness table: the table name and the time of the newest source data it holds. With this proposal, we would set freshness.sql once on each dataset, pointing at its row. Every dashboard built on those datasets would then show the right "data as of" with no per-dashboard work, including dashboards added later.

Alternatives considered

• A Big Number or Handlebars chart on each dashboard that reads the freshness table. It works, but it's one chart per dashboard, built by hand, and it sits in the grid instead of the header. With guest tokens, an RLS rule that has no dataset also gets applied to the freshness table, so the chart fails for those users.
• Showing it in the host app around an embedded dashboard. That works for embedded users only. Anyone opening Superset directly doesn't see it.
• Injecting it into the header with custom JS. It would break on upgrades.
• "Last queried at" (feat: Chart query last run timestamp #36934). That one complements this proposal. It answers "when did Superset last run this?"; this one answers "how old is the data?"

Open questions

• Row-level security: should freshness queries run with the user's RLS rules? The result is a single timestamp, not rows, but a custom sql query could still read data the user can't. Running it with RLS is the safe default. The cost is that a guest RLS rule with no dataset (see above) would break it, so those rules may need to skip freshness queries.
• Caching: should the cache be per dataset, or per dataset plus RLS context?
• Virtual datasets: should these be able to inherit freshness from the physical tables they read?

I'm happy to help with a SIP or a PR if there's interest.

[sfirke]

When I've had a similar need I use a workaround: a Handlebars chart that queries the max of the desired column and shows it as text. I like your proposal!

To answer your questions from Slack, I don't think there's a way to do this currently, and I think this is a good candidate for a SIP. Maybe try taking it to a Superset Townhall meeting, or SIP office hours, if those work for your timezone + schedule.

You have it as a Feature Flag above; I think it would be more appropriate as a config flag (see the recent discussion at #44512), we are trying to move away from feature flags as the default, they are more for features that are still being refined over several releases.