Is local! the intended mechanism for local-time D3 formatting?

[gianfranco-campana-vs]

I'm investigating timezone formatting in Apache Superset and would like to clarify the intended behavior of the D3 time formatter.

Superset officially uses UTC for timestamp handling, which I understand and am not questioning.

However, while investigating the frontend formatter used by the Table Chart, I found that Superset has an explicit mechanism to switch between UTC and local-time formatting.

For a temporal column, using this D3 format:

%H:%M

the Table Chart formats the timestamp in UTC.

Using:

local!%H:%M

the same timestamp is formatted using the browser/local timezone.

For example, with Europe/Rome during CEST:

%H:%M        → 10:30
local!%H:%M  → 12:30

I traced this behavior through the frontend code.

The relevant formatter logic recognizes the local! prefix and converts it into useLocalTime: true. The formatter construction then uses local formatting when useLocalTime is true and UTC formatting otherwise.

In other words, the code path appears to be explicitly designed to distinguish:

useLocalTime = false → utcFormat()
useLocalTime = true  → format()

and local! is the mechanism used by the formatter to request the latter.

What I cannot determine is the intended user-facing status of this mechanism.

In the Table Chart UI, the "D3 format" selector provides predefined formats such as:

%Y-%m-%d %H:%M:%S
%d-%m-%Y %H:%M:%S
%d.%m.%Y
%d/%m/%Y
%H:%M:%S
%Y-%m-%d
Adaptive formatting

but there is no indication that prefixing a format with local! changes the timezone behavior.

For example, there is no visible option such as:

local!%Y-%m-%d %H:%M:%S

I also could not find documentation explaining the local! prefix or how users are expected to request local-time D3 formatting.

This is particularly important for BI dashboards used in organizations operating outside UTC.

For users working in a local timezone, timestamps displayed in dashboards are not merely a formatting preference: they are part of the meaning of the data. A timestamp displayed two hours earlier or later can affect how users interpret events, sequences, durations, operational activity, and ultimately the business decisions based on the dashboard.

Therefore, the ability to explicitly request local-time rendering is an important aspect of making timestamp visualization usable in real-world BI scenarios, even when UTC remains the canonical timezone used internally by Superset.

My question is therefore:

Is local! the intended and supported mechanism for displaying D3-formatted timestamps in the user's local timezone?

If yes, is there a reason why this mechanism is not documented and/or exposed in the D3 format choices of the Table Chart?

I am particularly interested in understanding whether this is an established Superset feature, an undocumented feature, or functionality that is still under development.

I can provide the relevant frontend code path and a more detailed description of the debugging process if useful.

[dosubot[bot]]

Hi @gianfranco-campana-vs! I'm Dosu and I'm helping the Apache Superset team.

Your analysis is exactly correct, and local! is the intended mechanism for local-time D3 formatting — it's not a hack or accident. Here's what the code confirms:

It's an established, deliberate feature. LOCAL_PREFIX = 'local!' is a named exported constant in TimeFormats.ts. The TimeFormatterRegistry explicitly checks for this prefix on every format lookup — it calls targetFormat.startsWith(LOCAL_PREFIX) and strips the prefix before creating the formatter [1]. createD3TimeFormatter then uses the resulting useLocalTime flag to choose between D3's utcFormat and timeFormat [2]. The feature is even mentioned in the package's own README:

It is powered by a registry to support registration of custom formatting, with fallback to d3.utcFormat or d3.timeFormat (if the formatId starts with local!)

Why it's not exposed in the Table Chart UI. The Table Chart calls getTimeFormatter(timeFormat) with whatever string the user types or selects from the dropdown [3]. Because TimeFormatterRegistry.get() handles the local! prefix transparently, typing local!%H:%M manually in the D3 format field already works — the registry strips the prefix and routes to the local formatter. The predefined dropdown options simply don't include any local!-prefixed variants, and there's no UI hint that the prefix exists. This is a documentation/UX gap, not a code limitation.

Practical bottom line. You can use local!%Y-%m-%d %H:%M:%S (or any local!-prefixed D3 format string) today as a custom value in the Table Chart's D3 format field to get browser-local-time rendering. It will work reliably because the registry handles it natively.

If you'd like to see this improved, a documentation update explaining the local! prefix and/or adding local!-prefixed options to the Table Chart's format dropdown would be a straightforward and valuable contribution.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.