increment_key

Uso

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

- ou -

explore
aggregate_table
materialization
increment_key
Valor padrão
Nenhum

Aceita
O nome de uma dimensão do LookML baseada em tempo.

Regras especiais
increment_key só é compatível com tabelas persistentes e apenas para dialetos específicos.

Definição

É possível criar TDPs incrementais no projeto se o dialeto for compatível com eles. Uma TDP incremental é uma tabela derivada persistente (TDP) que o Looker cria anexando dados novos à tabela, em vez de recriá-la por completo. Para mais informações, consulte a página de documentação sobre TDPs incrementais.

increment_key é o parâmetro que transforma uma TDP em uma TDP incremental, especificando o incremento de tempo para que os dados novos sejam consultados e adicionados ao final da TDP. Além de increment_key, você pode fornecer um increment_offset para especificar o número de períodos anteriores (na granularidade da chave de incremento) que são recriados para considerar os dados que chegam com atraso.

O increment_key de uma TDP é independente do gatilho de persistência dela. Consulte a página de documentação TDPs incrementais para ver alguns exemplos de cenários que mostram a interação de increment_key, increment_offset e estratégia de persistência.

O parâmetro increment_key funciona apenas com dialetos compatíveis e apenas com tabelas que têm uma estratégia de persistência, como TDPs e tabelas de agregação (que são um tipo de TDP).

O increment_key precisa especificar uma dimensão do LookML baseada em tempo:

Além disso, o increment_key precisa ser:

  • Um tempo absoluto truncado, como dia, mês, ano ou trimestre fiscal. Períodos como o dia da semana não são aceitos.
  • Um carimbo de data/hora que aumenta de forma previsível com novos dados, como a data de criação do pedido. Em outras palavras, um carimbo de data/hora só deve ser usado como uma chave de incremento se os dados mais recentes adicionados à tabela também tiverem o carimbo de data/hora mais recente. Um carimbo de data/hora, como o aniversário do usuário, não funcionaria como uma chave de incremento, já que um carimbo de data/hora de aniversário não aumenta de forma confiável com a adição de novos usuários à tabela.

Como criar uma TDP incremental baseada em LookML

Para transformar uma TDP baseada em LookML (nativa) em uma TDP incremental, use o parâmetro increment_key para especificar o nome de uma dimensão do LookML baseada em tempo. A dimensão precisa ser definida na visualização em que o explore_source da TDP se baseia.

Por exemplo, veja um arquivo de visualização para uma TDP baseada em LookML, usando o parâmetro explore_source do LookML. A TDP é criada com base na Análise flights, que, neste caso, é baseada na visualização 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
  }
}

Essa tabela será criada por completo na primeira vez que uma consulta for executada nela. Depois disso, a TDP será recriada em incrementos de um dia (increment_key: departure_date), voltando três dias (increment_offset: 3).

A dimensão departure_date é, na verdade, o período date do grupo de dimensão departure. Consulte a página de documentação do parâmetro dimension_group para uma visão geral de como os grupos de dimensões funcionam. O grupo de dimensões e o período são definidos na visualização flights, que é o explore_source para essa TDP. Veja como o grupo de dimensões departure é definido no arquivo de visualização flights:

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

Como criar uma TDP incremental baseada em SQL

O Looker sugere que você use tabelas derivadas (nativas) baseadas em LookML como base para TDPs incrementais, em vez de usar tabelas derivadas com base em SQL. As tabelas derivadas nativas lidam de forma inerente com a lógica complexa necessária para TDPs incrementais. As TDPs baseadas em SQL dependem de uma lógica criada manualmente, que é propensa a erros quando usada com funcionalidades altamente complexas.

Para definir uma TDP incremental baseada em SQL, use increment_key e (opcionalmente) increment_offset como faria com uma TDP baseada em LookML. No entanto, como as TDPs baseadas em SQL não se baseiam em arquivos de visualização do LookML, há requisitos adicionais para transformar uma TDP baseada em SQL em uma TDP incremental:

  • A chave de incremento precisa ser baseada em uma dimensão do LookML baseada em tempo que você define no arquivo de visualização da TDP.
  • É necessário fornecer um filtro Liquid {% incrementcondition %} na TDP para conectar a chave de incremento à coluna de tempo do banco de dados em que ela se baseia. O filtro {% incrementcondition %} precisa especificar o nome da coluna no banco de dados, não um alias SQL nem o nome de uma dimensão baseada na coluna (consulte o exemplo a seguir).

O formato básico do filtro Liquid é:

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

Por exemplo, este é o arquivo de visualização de uma TDP baseada em SQL que é recriada em incrementos de um dia (increment_key: "dep_date"), em que os dados dos últimos três dias serão adicionados à tabela quando ela for recriada (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
  }
}

Observe o seguinte sobre este exemplo:

  • A tabela derivada é baseada em uma instrução SQL. A instrução SQL cria uma coluna na tabela derivada com base na coluna flights.leaving_time no banco de dados. A coluna recebe o alias departure.
  • O arquivo de visualização da TDP define um grupo de dimensões chamado dep.
    • O parâmetro sql do grupo de dimensão indica que ele se baseia na coluna departure na tabela derivada.
    • O parâmetro timeframes do grupo de dimensão inclui date como um período.
  • O increment_key da tabela derivada usa a dimensão dep_date, que é baseada no período date do grupo de dimensão dep. Consulte a página de documentação do parâmetro dimension_group para uma visão geral de como os grupos de dimensões funcionam.
  • O filtro Liquid {% incrementcondition %} é usado para conectar a chave de incremento à coluna flights.leaving_time no banco de dados.
    • O {% incrementcondition %} precisa especificar o nome de uma coluna TIMESTAMP no banco de dados (ou precisa ser avaliado como uma coluna TIMESTAMP no banco de dados).
    • O {% incrementcondition %} precisa ser avaliado em relação ao que está disponível na cláusula FROM que define a TDP, como colunas da tabela especificada na cláusula FROM. O {% incrementcondition %} não pode se referir ao resultado da instrução SELECT, como um alias que foi atribuído a uma coluna na instrução SQL ou o nome de uma dimensão baseada na coluna. Neste exemplo, o {% incrementcondition %} é flights.leaving_time. Como a cláusula FROM especifica a tabela flights, o {% incrementcondition %} pode se referir a colunas da tabela flights.
    • O {% incrementcondition %} precisa apontar para a mesma coluna do banco de dados usada para a chave de incremento. Neste exemplo, a chave de incremento é dep_date, uma dimensão definida pela coluna departure na TDP, que é um alias para a coluna flights.leaving_time no banco de dados. Portanto, o filtro aponta para flights.leaving_time:
WHERE {% incrementcondition %} flights.leaving_time {%  endincrementcondition %}

É possível adicionar à cláusula WHERE para criar outros filtros. Por exemplo, se a tabela do banco de dados tiver muitos anos, você poderá criar um filtro para que a criação inicial da TDP use apenas dados após uma determinada data. Este WHERE cria uma TDP com dados de depois de 1º de janeiro de 2020:

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

Também é possível usar a cláusula WHERE para analisar dados em SQL em um carimbo de data/hora e, em seguida, dar um alias a ele. Por exemplo, a TDP incremental a seguir usa um incremento de 15 minutos com base em text_column, que são dados de string analisados em dados de carimbo de data/hora:

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
  }
}

É possível usar o alias para o SQL na definição sql do grupo de dimensões, mas é preciso usar a expressão SQL na cláusula WHERE. Como minute15 foi configurado como período no grupo de dimensões event, é possível usar event_minute15 como a chave de incremento para receber um incremento de 15 minutos para a TDP.

Criar uma tabela de agregação incremental

Para criar uma tabela de agregação incremental, adicione increment_key e (opcionalmente) increment_offset ao parâmetro materialization do parâmetro aggregate_table. Use o parâmetro increment_key para especificar o nome de uma dimensão do LookML baseada em tempo. A dimensão precisa ser definida na visualização em que a Análise da tabela de agregação se baseia.

Por exemplo, esta tabela de agregação é baseada na Análise accidents, que, neste caso, é baseada na visualização accidents. A tabela de agregação é recriada em incrementos de uma semana (increment_key: event_week), voltando duas semanas (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
    }
  }
}

A chave de incremento usa a dimensão event_week, que se baseia no período week do grupo de dimensões event. Consulte a página de documentação do parâmetro dimension_group para uma visão geral de como os grupos de dimensões funcionam. O grupo de dimensões e o período são definidos na visualização accidents:

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

Informações importantes

Otimizar a tabela de origem para consultas baseadas em tempo

Verifique se a tabela de origem da TDP incremental está otimizada para consultas baseadas em tempo. Especificamente, a coluna baseada em tempo usada para a chave de incremento precisa ter uma estratégia de otimização, como particionamento, chaves de classificação, índices ou qualquer estratégia de otimização compatível com seu dialeto. A otimização da tabela de origem é altamente recomendada porque, sempre que a tabela incremental é atualizada, o Looker consulta a tabela de origem para determinar os valores mais recentes da coluna baseada em tempo que está sendo usada para a chave de incremento. Se a tabela de origem não for otimizada para essas consultas, a consulta do Looker para os valores mais recentes poderá ser lenta e cara.

Dialetos de banco de dados compatíveis com TDPs incrementais

Para que o Looker seja compatível com TDPs incrementais no seu projeto do Looker, o dialeto do banco de dados precisa ser compatível com comandos da linguagem de definição de dados (DDL) que permitem excluir e inserir linhas.

A tabela a seguir mostra quais dialetos são compatíveis com TDPs incrementais na versão mais recente do Looker:

Dialeto Compatível?
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