dimension_group

用法

view: view_name {
  dimension_group:  field_name { ... }
}
层次结构
view
dimension_group
接受
一个 Looker 标识符（用作维度组创建的每个维度的名称的第一部分）

特殊规则

定义

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 字段可以是以下任意一项：

  • 对现有维度组中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 参考类型。view_name.field_name::type 语法（如纳入 SQL 并引用 LookML 对象文档页面中所述）可让您创建字段的 ::date 或 ::datetime 版本，而无需将对这些维度的引用转换为字符串。

例如，假设您有一个 type: time 的 created 维度组，其时间范围为 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 引用类型，可让系统在生成的 SQL 中将 created_month 和 created_time 维度视为时间戳。

例如，假设用户从字段选择器中选择了 Created Date 和 Days Since First of Month 维度。如果为创建日期返回的值之一是 2019-03-10，那么为自月初以来的天数返回的值将是 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 表达式，其中包含时间戳、日期时间、日期、纪元或 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 相应 datetime 中从周一开始的周的日期 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 基础 datetime 的年份和季度 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 底层 datetime 的整数年份 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 纪元字段（即一个整数，表示自 Unix 纪元以来的秒数）。
  • date：SQL 日期字段（即不包含一天中的时间信息的字段）。
  • datetime：SQL 日期时间字段。
  • timestamp：SQL 时间戳字段。
  • yyyymmdd：包含表示日期（格式为 YYYYMMDD）的整数的 SQL 字段。

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，则可能会出现此错误。如需了解详情，请参阅 Looker 社区帖子时间范围和维度组 。

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

某些数据库方言具有包含时区信息的时间戳选项。这样一来，您就可以将可能包含多个时区的时间戳数据存储在一个字段中。一行数据可能以 UTC 格式存储，另一行数据可能以美国东部时间格式存储。例如，如需了解 Snowflake 方言时间戳选项，请参阅 Snowflake 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 标准，而 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 区间遵循相同的逻辑。