GitHub user gianfranco-campana-vs created a discussion: Make local! time formatting discoverable and document its use in Table Chart
## 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: ```text 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: ```text %Y-%m-%d %H:%M:%S ``` uses UTC formatting, while: ```text 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: ```text 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: ```text 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]](https://github.com/apache/superset/discussions/43551?utm_source=chatgpt.com) ## 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. GitHub link: https://github.com/apache/superset/discussions/44006 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
