dimension_group

用量

view: view_name {
  dimension_group:  field_name { ... }
}
階層
view
dimension_group
接受
Looker ID (做為維度群組建立的每個維度名稱的第一部分)

特別規則

定義

dimension_group 參數可用於一次建立一組以時間或時間長度為準的維度。您定義維度群組後，維度群組會為不同間隔或時間範圍建立一組個別維度。舉例來說，您可以根據時間戳記資料欄指定 type: time 的維度群組，而維度群組會建立對應的維度，以時間、日期、週、小時、季和年表示資料。

維度群組的形式和功能會因維度群組的 type 值而異：

時間長度類型維度群組

type: duration 會與 dimension_group 搭配使用，計算一組以間隔為準的持續時間維度。

type: duration 的維度群組形式如下：

dimension_group: dimension_group_name {
  type: duration
  sql_start: SQL expression ;;  # often this is a single database column
  sql_end: SQL expression ;;  # often this is a single database column
  intervals: [interval, interval, …] # see following explanation for valid intervals
}

適用於 type: duration 的維度群組：

  • sql_start 和 sql_end 參數會提供 SQL 運算式，定義時間範圍的開始和結束時間。詳情請參閱本頁的「定義時間長度的開始和結束時間」一節。

  • intervals 參數可指定一或多個間隔單位，用來測量時間差。如需可選用的間隔，請參閱本頁面的「間隔選項」一節。

  • 系統會將時間長度值無條件捨去到最接近的整數。

  • datatype 參數為選用參數。如果維度群組不是以日期時間為準，您可以改為指定紀元、時間戳記、日期或 yyyymmdd 格式。如果是 type: duration 的維度群組，datatype 參數會同時套用至 sql_start 和 sql_end 參數，因此請務必確認 sql_start 和 sql_end 都是指定的資料類型。如需 datatype 參數的詳細說明，請參閱本頁的「指定資料庫 datatype」一節。

雖然這裡未列出，但許多欄位層級參數也可用於維度群組。

舉例來說，如果您有 enrollment_date 和 graduation_date 的資料欄，可以建立時間長度維度群組，查看學生在學校待了多久的時間，並以週和年為間隔計算：

dimension_group: enrolled {
  type: duration
  intervals: [week, year]
  sql_start: ${TABLE}.enrollment_date ;;
  sql_end: ${TABLE}.graduation_date ;;
}

在「探索」使用者介面中，這會產生名為「註冊時間長度」的維度群組，其中包含名為「註冊週數」和「註冊年數」的個別維度。

間歇選項

intervals 參數會告知維度群組，應使用哪些間隔單位來測量 sql_start 時間和 sql_end 時間之間的時間差。intervals 參數僅支援 type: duration 的維度群組。

如果未納入 intervals，維度群組會包含所有可能的間隔。

intervals 參數的選項如下：

時間間隔 說明 輸出範例
day 計算天數的時間差。 9 days
hour 以小時為單位計算時差。 171 hours
minute 計算以分鐘為單位的時差。 10305 minutes
month 計算以月為單位的時間差。 3 months
quarter 計算以季為單位的時間差。 2 quarters
second 計算時間差 (以秒為單位)。 606770 seconds
week 計算以週為單位的時差。 6 weeks
year 計算以年為單位的時間差。 2 years

定義時間長度的開始和結束時間

如果是 type: duration 維度群組，sql_start 和 sql_end 參數會提供用於計算時間差的開始和結束資訊。這些欄位可採用任何有效的 SQL 運算式，其中包含時間戳記、日期時間、日期、紀元或 yyyymmdd 格式的資料。sql_start 和 sql_end 欄位可以是下列任一項目：

  • 參照現有維度群組的 raw 時間範圍 type: time
  • type: date_raw 維度的參照
  • 時間戳記的 SQL 運算式，例如參照時間戳記的 SQL 欄
  • SQL 運算式，可從資料庫中提取時間，並使用適合方言的運算式
  • 使用 ::datetime 或 ::date field 類型參照的 LookML 欄位參照

舉例來說，假設您有名為 faa_event_date_raw 的維度，其中包含日期時間資訊：

dimension: faa_event_date_raw {
  type: date_raw
  sql: ${TABLE}.event_date ;;
}

您可以建立維度群組 type: duration，計算自 FAA 事件日期起經過的時間量。如要這麼做，您可以使用 faa_event_date_raw 維度做為計算的開始時間，然後使用方言的 SQL 運算式做為計算的結束時間。以下是 MySQL 資料庫的範例：

dimension_group: since_event {
  type: duration
  intervals: [hour, day]
  sql_start: ${faa_event_date_raw} ;;
  sql_end: CURRENT_TIMESTAMP();;
}

在「探索」使用者介面中，這會產生名為「事件發生後經過的時間」的維度群組，其中包含名為「事件發生後經過的小時數」和「事件發生後經過的天數」的個別維度。

參照其他 LookML 欄位的間隔

如要在 type: duration 的 dimension_group 中參照 interval 值，請使用 ${interval_fieldname} 語法，並使用 interval 值的複數版本。舉例來說，在下列 LookML 範例中，average_days_since_event 測量指標會使用 ${days_since_event} 參照 since_event 維度群組中的 day 間隔：


dimension_group: since_event {
  type: duration
  intervals: [hour, day, week, month, quarter, year]
  sql_start: ${faa_event_date_raw} ;;
  sql_end: CURRENT_TIMESTAMP();;
}

measure: average_days_since_event {
  type: average
  sql: ${days_since_event} ;;
}

搭配時間長度欄位使用 LookML 欄位類型參照

如要建立自訂時間長度欄位，可以為 type: duration 維度群組的 sql_start 和 sql_end 參數中參照的維度指定 ::date 或 ::datetime 參照類型。view_name.field_name::type 語法 (請參閱「併入 SQL 並參照 LookML 物件」說明文件頁面) 可讓您建立欄位的 ::date 或 ::datetime 版本，而不必將這些維度的參照轉換為字串。

舉例來說，假設您有 created 維度群組，其中包含 time、date、week、month 和 raw 的時間範圍，定義如下：type: time


dimension_group: created {
  type: time
  timeframes: [time, date, week, month, raw]
  sql: ${TABLE}.created_at ;;
}

使用 created_month 和 created_time 維度，您可以建立 type: duration 維度群組，計算 created_date 欄位中的日期與該日期所在月份的第一天之間的時間長度 (以週、天和小時為單位)：


dimension_group: since_first_of_month {
  type: duration
  intervals: [week, day, hour]
  sql_start: ${created_month::datetime} ;;
  sql_end: ${created_time::datetime} ;;
}

在探索使用者介面中，這會建立名為「本月首日至今的時間長度」的維度群組，其中包含「本月首日至今的週數」、「本月首日至今的天數」和「本月首日至今的小時數」等個別維度。為 sql_start 和 sql_end 參數中參照的欄位指定 ::datetime 參照類型，可讓系統在產生的 SQL 中將 created_month 和 created_time 維度視為時間戳記。

舉例來說，假設使用者從欄位挑選器選取「建立日期」和「自月初起的天數」維度，如果「建立日期」傳回的值為「2019-03-10」，則「自當月 1 日起的天數」傳回的值為「9 天」。

時間類型維度群組

type: time 會與 dimension_group 和 timeframes 參數搭配使用，建立一組以時間為準的維度。舉例來說，您可以根據單一時間戳記欄，輕鬆建立日期、週和月份維度。

type: time 的維度群組形式如下：

dimension_group: dimension_group_name {
  type: time
  timeframes: [timeframe, timeframe, …] # see following explanation for valid timeframes
  sql: SQL expression ;;  # often this is a single database column
  datatype: epoch| timestamp | datetime | date | yyyymmdd # defaults to datetime
  convert_tz: yes | no   # defaults to yes
}

適用於 type: time 的維度群組：

  • timeframes 參數為選用參數，但很少會省略。這個屬性會指定維度群組應產生的一或多個時間範圍。如果未加入 timeframes，系統會將每個時間範圍選項新增至維度群組。如需可選用的時間範圍，請參閱本頁面的「時間範圍選項」一節。

  • type: time 維度群組的 sql 參數可採用任何有效的 SQL 運算式，其中包含 timestamp、datetime、date、epoch 或 yyyymmdd 格式的資料。

  • datatype 參數為選用參數。如果維度群組不是以日期時間為準，您可以改為指定紀元、時間戳記、日期或 yyyymmdd 格式。如需更多詳細資料，請參閱本頁的「指定資料庫 datatype」一節。

  • convert_tz 參數為選用項目，可防止系統自動轉換時區。詳情請參閱本頁的「時區轉換和 convert_tz」一節。

雖然這裡未列出，但許多欄位層級參數也可用於維度群組。

舉例來說，假設您有名為 created_at 的資料欄，其中包含日期時間資訊。您想根據這個日期時間建立日期、週別和月份維度。此時便可使用：

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

在「探索」使用者介面中，這會產生三個維度，名稱分別為「建立日期」、「建立週」和「建立月份」。請注意，dimension_group 名稱會與時間範圍合併，產生維度名稱。

時間範圍選項

timeframes 參數僅支援 type: time 維度群組。如為 type: duration 的維度群組，請改用 intervals 參數。

timeframes 參數會告知維度群組應產生哪些維度，並包含下列選項：

特殊時間範圍

時間範圍 說明 輸出範例
raw 資料庫中的原始值，未經過轉換或時區轉換。raw 只能在 LookML 中存取，不會顯示在「探索」頁面。raw 時間範圍會傳回時間戳記，不像其他時間範圍會傳回格式化字串。主要用於對欄位執行日期作業。 2014-09-03 17:15:00 +0000
yesno yesno 維度，如果日期時間有值，則傳回「是」，否則傳回「否」。與其他時間範圍不同，從其他欄位參照yesno時間範圍維度時，請勿在參照中加入時間範圍。舉例來說，如要參照 dimension_group: created 中的 yesno 時間範圍，請使用 ${created} 語法，而非 ${created_yesno}。 Yes

時間範圍

時間範圍 說明 輸出範例
time 基礎欄位的日期時間 (部分 SQL 方言會顯示資料庫所含的精確度，其他方言則只會顯示到秒) 2014-09-03 17:15:00
time_of_day 時段 17:15
hour 日期時間截斷至最接近的小時 2014-09-03 17
hour_of_day 基礎欄位的小時整數值 17
hourX 將每天分成指定時數的間隔。 請參閱「使用 hourX」。
minute 日期時間截斷至最接近的分鐘 2014-09-03 17:15
minuteX 將每小時分成指定分鐘數的間隔。 請參閱「使用 minuteX」。
second 日期時間 (四捨五入至最接近的秒數) 2014-09-03 17:15:00
millisecond 日期時間截斷至最接近的毫秒 (如需方言支援的相關資訊，請參閱本頁的「方言支援毫秒和微秒」一節)。 2014-09-03 17:15:00.000
millisecondX 將每秒分割為指定毫秒數的時間間隔 (如需方言支援的相關資訊，請參閱本頁的「毫秒和微秒的方言支援」一節)。 請參閱「使用 millisecondX」。
microsecond 日期時間會截斷至最接近的微秒 (如需方言支援的資訊，請參閱本頁的「方言支援的毫秒和微秒」一節)。 2014-09-03 17:15:00.000000

日期時間範圍

時間範圍 說明 輸出範例
date 基礎欄位的日期 2017-09-03

每週時間範圍

時間範圍 說明 輸出範例
week 以基礎日期時間的星期一為一週的開始日期 2017-09-01
day_of_week 僅限星期幾 Wednesday
day_of_week_index 星期幾索引 (0 = 星期一，6 = 星期日) 2

月時間範圍

時間範圍 說明 輸出範例
month 基礎日期時間的年和月 2014-09
month_num 基礎日期時間的月份整數 9
fiscal_month_num 基礎日期時間的會計月份整數 6
month_name 月份名稱 September
day_of_month 當月第幾日 3

如要使用 fiscal_month_num 時間範圍，必須在模型中設定 fiscal_month_offset 參數。

季時間範圍

時間範圍 說明 輸出範例
quarter 基礎日期時間的年份和季度 2017-Q3
fiscal_quarter 基礎日期時間的會計年度和季度 2017-Q3
quarter_of_year 年份季度，以「Q」開頭 Q3
fiscal_quarter_of_year 會計年度的季度，前面加上「Q」 Q3

如要使用 fiscal_quarter 和 fiscal_quarter_of_year 時間範圍，必須在模型中設定 fiscal_month_offset 參數。

年度時間範圍

時間範圍 說明 輸出範例
year 基礎日期時間的整數年份 2017
fiscal_year 基礎日期時間的整數會計年度 FY2017
day_of_year 一年中的第幾天 143
week_of_year 以數字表示的週次 17

如要使用 fiscal_year 時間範圍，必須在模型中設定 fiscal_month_offset 參數。

正在使用 hourX

在 hourX 中，X 會替換為 2、3、4、6、8 或 12。

這會將每天分成指定時數的間隔。舉例來說，hour6 會將每天分成 6 小時的區段，顯示方式如下：

  • 2014-09-01 00:00:00
  • 2014-09-01 06:00:00
  • 2014-09-01 12:00:00
  • 2014-09-01 18:00:00

舉例來說，如果資料列的 time 為 2014-09-01 08:03:17，則 hour6 為 2014-09-01 06:00:00。

正在使用 minuteX

在 minuteX 中，X 會替換為 2、3、4、5、6、10、12、15、20 或 30。

這會將每小時劃分為指定分鐘數的間隔。舉例來說，minute15 會將每小時劃分為 15 分鐘的區段，顯示方式如下：

  • 2014-09-01 01:00:00
  • 2014-09-01 01:15:00
  • 2014-09-01 01:30:00
  • 2014-09-01 01:45:00

舉例來說，如果資料列的 time 為 2014-09-01 01:17:35，則 minute15 為 2014-09-01 01:15:00。

正在使用 millisecondX

在 millisecondX 中，X 會替換為 2、4、5、8、10、20、25、40、50、100、125、200、250 或 500。

這會將每秒分割成間隔，間隔長度為指定的毫秒數。舉例來說，millisecond250 會將每秒分割為 250 毫秒的片段，如下所示：

  • 2014-09-01 01:00:00.000
  • 2014-09-01 01:00:00.250
  • 2014-09-01 01:00:00.500
  • 2014-09-01 01:00:00.750

舉例來說，如果資料列的 time 為 2014-09-01 01:00:00.333，則 millisecond250 為 2014-09-01 01:00:00.250。

時區轉換和 convert_tz

一般來說，只有在所有時間值都轉換為相同時區時，時間計算 (差異、時間長度等) 才能正確運作，因此撰寫 LookML 時請務必留意時區。

Looker 提供多種時區設定，可在不同時區之間轉換時間資料。Looker 預設會轉換時區。type: time 維度群組支援 convert_tz 參數。如果您不希望 Looker 對特定維度或維度群組執行時區轉換，可以使用 convert_tz 參數說明頁面所述的 convert_tz 參數。

支援毫秒和微秒的方言

Looker 支援精確度達微秒的時間範圍，但部分資料庫僅支援精確度達秒的時間範圍。如果資料庫遇到的時間範圍比支援的範圍更精確，系統會將時間範圍向上取整至秒。

在最新版 Looker 中，下列方言支援毫秒：

方言 是否支援？
Actian Avalanche
Amazon Athena
Amazon Aurora MySQL
Amazon Redshift
Amazon Redshift 2.1+
Amazon Redshift Serverless 2.1+
Apache Druid
Apache Druid 0.13+
Apache Druid 0.18+
Apache Hive 2.3+
Apache Hive 3.1.2+
Apache Spark 3+
ClickHouse
Cloudera Impala 3.1+
Cloudera Impala 3.1+ with Native Driver
Cloudera Impala with Native Driver
DataVirtuality
Databricks
Denodo 7
Denodo 8 & 9
Dremio
Dremio 11+
Exasol
Google BigQuery Legacy SQL
Google BigQuery Standard SQL
Google Cloud PostgreSQL
Google Cloud SQL
Google Spanner
Greenplum
HyperSQL
IBM Netezza
MariaDB
Microsoft Azure PostgreSQL
Microsoft Azure SQL Database
Microsoft Azure Synapse Analytics
Microsoft SQL Server 2008+
Microsoft SQL Server 2012+
Microsoft SQL Server 2016
Microsoft SQL Server 2017+
MongoBI
MySQL
MySQL 8.0.12+
Oracle
Oracle ADWC
PostgreSQL 9.5+
PostgreSQL pre-9.5
PrestoDB
PrestoSQL
SAP HANA
SAP HANA 2+
SingleStore
SingleStore 7+
Snowflake
Teradata
Trino
Vector
Vertica

在最新版 Looker 中，下列方言支援微秒：

方言 是否支援？
Actian Avalanche
Amazon Athena
Amazon Aurora MySQL
Amazon Redshift
Amazon Redshift 2.1+
Amazon Redshift Serverless 2.1+
Apache Druid
Apache Druid 0.13+
Apache Druid 0.18+
Apache Hive 2.3+
Apache Hive 3.1.2+
Apache Spark 3+
ClickHouse
Cloudera Impala 3.1+
Cloudera Impala 3.1+ with Native Driver
Cloudera Impala with Native Driver
DataVirtuality
Databricks
Denodo 7
Denodo 8 & 9
Dremio
Dremio 11+
Exasol
Google BigQuery Legacy SQL
Google BigQuery Standard SQL
Google Cloud PostgreSQL
Google Cloud SQL
Google Spanner
Greenplum
HyperSQL
IBM Netezza
MariaDB
Microsoft Azure PostgreSQL
Microsoft Azure SQL Database
Microsoft Azure Synapse Analytics
Microsoft SQL Server 2008+
Microsoft SQL Server 2012+
Microsoft SQL Server 2016
Microsoft SQL Server 2017+
MongoBI
MySQL
MySQL 8.0.12+
Oracle
Oracle ADWC
PostgreSQL 9.5+
PostgreSQL pre-9.5
PrestoDB
PrestoSQL
SAP HANA
SAP HANA 2+
SingleStore
SingleStore 7+
Snowflake
Teradata
Trino
Vector
Vertica

指定資料庫 datatype

datatype 參數可讓您指定資料庫表格中提供給維度群組的時間資料類型，進而提升查詢效能。

如果是 type: time 的維度群組，datatype 參數會套用至維度群組的 sql 參數。

如果是 type: duration 的維度群組，datatype 參數會同時套用至 sql_start 和 sql_end 參數，因此請務必確認 sql_start 和 sql_end 都是指定的資料類型。

datatype 參數接受下列值：

  • epoch：SQL Epoch 欄位 (即代表從 Unix Epoch 紀元時間起算的秒數的整數)。
  • date：SQL 日期欄位 (即不含時間資訊的欄位)。
  • datetime：SQL datetime 欄位。
  • timestamp：SQL 時間戳記欄位。
  • yyyymmdd：SQL 欄位，內含代表 YYYYMMDD 格式日期的整數。

datatype 的預設值為 timestamp。

範例

假設您有名為 created_at 的資料欄，其中包含日期時間資訊。您想根據這個日期時間建立日期、週別和月份維度。此時便可使用：

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

-

在「探索」使用者介面中，這會產生三個維度，名稱分別為「建立日期」、「建立週」和「建立月份」。請注意，dimension_group 名稱會與時間範圍合併，產生維度名稱。

注意事項

維度群組必須由個別維度參照

由於維度群組代表一組維度，而非單一維度，因此您無法在 LookML 中直接參照維度群組。您必須改為參照該維度。

舉例來說，假設維度群組如下：

dimension_group: created {
  type: time
  timeframes: [date, week, month]
  sql: ${TABLE}.created_at ;;
}

如要在其他 LookML 欄位中參照這些維度，請使用 ${created_date}、${created_week} 或 ${created_month} 參照。如果您只嘗試使用 ${created}，Looker 不會知道您指的是哪個時間範圍，因此會產生錯誤。

基於同樣的理由，如果您指定多個 timeframe，就不應在維度群組中使用 primary_key 參數。

即時通訊團隊提示：如果使用 primary_key 的 dimension_group 具有多個 timeframe，您可能會遇到驗證錯誤，我們經常收到這類問題。詳情請參閱 Looker 中的時間範圍和維度群組 社群貼文。

包含時區資訊的時間戳記資料

部分資料庫方言提供包含時區資訊的時間戳記選項。這樣一來，您就能將時間戳記資料儲存在可能有多個時區的單一欄位中。一列資料可能以世界標準時間儲存，另一列則以美東時間儲存。如需範例，請參閱 Snowflake TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ 時間戳記說明文件，瞭解 Snowflake 方言的時間戳記選項。

在這種情況下，Looker 執行時區轉換時可能會發生錯誤。為避免這種情況，您應在維度的 sql 參數中，將時間戳記資料明確轉換為不會進行時區轉換的時間戳記類型。舉例來說，在 Snowflake 方言中，您可以使用 TO_TIMESTAMP 函式轉換時間戳記資料。

您可以建立個別的時間或時長維度

您可以為要納入的每個時間範圍或時間長度建立一個維度，而不是在單一 dimension_group 中產生所有維度。一般來說，除非您想變更 Looker 的時間範圍命名慣例，或資料庫中已有預先計算的時間資料欄，否則可以避免建立個別維度。詳情請參閱「維度、篩選器和參數類型」說明文件頁面。

你可以變更一週的第一天

根據預設，Looker 中的週會從星期一開始。您可以在模型層級使用 week_start_day 參數變更這項設定。

請注意，week_start_day 不適用於 week_of_year 時間範圍，因為該時間範圍是以 ISO 標準為準，而 ISO 標準是以星期一為一週的起始日。

自訂篩選器和自訂欄位不支援所有時間範圍

時間範圍 day_of_week、fiscal_quarter_of_year、millisecond、millisecondX、microsecond、month_name、quarter_of_year 和 time_of_day 不支援自訂篩選器或自訂欄位。

以月、季和年為間隔時，系統只會計算完整週期

在 duration 維度群組中，只有當結束日期大於或等於開始日期時，month 間隔才會將該月視為已過。例如：

  • 同年 9 月 26 日和 10 月 25 日的月份差異為 0。
  • 同年 9 月 26 日和 10 月 26 日的月份差異為 1。

quarter 和 year 間隔採用相同的邏輯。