在 Looker 中使用自定义日历

对于支持此功能的方言,Looker 中的自定义日历功能可让您在数据库中定义自定义日历(例如特定的财政或零售日历),然后将该日历应用于 LookML 模型中基于日期的维度组。然后,您的用户就可以使用自定义时间范围(例如 custom_weekcustom_period)创建探索查询,就像使用标准时间范围一样。

前提条件

在使用自定义日历之前,请确保满足以下前提条件:

创建自定义日历

如需实现自定义日历,您需要执行以下常规步骤(在以下各部分中介绍):

  1. 在数据库中创建日历表
  2. 在 LookML 中定义自定义日历视图
  3. 创建自定义日历维度组

在数据库中创建日历表

为了计算自定义日历的日期,Looker 需要数据库中有一个专用日历表来定义自定义时间范围。您的表格必须包含一个使用标准日历日期的参考日期列。Looker 会根据参考日期列将您的日历表与数据表(例如 orders 表)联接起来。

日历表中的列名称是灵活的。在 LookML 中定义自定义日历视图时,您将使用 calendar_definition 组成块将数据库中的列映射到标准自定义时段名称。

以下是名为 fiscal_calendar_table 的日历表的示例表架构。

列名 数据类型 说明
reference_date DATE 标准日历日期(例如“2023-01-01”)。用于加入。应为唯一键或主键。
fiscal_year VARCHAR 相应财年(例如“FY2023”)。
fiscal_year_num INTEGER 数字形式的财政年度(例如 2023 年)。
fiscal_quarter_of_year VARCHAR 财季(例如“FQ1”)。
fiscal_quarter_of_year_num INTEGER 以数字表示的财政季度(例如 1)。
fiscal_week_of_year VARCHAR 一年中的财政周(例如“Week01”“FW01”)。
fiscal_week_of_year_num INTEGER 相应年份的财政周数(例如 1)。
fiscal_period_of_year VARCHAR 自定义周期名称(例如“P01”)。
fiscal_period_of_year_num INTEGER 数字自定义周期(例如 1)。
season VARCHAR 自定义季名称(例如“冬季”)。
season_num INTEGER 数字自定义季(例如 1)。

为便于说明,以下是 fiscal_calendar_table 表中的一些示例行:

reference_date fiscal_year fiscal_year_num fiscal_period fiscal_period_num
2023-12-25 FY2024 2024 P01 1
2023-12-26 FY2024 2024 P01 1
2024-01-01 FY2024 2024 P02 2
2024-01-02 FY2024 2024 P02 2

在 LookML 中定义自定义日历视图

在数据库中创建日历表后,您需要创建一个 LookML 视图来对数据库日历表进行建模。

自定义日历视图文件必须包含以下内容:

  • 指向数据库中自定义日历表的 sql_table_name 参数。
  • 用于将表格的列映射到 Looker 自定义时间段类型的 calendar_definition 组成块。
  • dimension 参数,用于对数据库中自定义日历表的列进行建模。

以下是一个名为 fiscal_calendar.view.lkml 的示例视图文件,用于对示例 fiscal_calendar_table 进行建模:

view: fiscal_calendar {
  sql_table_name: fiscal_calendar_table ;;
  calendar_definition: {
    reference_date: reference_date
    timeframe_mapping: {
      custom_year: fiscal_year
      custom_quarter: fiscal_quarter_of_year
      custom_date: fiscal_date
      custom_week: fiscal_week_of_year
      custom_period: fiscal_period_of_year
      custom_season: season
    }
    timeframe_ordinal_mapping: {
      custom_year: fiscal_year_num
      custom_quarter: fiscal_quarter_of_year_num
      custom_date: fiscal_date_num
      custom_week: fiscal_week_of_year_num
      custom_period: fiscal_period_of_year_num
      custom_season: season_num
    }
  }

  dimension: reference_date {
    type: date
    primary_key: yes
    sql: ${TABLE}.reference_date ;; # Assuming column name is reference_date
  }

  dimension: fiscal_date {
  type: string
  sql: FORMAT_TIMESTAMP('%Y-%m-%d', ${TABLE}.reference_date) ;;
}

  dimension: fiscal_year {
    type: string
    sql: ${TABLE}.fiscal_year ;;
  }

  dimension: fiscal_year_num {
    type: number
    sql: ${TABLE}.fiscal_year_num ;;
  }

  # ... other dimensions for quarters, weeks, periods, seasons, etc. ...

  # Example placeholder dimensions for unused timeframes
  dimension: season {
    type: string
    sql: 'N/A' ;;
    hidden: yes
  }
  dimension: season_num {
    type: number
    sql: 0 ;;
    hidden: yes
  }
}

如需详细了解 calendar_definition 参数,请参阅 calendar_definition 参数页面。

创建自定义日历维度组

在数据库中创建日历表在 LookML 中对数据库日历表进行建模后,您可以创建基于自定义日历视图的 type: custom_calendar 维度组。

例如,以下是一个名为 orders.view.lkml 的视图文件,用于定义自定义日历维度组。

include: "/views/fiscal_calendar.view"

view: orders {
  sql_table_name: public.orders ;;

  dimension_group: created {
    type: custom_calendar

    # Optional list of allowed timeframes
    custom_timeframes: [
      custom_date,
      custom_week,
      custom_year
    ]
    sql: ${TABLE}.created_at ;;
    based_on_calendar: fiscal_calendar  # This links to your calendar view
  }
}

借助此 LookML,Looker 将自动为 created 维度组创建一组新的自定义时间范围(例如“创建自定义年份”“创建自定义周”)。然后,用户可以使用这些字段进行探索、生成报告和过滤。

如需详细了解如何为自定义日历创建维度组,请参阅 dimension_group 文档页面。

注意事项

请注意自定义日历的以下限制:

  • 过滤后的度量:过滤后的度量不支持自定义日历:您无法在度量的 filters 参数中引用自定义日历维度。
  • 高级过滤条件:高级过滤条件不支持自定义日历:您无法在 Looker 过滤条件表达式中引用自定义日历维度。
  • 对称聚合:在某些复杂的联接场景中,对于涉及自定义日历维度的查询,对称聚合可能无法得到完全支持。
  • 维度填充:对于自定义日历维度,Looker 无法维度填充缺失的日期。
  • 过滤超出日历边界的时间范围:如果将过滤条件应用于自定义时间范围,导致日期不在日历中,则可能会返回意外结果。这与用于计算周期开始时间的序数算术有关。
  • OR 过滤条件:对于使用自定义日历的查询,不支持 OR 过滤条件
  • 时区转换行为:Looker 会遵循现有的时区转换语义。也就是说,如果数据库时区与查询时区一致,则不会应用时区转换。如果两者不一致,Looker 会应用时区转换。您可以通过为自定义日历维度组指定 convert_tz: no 来替换此行为。
  • 默认排序:选择自定义日历字段后,Looker 会对第一个日期字段应用默认排序。然后,用户可以指定不同的数据排序方式
  • 自定义日历过滤条件:自定义日历维度支持特定的过滤条件选项,例如过去 3 个自定义年份此自定义周期。如需了解详情,请参阅过滤和限制数据文档页面中的自定义日历过滤条件部分。

自定义日历支持的数据库方言

下表显示了 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.x - 0.17.x
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 AlloyDB for PostgreSQL
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