维度组

用量

视图：view_name {
dimension_group: field_name { ... }
}

层次结构 查看文件 view dimension_group

接受 Looker 标识符（用作维度组创建的每个维度名称的第一部分） 特殊规则 type 可以是 time 或 duration 通常与 timeframes 或 intervals 参数搭配使用 如果维度组不是基于日期时间字段，请使用 datatype 参数 对于 type: time 的维度组，如果您想阻止自动时区转换，请使用 convert_tz 参数

定义

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, …] # valid intervals described below
}

对于维度组 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 时间之间的时间差。只有 type: duration 的维度组支持 intervals 参数。

如果未添加 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 参数提供用于计算时间差的开始和结束信息。这些字段可以采用包含时间戳、日期时间、日期、纪元或 yyyymmdd 格式的任何有效 SQL 表达式。sql_start 和 sql_end 字段可以是以下任何一项：

• 对 type: time 中现有维度组的 raw 个时间范围的引用
• 对 type: date_raw 维度的引用
• 是一个时间戳的 SQL 表达式，例如对作为时间戳的 SQL 列的引用
• 从数据库中提取时间的 SQL 表达式，使用方言适当的表达式
• 使用 ::datetime 或 ::date 字段类型引用的 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 引用类型。通过合并 SQL 并引用 LookML 对象文档页面中介绍的 view_name.field_name::type 语法，您可以创建字段的 ::date 或 ::datetime 版本，而无需将对这些维度的引用转换为字符串。

例如，假设您有一个 created 维度组“type: time”，时间范围为 time、date、week、month 和 raw，定义如下：

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 引用类型，可将 created_month 和 created_time 维度视为生成的 SQL 中的时间戳。

例如，假设用户从字段选择器中选择“创建日期”和“月第一天”维度。如果为 Created Date 返回的值之一为 2019-03-10，则 Month 自第一天起的天数将为 9 天。

时间类型

type: time 与 dimension_group 和 timeframes 参数结合使用，来创建一组基于时间的维度。例如，您可以根据单个时间戳列轻松创建日期、周和月份维度。

type: time 维度组的形式为：

dimension_group: dimension_group_name {
  type: time
  timeframes: [timeframe, timeframe, …] # valid timeframes described below
  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 参数可以接受包含时间戳、日期时间、日期、纪元或 yyyymmdd 格式的任何有效 SQL 表达式。

• datatype 参数是可选的。如果您的维度组不是基于日期时间，则可以指定纪元、时间戳、日期或 yyyymmdd 格式。如需了解详情，请参阅本页面的指定数据库 datatype 部分。

• convert_tz 参数是可选参数，可让您阻止自动转换时区。本页的时区转化和convert_tz部分对此进行了更详细的说明。

此处并未一一列出它们，不过许多字段级参数也可以用于维度组。

例如，假设您有一个名为 created_at 的列，其中包含日期时间信息。您希望基于此日期时间创建日期、周和月维度。您可以使用：

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

在“探索”界面中，此操作会生成三个维度，分别名为创建日期、创建周和创建月份。请注意如何将 dimension_group 名称与生成维度名称的时间范围结合使用。

时间范围选项

只有 type: time 的维度组支持 timeframes 参数。对于维度组 type: duration，请改用 intervals 参数。

timeframes 参数用于告知维度组应生成哪些维度。以下是各个选项：

特殊时间范围

时间范围	说明	输出示例
raw	数据库中的原始值，未进行转换或时区转换。raw 只能在 LookML 内访问，不会显示在“探索”页面上。与返回格式化字符串的大多数其他时间范围不同，raw 时间范围会返回时间戳。它主要用于对字段执行日期操作。	2014-09-03 17:15:00 +0000
yesno	yesno 维度，如果日期时间有值，则返回“Yes”，否则返回“No”。与其他时间范围不同，当您从另一个字段引用 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	将每天拆分为具有指定小时数的间隔。有关说明，请参阅下文。	请参阅下文
minute	日期时间已被截断为最接近的分钟	2014-09-03 17:15
minuteX	按指定的分钟数拆分每小时的时间间隔。有关说明，请参阅下文。	请参阅下文
second	日期时间已被截断至最接近的秒数	2014-09-03 17:15:00
millisecond	日期时间已被截断至最接近的毫秒数（有关本页支持方言的信息，请参阅本页面中的对毫秒和微秒的方言支持部分）。	2014-09-03 17:15:00.000
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 中，以下方言支持毫秒：

在最新版本的 Looker 中，以下方言支持微秒：

指定数据库 datatype

借助 datatype 参数，您可以指定要提供给维度组的数据库表中的时间数据类型，从而提升查询性能。

对于维度组 type: time，datatype 参数适用于维度组的 sql 参数。

对于 type: duration 的维度组，datatype 参数会同时应用于 sql_start 和 sql_end 参数，因此请确保 sql_start 和 sql_end 都是指定的数据类型。

datatype 参数接受以下值：

• epoch：SQL 纪元字段（即表示与 Unix 纪元相隔的秒数的整数）。
• date：SQL 日期字段（即不包含时段信息的字段）。
• datetime：SQL 日期时间字段。
• 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 参数。

聊天团队提示：我们经常询问在具有多个 timeframe 的 dimension_group 上使用 primary_key 时发生的验证错误。如需了解详情，请参阅此社区主题。

包含时区信息的时间戳数据

某些数据库方言具有包含时区信息的时间戳选项。这样，您就可以将时间戳数据存储在一个可能具有多个时区的单个字段中。一行数据可能以世界协调时间 (UTC) 存储，而另一行时间以美国东部时间存储。例如，如需了解雪花方言时间戳选项，请参阅雪花 TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ 时间戳文档。

在这种情况下，当 Looker 执行时区转换时，可能会发生错误。为避免出现这种情况，您应在维度的 sql 参数中明确将时间戳数据转换为不执行时区转换的时间戳类型。例如，在 Snowflake 方言中，您可以使用 TO_TIMESTAMP 函数来转换时间戳数据。

您可以创建单个时间维度或时长维度

您可以为想要包含的每个时间范围或时长创建一个维度，而不是通过单个 dimension_group 生成所有维度。通常情况下，您可以避免创建单个维度，除非您想更改 Looker 的时间范围命名惯例，或者您已经在数据库中预先计算了时间列。如需了解详情，请参阅维度、过滤条件和参数类型文档页面。

您可以更改一周的第一天

默认情况下，Looker 中的周从星期一开始。您可以使用模型级别的 week_start_day 参数更改此设置。

请注意，week_start_day 不支持 week_of_year 时间范围，因为该时间范围基于 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 间隔遵循相同的逻辑。