increment_key

用量

view: my_view {
  derived_table: {
    increment_key: "created_date"
    ...
  }
}

階層 查看檔案 view derived_table increment_key - 或 - 模型檔案 explore aggregate_table materialization increment_key

預設值 無 接受 時間 LookML 維度的名稱 特殊規則 increment_key 僅支援永久性資料表，且僅適用於特定方言

定義

如果方言支援，您可以在專案中建立永久累加型衍生資料表。累加型 PDT 是一種永久衍生資料表 (PDT)，Looker 會將新資料附加至資料表，而不是重新建構整個資料表。詳情請參閱「永久累加型衍生資料表」說明文件頁面。

increment_key 是將 PDT 轉換為增量 PDT 的參數，可指定查詢最新資料並附加至 PDT 的時間增量。除了 increment_key 之外，您也可以選擇提供 increment_offset，指定要重建多少個先前的時間範圍 (以增量鍵的精細程度為準)，以納入延遲到達的資料。

PDT 的 increment_key 與 PDT 的持續性觸發條件無關。如需 increment_key、increment_offset 和持續性策略互動的情境範例，請參閱「永久累加型衍生資料表」說明文件頁面。

increment_key 參數僅適用於支援的方言，且僅適用於具有永久策略的資料表，例如 PDT 和匯總表格 (一種 PDT)。

increment_key 必須指定以時間為基礎的 LookML 維度：

• 如果是以 LookML 為基礎的 PDT，increment_key 必須以 LookML 維度為基礎，而該維度是在 PDT 的 explore_source 所依據的檢視表中定義。如需範例，請參閱本頁的「建立以 LookML 為基礎的永久累加型衍生資料表」一節。
• 如果是匯總表格，increment_key 必須以 LookML 維度為基礎，而該維度是在匯總表格探索所依據的檢視表中定義。如需範例，請參閱本頁的「建立累加型匯總表格」一節。
• 如果是以 SQL 為基礎的 PDT，increment_key 必須以 PDT 檢視表檔案中定義的 LookML 維度為基礎。如需範例，請參閱本頁的「建立 SQL 累加型 PDT」一節。

此外，increment_key 必須符合下列條件：

• 截斷的絕對時間，例如日、月、年或會計季度。不支援星期幾等時間範圍。
• 時間戳記，會隨著新資料 (例如訂單建立日期) 增加而遞增。換句話說，只有在新增至資料表的最新資料也具有最新時間戳記時，才應使用時間戳記做為遞增鍵。使用者生日等時間戳記不適合做為遞增鍵，因為生日時間戳記不會隨著資料表新增使用者而穩定增加。

建立以 LookML 為基礎的增量 PDT

如要將以 LookML 為基礎 (原生) 的 PDT 轉換為累加型 PDT，請使用 increment_key 參數指定時間型 LookML 維度的名稱。維度必須在 PDT explore_source 所依據的檢視表中定義。

舉例來說，以下是使用 explore_source LookML 參數，以 LookML 為基礎的 PDT 檢視表檔案。PDT 是根據 flights 探索建立，在本例中是以 flights 檢視表為基礎：

view: flights_lookml_incremental_pdt {
  derived_table: {
    indexes: ["id"]
    increment_key: "departure_date"
    increment_offset: 3
    datagroup_trigger: flights_default_datagroup
    distribution_style: all
    explore_source: flights {
      column: id {}
      column: carrier {}
      column: departure_date {}
    }
  }

  dimension: id {
    type: number
  }
  dimension: carrier {
    type: string
  }
  dimension: departure_date {
    type: date
  }
}

首次對這個資料表執行查詢時，系統會完整建構資料表。之後，PDT 會以一天為單位 (increment_key: departure_date) 重新建立，並回溯三天 (increment_offset: 3)。

departure_date 維度實際上是 departure 維度群組中的 date 時間範圍。(如要概略瞭解維度群組的運作方式，請參閱 dimension_group 參數說明文件頁面)。維度群組和時間範圍都是在 flights 檢視表中定義，也就是這個 PDT 的 explore_source。以下是 flights 檢視表檔案中 departure 維度群組的定義方式：

...
  dimension_group: departure {
    type: time
    timeframes: [
      raw,
      date,
      week,
      month,
      year
    ]
    sql: ${TABLE}.dep_time ;;
  }
...

建立以 SQL 為基礎的增量 PDT

Looker 建議您使用以 LookML 為基礎的 (原生) 衍生資料表做為累加 PDT 的基礎，而非使用以 SQL 為基礎的衍生資料表。原生衍生資料表本身會處理增量 PDT 所需的複雜邏輯。SQL 型 PDT 仰賴手動建立的邏輯，在搭配高度複雜的功能使用時，容易發生錯誤。

如要定義以 SQL 為基礎的累加型 PDT，請使用 increment_key 和 increment_offset (選用)，就像使用以 LookML 為基礎的 PDT 一樣。不過，SQL 衍生 PDT 並非以 LookML 檢視表檔案為基礎，因此如要將 SQL 衍生 PDT 設為增量 PDT，還須符合其他規定：

• 您必須根據在 PDT 檢視表檔案中定義的時間型 LookML 維度，設定遞增鍵。
• 您必須在 PDT 中提供 {% incrementcondition %} Liquid 篩選器，將增量鍵連結至增量鍵所依據的資料庫時間欄。{% incrementcondition %} 篩選器必須指定資料庫中的資料欄名稱，而非 SQL 別名或以該資料欄為基礎的維度名稱 (請參閱以下範例)。

Liquid 篩選器的基本格式如下：

   WHERE {% incrementcondition %} database_table_name.database_time_column {% endincrementcondition %}

舉例來說，以下是 SQL 永久衍生資料表的檢視表檔案，該資料表會以一天為單位重新建立 (increment_key: "dep_date")，並在重新建立時將過去三天的資料加入資料表 (increment_offset: 3)：

view: sql_based_incremental_date_pdt {
  derived_table: {
    datagroup_trigger: flights_default_datagroup
    increment_key: "dep_date"
    increment_offset: 3
    distribution_style: all
    sql: SELECT
        flights.id2  AS "id",
        flights.origin  AS "origin",
        DATE(flights.leaving_time )  AS "departure"
      FROM public.flights  AS flights
      WHERE {% incrementcondition %} flights.leaving_time {%  endincrementcondition %}
          ;;
  }

  dimension_group: dep {
    type: time
    timeframes: [date, week, month, year]
    datatype: date
    sql:  ${TABLE}.departure
    ;;
  }
  dimension: id {
      type: number
    }
    dimension: origin {
      type: string
  }
}

請注意以下範例：

• 衍生資料表是以 SQL 陳述式為基礎。SQL 陳述式會根據資料庫中的 flights.leaving_time 資料欄，在衍生資料表中建立資料欄。資料欄的別名為 departure。
• PDT 的檢視表檔案定義了名為 dep 的維度群組。
  • 維度群組的 sql 參數表示維度群組是以衍生資料表中的 departure 欄為基礎。
  • 維度群組的 timeframes 參數包含 date 做為時間範圍。
• 衍生資料表的 increment_key 使用 dep_date 維度，這個維度是以 dep 維度群組的 date 時間範圍為基礎。(如要概略瞭解維度群組的運作方式，請參閱 dimension_group 參數說明文件頁面)。
• {% incrementcondition %} Liquid 篩選器用於將遞增鍵連結至資料庫中的 flights.leaving_time 欄。
  • {% incrementcondition %} 必須指定資料庫中 TIMESTAMP 資料欄的名稱 (或必須評估為資料庫中的 TIMESTAMP 資料欄)。
  • {% incrementcondition %} 必須根據定義 PDT 的 FROM 子句中可用的內容進行評估，例如 FROM 子句中指定的資料表資料欄。{% incrementcondition %} 無法參照 SELECT 陳述式的結果，例如 SQL 陳述式中資料欄的別名，或以該資料欄為基礎的維度名稱。在本範例中，{% incrementcondition %} 為 flights.leaving_time。由於 FROM 子句指定了 flights 資料表，因此 {% incrementcondition %} 可以參照 flights 資料表中的資料欄。
  • {% incrementcondition %} 必須指向用於遞增鍵的同一個資料庫資料欄。在本例中，遞增鍵為 dep_date，這是由 PDT 中的 departure 資料欄定義的維度，也是資料庫中 flights.leaving_time 資料欄的別名。因此，篩選器會指向 flights.leaving_time：

WHERE {% incrementcondition %} flights.leaving_time {%  endincrementcondition %}

您可以在 WHERE 子句中新增內容，建立其他篩選器。舉例來說，如果資料庫資料表可追溯至多年前，您可以建立篩選條件，讓 PDT 的初始建構作業只使用特定日期之後的資料。這個 WHERE 會使用 2020 年 1 月 1 日之後的資料建立 PDT：

WHERE {% incrementcondition %} flights.leaving_time {%  endincrementcondition %}
  AND flights.leaving_time > '2020-01-01'

您也可以使用 WHERE 子句，將 SQL 中的資料剖析為時間戳記，然後指定別名。舉例來說，下列增量 PDT 使用 15 分鐘的增量，以 text_column 為基礎，這是已剖析為時間戳記資料的字串資料：

view: sql_based_incremental_15min_pdt {
  derived_table: {
    datagroup_trigger: flights_default_datagroup
    increment_key: "event_minute15"
    increment_offset: 1
    sql: SELECT PARSE_TIMESTAMP("%c", flights.text_column) as parsed_timestamp_column,
        flights.id2  AS "id",
        flights.origin  AS "origin",
      FROM public.flights  AS flights
      WHERE {% incrementcondition %} PARSE_TIMESTAMP("%c", flights.text_column)
          {% endincrementcondition %} ;;
  }

  dimension_group: event {
    type: time
    timeframes: [raw, minute15, hour, date, week, month, year]
    datatype: timestamp
    sql:  ${TABLE}.parsed_timestamp_column ;;
  }
  dimension: id {
    type: number
  }
  dimension: origin {
    type: string
  }
}

您可以在維度群組 sql 定義中使用 SQL 別名，但必須在 WHERE 子句中使用 SQL 運算式。接著，由於 minute15 已設為 event 維度群組中的時間範圍，因此您可以使用 event_minute15 做為增量鍵，為 PDT 取得 15 分鐘的增量。

建立累加型匯總資料表

如要建立遞增匯總表格，請在 aggregate_table 參數的 materialization 參數下方，新增 increment_key 和 increment_offset (選用)。使用 increment_key 參數指定時間 LookML 維度的名稱。維度必須定義在匯總表格「探索」所依據的檢視表中。

舉例來說，這個匯總表格是以 accidents 探索為基礎，而這個探索是以 accidents 檢視表為基礎。匯總表格會以一週 (increment_key: event_week) 為單位重新建立，並回溯兩週 (increment_offset: 2)：

explore: accidents {
  . . .
  aggregate_table: accidents_daily {
    query: {
      dimensions: [event_date, id, weather_condition]
      measures: [count]
    }
    materialization: {
      datagroup_trigger: flights_default_datagroup
      increment_key: "event_week"
      increment_offset: 2
    }
  }
}

增量鍵會使用 event_week 維度，該維度是以 event 維度群組中的 week 時間範圍為基礎。(如要概略瞭解維度群組的運作方式，請參閱 dimension_group 參數說明文件頁面)。維度群組和時間範圍都是在 accidents 檢視表中定義：

. . .
view: accidents {
  . . .
  dimension_group: event {
      type: time
      timeframes: [
        raw,
        date,
        week,
        year
      ]
      sql: ${TABLE}.event_date ;;
  }
  . . .
}

注意事項

針對時間查詢最佳化來源資料表

請務必針對時間型查詢，最佳化遞增 PDT 的來源資料表。具體來說，用於遞增鍵的時間欄必須有最佳化策略，例如分區、排序鍵、索引，或方言支援的任何最佳化策略。強烈建議您最佳化來源資料表，因為每次更新累加資料表時，Looker 都會查詢來源資料表，判斷用於累加鍵的時間欄最新值。如果來源資料表未針對這些查詢進行最佳化，Looker 查詢最新值的速度可能會變慢，且費用較高。

增量 PDT 支援的資料庫方言

如要讓 Looker 支援 Looker 專案中的增量 PDT，資料庫方言必須支援資料定義語言 (DDL) 指令，才能刪除及插入資料列。

下表列出最新版 Looker 中，支援累加型 PDT 的方言：

方言	是否支援？
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
ClickHouse 26+
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+
Dremio 26+ with Arrow Flight SQL
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
MongoSQL
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