ConvertTimezone

convertTimezone 透過從時間戳記中加入或減去正確的間隔，將時間戳記移至指定的時區。

時間戳記和時區處理起來相當棘手（很容易犯錯，而且難以察覺），因此只有在資料的解讀對基於時間的截止點很敏感時，才應嘗試使用 convertTimezone。

例如，如果您正在追蹤使用者隨時間的登入次數，如果某些登入次數被計算在星期一而不是星期二，您的業務可能不會有不同的運作方式。但是，如果您使用 Metabase 來進行精確的事情，例如報稅，您（和政府）可能會更關心 12 月 31 日與 1 月 1 日發生的交易之間的差異。

支援的時區

Metabase 支援 tz 資料庫時區。

參數

column 可以是下列任一項

• 時間戳記欄位的名稱、
• 傳回 時間戳記 的自訂表達式，或
• 字串格式 "YYYY-MM-DD 或 "YYYY-MM-DDTHH:MM:SS"。

目標:

• 您想要指派給欄位的時區名稱。

來源:

• 欄位目前時區的名稱。
• 針對資料類型為 timestamp without time zone 的欄位或表達式為必要項目。
• 針對資料類型為 timestamp with time zone 的欄位或表達式為選用項目。
• 如需更多資訊，請參閱 接受的資料類型。

我們支援 tz 資料庫 時區名稱（例如 “Canada/Eastern” 而不是 “EST”）。

建立自訂報表日期

假設您有一些時間序列資料儲存在一個或多個時區中（**來源時間**）。您想要為位於 EST 的團隊建立自訂報表日期。

如果 **來源時間** 儲存為 timestamp with time zone 或 timestamp with offset，您只需要提供 target 時區

convertTimezone([Source Time], 'EST')

如果 **來源時間** 儲存為 timestamp without time zone，您*必須*提供 source 時區（這將取決於您的資料庫時區）

convertTimezone([Source Time], 'EST', 'UTC')

通常最好使用目標時區的名稱標記 convertTimezone 欄位（或將目標時區新增至模型的元數據）。我們保證當有人不可避免地詢問為什麼數字不符時，這會讓您的生活更輕鬆。

如果您沒有獲得預期的結果

• 檢查您是否使用了正確的 來源時區。
• 向您的資料庫管理員詢問 timestamp with time zone 與 timestamp without time zone 的差異（如需更多資訊，請參閱 接受的資料類型）。

選擇來源時區

當您進行時區轉換時，請確保您知道您正在使用的來源時區。同一個表格、問題或模型中的不同欄位（甚至不同列）可能位於不同的「來源」時區。

例如，假設您有一個表格，每位造訪您網站的人都有一列。光看 2022 年 12 月 28 日，下午 12:00，很難判斷「原始」時間戳記是否為

• 使用您的資料庫時區（通常為 UTC）儲存、
• 在沒有時區元數據的情況下儲存（例如，如果網站訪客位於 HKT，則時間戳記 2022 年 12 月 28 日，下午 12:00 可能「隱含地」使用香港時間）、
• 在您的 Metabase 報表時區中*顯示*。

如需更多血淋淋的細節，請參閱 限制。

接受的資料類型

我們使用「時間戳記」和「日期時間」來談論 Metabase 支援的任何時間資料類型。

如果您的時間戳記在資料庫中儲存為字串或數字，管理員可以從「表格元數據」頁面將它們轉換為時間戳記。

為了使用 convertTimezone 而不會遇到錯誤或惱人的無法偵測的錯誤，您應該知道有幾種 timestamp 資料類型

請注意，時間戳記的第一部分是 UTC（與 GMT 相同）。時區或偏移量會告訴您對於給定的時區要加入或減去多少時間。

convertTimezone 將適用於所有三種時間戳記類型，但 convertTimezone 的輸出將始終是不具時區的 timestamp。

限制

convertTimezone 目前不適用於下列資料庫

• 亞馬遜雅典娜
• Databricks
• Druid
• MongoDB
• Presto
• SparkSQL
• SQLite
• Metabase 範例資料庫

關於來源時區的注意事項

Metabase 顯示不具時區或偏移量資訊的時間戳記，這就是為什麼在使用 convertTimezone 時，您必須非常小心 來源時區。

Metabase 報表時區僅適用於 timestamp with time zone 或 timestamp with offset 資料類型。例如

Metabase 報表時區將不適用於 convertTimezone 表達式的輸出。例如

convertTimezone("2022-12-28T12:00:00 AT TIME ZONE 'Canada/Central'", "Canada/Pacific", "Canada/Central")

將產生原始的 timestamp without time zone

2022-12-28T04:00:00

並在 Metabase 中顯示為

Dec 28, 2022, 4:00 AM

如果您在不具時區的 timestamp 上使用 convertTimezone，請確保使用 ‘UTC’ 作為 source 時區，否則表達式會將您的時間戳記移動錯誤的量。例如，如果我們的不具時區的 timestamp 僅「隱含地」位於 CST 中，我們應該使用 ‘UTC’ 作為 source 參數，以獲得與上述相同的結果。

例如，如果我們選擇 ‘CST’ 作為不具時區的 timestamp 的 source 時區

convertTimezone("2022-12-28T12:00:00", "Canada/Pacific", "Canada/Central")

我們將獲得原始的 timestamp without time zone

2022-12-28T10:00:00

在 Metabase 中顯示為

Dec 28, 2022, 10:00 AM

相關函數

本節涵蓋與 Metabase convertTimezone 表達式運作方式相同的函數和公式，並附註如何為您的使用案例選擇最佳選項。

• SQL
• 試算表
• Python

SQL

當您使用查詢產生器執行問題時，Metabase 會將您的圖形化查詢設定（篩選條件、摘要等）轉換為查詢，並針對您的資料庫執行該查詢以取得結果。

如果我們的時間戳記範例資料是儲存在 PostgreSQL 資料庫中的 timestamp without time zone

SELECT source_time::TIMESTAMP AT TIME ZONE 'UTC' AT TIME ZONE 'EST' AS team_report_time_est

與 convertTimezone 表達式相同，其中 source 參數設定為 ‘UTC’

convertTimezone([Source Time], "Canada/Eastern", "UTC")

如果 source_time 是 timestamp with time zone 或 timestamp with offset（例如，在 Snowflake 資料庫中），則我們不需要在 SQL 或 Metabase 中指定來源時區。

SELECT convert_timezone('America/Toronto', source_time) AS team_report_time_est

與下列項目相同

convertTimezone([Source Time], "Canada/Eastern")

請記住，時區名稱取決於您的資料庫。例如，Snowflake 不接受大多數時區縮寫（例如 EST）。

試算表

如果我們的時間戳記範例資料在試算表中，「來源時間」位於 A 欄，我們可以透過明確減去小時數來將其變更為 EST

A1 - TIME(5, 0, 0)

以獲得與下列項目相同的結果

convertTimezone([Client Time], "Canada/Eastern")

Python

如果時間戳記範例資料儲存在 pandas 資料框架中，您可以先將 **來源時間** 欄位轉換為具有時區的 timestamp 物件（基本上是將 timestamp without time zone 轉換為 timestamp with time zone），然後使用 tz_convert 將時區變更為 EST

df['Source Time (UTC)'] = pd.to_timestamp(df['Source Time'], utc=True)
df['Team Report Time (EST)'] = df['Source Time (UTC)'].dt.tz_convert(tz='Canada/Eastern')

以執行與巢狀 convertTimezone 表達式相同的事情

convertTimezone(convertTimezone([Source Time], "UTC"), "Canada/Eastern", "UTC")

延伸閱讀

• 自訂表達式文件
• 自訂表達式教學課程
• 時間序列分析