Make local! time formatting discoverable and document its use in Table Chart #44006

Description

This is not a request to change Superset's UTC handling or default timezone behavior. The local! mechanism already works correctly. The request is to make this existing functionality discoverable and documented.

Superset provides an intentional mechanism to format timestamps using the browser's local timezone by prefixing a D3 time format with local!.

For example:

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

This works correctly in the Table Chart and produces the expected local-time representation.

However, this mechanism is currently difficult to discover for users because:

• local! is not mentioned or suggested in the Table Chart UI where the D3 time format is configured.
• The predefined time-format options do not expose local-time variants.
• The documentation does not appear to clearly explain that prefixing a D3 format with local! switches the formatter from UTC to browser-local time.
• The distinction between the default UTC formatting and explicitly requested local-time formatting is therefore not obvious from the user interface.

As a result, a user encountering a timestamp displayed in UTC has little indication that a supported local! prefix exists and may reasonably assume that the displayed value cannot be changed to local time.

Expected behavior

The UI and/or documentation should make the local! functionality discoverable.

For example, the documentation could explicitly state that:

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

uses UTC formatting, while:

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

uses the browser's local timezone.

Alternatively (or additionally), the Table Chart time-format selector could provide local-time variants or otherwise expose this option to the user.

Actual behavior

The Table Chart accepts local! formats and formats the timestamp correctly, but there is no obvious indication in the UI that this syntax is supported.

The only practical way to discover it is to already know the implementation detail or find it through the source code/community discussion.

Why this matters

Timezone representation is a common requirement for dashboards, especially when data is stored or processed in UTC but users need to interpret timestamps in their local timezone.

The current behavior is technically supported, but the feature is effectively undiscoverable.

This can lead users to:

• incorrectly conclude that Superset always displays timestamps in UTC;
• attempt unnecessary backend/database timezone transformations;
• add redundant timezone-converted columns to datasets;
• spend significant time troubleshooting what appears to be a timezone bug.

Making the existing functionality discoverable would avoid these workarounds without requiring a change to Superset's UTC-oriented internal behavior.

Technical details

The local! behavior is already implemented in Superset's frontend formatter logic.

The relevant implementation uses the LOCAL_PREFIX (local!) and switches the D3 formatter from d3.utcFormat to d3.timeFormat when the prefix is present.

The Table Chart passes the user-provided D3 format through the formatter registry, so a manually entered format such as:

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

works as expected.

This was also confirmed in the related Superset GitHub Discussion, where the implementation and intended behavior of local! were confirmed.

Suggested improvement

At minimum, I suggest documenting this explicitly in the time-format documentation and/or the Table Chart documentation.

For example:

Local timezone formatting

By default, D3 time formats are rendered using UTC. To render a timestamp using the browser's local timezone, prefix the D3 format string with local!.

Example:

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

This uses the browser's local timezone instead of UTC.

A further UX improvement would be to expose local-time formats directly in the Table Chart format selector, for example:

YYYY-MM-DD HH:mm:ss (UTC)
YYYY-MM-DD HH:mm:ss (Local)

or an equivalent mechanism that makes the distinction clear without requiring users to know the local! syntax.

Related discussion

This issue follows the discussion where the local! implementation and its intended behavior were confirmed:

[link to the related GitHub Discussion]

Environment

• Apache Superset: current development version / master
• Visualization: Table Chart
• Time formatter: D3
• Browser timezone: Europe/Rome (CEST during the test period)

Conclusion

This does not appear to be a functional bug in the formatter itself: the existing local! mechanism works correctly.

The issue is primarily one of discoverability, documentation, and UX: an intentional and useful feature exists, but users have little or no way of knowing that it exists or how to use it.