在 Looker 中使用自訂日曆

對於支援的方言,Looker 的自訂日曆功能可讓您在資料庫中定義自訂日曆,例如特定會計或零售日曆,然後將日曆套用至 LookML 模型中以日期為準的維度群組。使用者接著就能使用自訂時間範圍 (例如 custom_weekcustom_period) 建立探索查詢,就像使用標準時間範圍一樣。

必要條件

使用自訂日曆前,請確認符合下列先決條件:

  • 您必須擁有 Looker 連線,才能使用支援自訂日曆的方言
  • 您必須在資料庫中建立日曆資料表,然後在 Looker 中將其建立為檢視區塊模型。Looker 會使用資料庫中的日曆資料表計算自訂時間範圍。詳情請參閱「在資料庫中建立日曆資料表」一節。
  • LookML 專案必須使用新的 LookML 執行階段。如果執行個體已啟用「使用舊版 LookML 執行階段」舊版功能,您必須將 new_lookml_runtime: yes 陳述式新增至專案的資訊清單檔案。

建立自訂日曆

如要實作自訂日曆,您需要執行下列一般步驟,後續章節會提供說明:

  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 參數。
  • calendar_definition 區塊,可將表格的資料欄對應至 Looker 自訂時間範圍類型。
  • 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 無法維度填入自訂日曆維度缺少的日期。
  • 篩選超出日曆範圍的日期:如果篩選器套用至自訂時間範圍,導致日期超出日曆範圍,系統可能會傳回非預期的結果。這是因為系統會使用序數算術計算週期開始時間。
  • 時區轉換行為:Looker 會遵守現有的時區轉換語意。也就是說,如果資料庫和查詢時區相符,系統就不會套用時區轉換。如果不同意,Looker 會套用時區轉換。如要覆寫此行為,請為自訂日曆維度群組指定 convert_tz: no
  • 預設排序:選取自訂日曆欄位時,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.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