mirror of
https://github.com/apache/superset.git
synced 2026-05-22 00:05:15 +00:00
04451766e7
Previously docusaurus.config.ts had `onBrokenLinks: 'warn'`, so broken
internal links produced advisory warnings during build but didn't gate
merges. Tightening to `throw` surfaces every broken internal route at
build time. Three classes of issue fell out:
1. Stale `/docs/...` and `/docs/6.0.0/...` references in the 6.0.0
versioned snapshot. The user-facing docs section was renamed
`docs` → `user-docs` (routeBasePath) at some point after 6.0.0 was
cut, but the snapshot's links still pointed at the old prefix. The
live site redirects /docs/* → /user-docs/* at runtime, but
Docusaurus's onBrokenLinks checker doesn't honor redirects.
Bulk-rewrote /docs/* → /user-docs/* across the snapshot (and one
/docs/api → /developer-docs/api).
2. Bare-relative MDX links like `[Label](./mcp)` (no .md/.mdx
extension). Docusaurus renders an absolute href in SSR HTML, so
static crawlers see correct links — BUT React Router's `<Link>`
component on the client side resolves the bare path relative to
the current URL on click, so when the page URL has a trailing
slash (e.g. /extensions/overview/), `./mcp` becomes
/extensions/overview/mcp (404). This is exactly the broken-flow a
user reported on /developer-docs/extensions/overview/. Added the
`.md`/`.mdx` extension to all 44 such links across 17 files; this
makes Docusaurus resolve them to the canonical doc URL at the
<Link> level, so SPA navigation works regardless of trailing slash.
3. Miscellaneous content fixes:
- 4 `/configuration/feature-flags` references in 6.0.0 snapshot
pointed at a page that doesn't exist in that version (the
dedicated feature-flags page was added later). Repointed to the
`#feature-flags` anchor inside `configuring-superset.mdx`.
- 3 references to `superset-core/src/superset_core/rest_api/decorators.py`
in extensions docs were rendered as relative URLs, resolving to
/developer-docs/extensions/superset-core/... (404). Converted to
absolute GitHub URLs.
- 1 `/storybook/?path=...` link in extensions/components/index.mdx
pointed at a non-existent route. Repointed to the existing
`/developer-docs/testing/storybook` page that explains how to
run Storybook locally.
- 4 unclosed-paren markdown links in 6.0.0 installation-methods.mdx
(pre-existing source bugs).
Build now passes with `onBrokenLinks: 'throw'`. Note that
`onBrokenAnchors` is still `'warn'` (default); a separate effort
should tighten that and fix the surviving anchor warnings (currently
~60 instances of `/community#superset-community-calendar`).
51 lines
3.2 KiB
Plaintext
51 lines
3.2 KiB
Plaintext
---
|
|
title: Timezones
|
|
hide_title: true
|
|
sidebar_position: 6
|
|
version: 1
|
|
---
|
|
|
|
# Timezones
|
|
|
|
There are four distinct timezone components which relate to Apache Superset,
|
|
|
|
1. The timezone that the underlying data is encoded in.
|
|
2. The timezone of the database engine.
|
|
3. The timezone of the Apache Superset backend.
|
|
4. The timezone of the Apache Superset client.
|
|
|
|
where if a temporal field (`DATETIME`, `TIME`, `TIMESTAMP`, etc.) does not explicitly define a timezone it defaults to the underlying timezone of the component.
|
|
|
|
To help make the problem somewhat tractable—given that Apache Superset has no control on either how the data is ingested (1) or the timezone of the client (4)—from a consistency standpoint it is highly recommended that both (2) and (3) are configured to use the same timezone with a strong preference given to [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) to ensure temporal fields without an explicit timestamp are not incorrectly coerced into the wrong timezone. Actually Apache Superset currently has implicit assumptions that timestamps are in UTC and thus configuring (3) to a non-UTC timezone could be problematic.
|
|
|
|
To strive for data consistency (regardless of the timezone of the client) the Apache Superset backend tries to ensure that any timestamp sent to the client has an explicit (or semi-explicit as in the case with [Epoch time](https://en.wikipedia.org/wiki/Unix_time) which is always in reference to UTC) timezone encoded within.
|
|
|
|
The challenge however lies with the slew of [database engines](/user-docs/6.0.0/configuration/databases#installing-drivers-in-docker-images) which Apache Superset supports and various inconsistencies between their [Python Database API (DB-API)](https://www.python.org/dev/peps/pep-0249/) implementations combined with the fact that we use [Pandas](https://pandas.pydata.org/) to read SQL into a DataFrame prior to serializing to JSON. Regrettably Pandas ignores the DB-API [type_code](https://www.python.org/dev/peps/pep-0249/#type-objects) relying by default on the underlying Python type returned by the DB-API. Currently only a subset of the supported database engines work correctly with Pandas, i.e., ensuring timestamps without an explicit timestamp are serializd to JSON with the server timezone, thus guaranteeing the client will display timestamps in a consistent manner irrespective of the client's timezone.
|
|
|
|
For example the following is a comparison of MySQL and Presto,
|
|
|
|
```python
|
|
import pandas as pd
|
|
from sqlalchemy import create_engine
|
|
|
|
pd.read_sql_query(
|
|
sql="SELECT TIMESTAMP('2022-01-01 00:00:00') AS ts",
|
|
con=create_engine("mysql://root@localhost:3360"),
|
|
).to_json()
|
|
|
|
pd.read_sql_query(
|
|
sql="SELECT TIMESTAMP '2022-01-01 00:00:00' AS ts",
|
|
con=create_engine("presto://localhost:8080"),
|
|
).to_json()
|
|
```
|
|
|
|
which outputs `{"ts":{"0":1640995200000}}` (which infers the UTC timezone per the Epoch time definition) and `{"ts":{"0":"2022-01-01 00:00:00.000"}}` (without an explicit timezone) respectively and thus are treated differently in JavaScript:
|
|
|
|
```js
|
|
new Date(1640995200000)
|
|
> Sat Jan 01 2022 13:00:00 GMT+1300 (New Zealand Daylight Time)
|
|
|
|
new Date("2022-01-01 00:00:00.000")
|
|
> Sat Jan 01 2022 00:00:00 GMT+1300 (New Zealand Daylight Time)
|
|
```
|