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 は永続的な派生テーブル（PDT）です。Looker はテーブル全体を再構築するのではなく、テーブルに新しいデータを追加して構築します。詳細については、増分 PDT のドキュメント ページをご覧ください。

increment_key は、PDT にクエリして追加する新しいデータの時間増分を指定することで、PDT を増分 PDT にするパラメータです。increment_key に加えて、必要に応じて increment_offset を指定して、遅れて到着するデータを考慮して再構築する、以前の期間（インクリメント キーの粒度）の数を指定できます。

PDT の increment_key は、PDT の永続化トリガーとは独立しています。増分 PDT のドキュメント ページで、increment_key、increment_offset、永続化戦略の相互作用を示すシナリオの例をご覧ください。

increment_key パラメータは、サポートされている言語でのみ、永続化戦略を持つテーブルでのみ機能します。PDT や集約テーブル（PDT の一種）などです。

increment_key では、時間ベースの LookML ディメンションを指定する必要があります。

• LookML ベースの PDT の場合、increment_key は、PDT の explore_source のベースとなるビューで定義された LookML ディメンションに基づく必要があります。例については、このページの LookML ベースの増分 PDT を作成するをご覧ください。
• 集約テーブルの場合、increment_key は、集約テーブルの Explore のベースとなるビューで定義された LookML ディメンションに基づく必要があります。例については、このページの増分サマリー表を作成するをご覧ください。
• SQL ベースの PDT の場合、increment_key は、PDT のビューファイル内で定義された LookML ディメンションに基づく必要があります。例については、このページの SQL ベースの増分 PDT を作成するをご覧ください。

また、increment_key は次の条件を満たす必要があります。

• 日、月、年、会計四半期など、切り捨てられた絶対時間。曜日などのタイムフレームはサポートされていません。
• 注文作成日など、新しいデータで予測どおりに増加するタイムスタンプ。つまり、テーブルに追加された最新のデータにも最新のタイムスタンプがある場合にのみ、タイムスタンプを増分キーとして使用する必要があります。ユーザーの誕生日などのタイムスタンプは、テーブルに追加された新しいユーザーで誕生日タイムスタンプが確実に増加するわけではないため、増分キーとして機能しません。

LookML ベースの増分 PDT を作成する

LookML ベース（ネイティブ）の PDT を増分 PDT にするには、increment_key パラメータを使用して、時間ベースの LookML ディメンションの名前を指定します。ディメンションは、PDT の explore_source のベースとなるビューで定義する必要があります。

たとえば、LookML に基づく PDT のビューファイルは、explore_source LookML パラメータを使用して次のようになります。PDT は flights Explore から作成されます。この Explore は 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 は 1 日分（increment_key: departure_date）単位で再構築され、3 日分（increment_offset: 3）に戻ります。

departure_date ディメンションは、実際には departure ディメンション グループの date タイムフレーム です。（dimension_group パラメータの仕組みの概要については、ドキュメント ページをご覧ください）。ディメンション グループと期間はどちらも、この PDT の explore_source である flights ビューで定義されます。flights ビューファイルで departure ディメンション グループを定義する方法は次のとおりです。

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

SQL ベースの増分 PDT を作成する

Looker では、LookML ベース（ネイティブ）の派生テーブルを使用するのではなく、SQL ベースの派生テーブルを増分 PDT のベースとして使用することをおすすめします。ネイティブ派生テーブルは、増分 PDT に必要な複雑なロジックを本質的に処理します。SQL ベースの PDT は手動で作成されたロジックに依存するため、非常に複雑な機能で使用するとエラーが発生しやすくなります。

SQL ベースの増分 PDT を定義するには、SQL ベースの PDT と同様に increment_key と（必要に応じて）increment_offset を使用します。ただし、SQL ベースの PDT は LookML ビューファイルに基づいていないため、SQL ベースの PDT を増分 PDT にするには追加の要件があります。

• PDT のビューファイルで定義する時間ベースの LookML ディメンションに基づいて、増分キーを作成する必要があります。
• PDT に {% incrementcondition %} Liquid フィルタを指定して、増分キーを、その増分キーの基準となっているデータベース時間列と結び付ける必要があります。{% incrementcondition %} フィルタでは、データベース内の列の名前を指定する必要があります。SQL エイリアスや、列に基づくディメンションの名前は指定できません（次の例を参照）。

Liquid フィルタの基本形式は次のとおりです。

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

たとえば、1 日単位（increment_key: "dep_date"）で再構築される SQL ベースの PDT のビューファイルは次のようになります。再構築時に過去 3 日間のデータがテーブルに追加されます（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 列に評価される必要があります）。
  • The {% incrementcondition %} は、PDT を定義する FROM 句で使用可能なもの（FROM 句で指定されたテーブルの列など）に対して評価する必要があります。{% incrementcondition %} は、SELECT ステートメントの結果（SQL ステートメントの列に付けられたエイリアスや、列に基づくディメンションの名前など）を参照できません。この例では、{% incrementcondition %} は flights.leaving_time です。FROM 句で flights テーブルが指定されているため、{% incrementcondition %} は flights テーブルの列を参照できます。
  • The {% 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 は、text_column に基づく 15 分単位の増分を使用します。これは、タイムスタンプ データに解析された文字列データです。

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 分単位の増分を取得できます。

増分サマリー表を作成する

増分集約テーブルを作成するには、increment_keyと（必要に応じて）increment_offsetをmaterializationパラメータのaggregate_tableパラメータの下に追加します。increment_key パラメータを使用して、時間ベースの LookML ディメンションの名前を指定します。ディメンションは、集約テーブルの Explore のベースとなるビューで定義する必要があります。

たとえば、この集約テーブルは accidents Explore に基づいています。この Explore は accidents ビューに基づいています。サマリー表は 1 週間単位（increment_key: event_week）で再構築され、2 週間分（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 プロジェクトで増分 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
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
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