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 de tempo do LookML

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

Definição

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

increment_key é o parâmetro que transforma uma TDP em uma TDP incremental, especificando o incremento de tempo para o qual os dados atualizados devem ser consultados e adicionados à TDP. Além do 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 dados que chegam atrasados.

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

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

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

Além disso, o increment_key precisa ser:

  • Um período absoluto truncado, como dia, mês, ano, trimestre fiscal etc. Períodos como 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 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 não aumenta de forma confiável com novos usuários adicionados à tabela.

Como criar uma TDP incremental baseada em LookML

Para transformar uma PDT baseada em LookML (nativa) em uma PDT 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 PDT se baseia.

Por exemplo, aqui está um arquivo de visualização para uma PDT baseada em LookML, usando o parâmetro explore_source da LookML. A TDP é criada 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, o PDT será recriado 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ões 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 PDT. 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 PDT incremental baseada em SQL

O Looker sugere que você use tabelas derivadas nativas baseadas em LookML como base para PDTs incrementais, em vez de tabelas derivadas baseadas em SQL. As tabelas derivadas nativas processam a lógica complexa necessária para TDPs incrementais. As PDTs baseadas em SQL dependem de uma lógica criada manualmente, que está sujeita a erros quando usada com funcionalidades altamente complexas.

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

  • Você precisa basear a chave de incremento em uma dimensão do LookML baseada em tempo que você define no arquivo de visualização da PDT.
  • Você precisa fornecer um filtro do 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 PDT baseada em SQL que é recriada em incrementos de um dia (increment_key: "dep_date"), em que os dados dos últimos três dias são adicionados à tabela quando ela é 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 do banco de dados. A coluna recebe o alias departure.
  • O arquivo de visualização da PDT define um grupo de dimensões chamado dep.
    • O parâmetro sql do grupo de dimensões indica que ele se baseia na coluna departure da tabela derivada.
    • O parâmetro timeframes do grupo de dimensões inclui date como um período.
  • A increment_key da tabela derivada usa a dimensão dep_date, que é baseada no período date do grupo de dimensões 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 {% incrementcondition %} do Liquid é 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 seu banco de dados ou ser avaliado como uma coluna TIMESTAMP no seu banco de dados.
    • A {% incrementcondition %} precisa ser avaliada em relação ao que está disponível na cláusula FROM que define sua PDT, 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 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 de 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 PDT, que é um alias da coluna flights.leaving_time no banco de dados. Portanto, o filtro aponta para flights.leaving_time:
WHERE {% incrementcondition %} flights.leaving_time {%  endincrementcondition %}

Você pode adicionar à cláusula WHERE para criar outros filtros. Por exemplo, se a tabela do banco de dados for muito antiga, crie um filtro para que a criação inicial da PDT use apenas dados posteriores a uma determinada data. Esta WHERE cria uma PDT 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 e transformá-los em um carimbo de data/hora, atribuindo um alias a eles. Por exemplo, a seguinte TDP incremental 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 do SQL na definição do grupo de dimensões sql, mas é necessário usar a expressão SQL na cláusula WHERE. Como minute15 foi configurado como período no grupo de dimensões event, você pode usar event_minute15 como a chave de incremento para ter um incremento de 15 minutos para a PDT.

Como criar uma tabela agregada incremental

Para criar uma tabela agregada incremental, adicione increment_key e (opcionalmente) increment_offset no 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 agregada se baseia.

Por exemplo, essa tabela agregada é baseada na análise detalhada accidents, que, neste caso, é baseada na visualização accidents. A tabela agregada é 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 PDT 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, sortkeys, índices ou qualquer outra estratégia 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 usada para a chave incremental. Se a tabela de origem não estiver 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 ofereça suporte a PDTs incrementais no seu projeto, 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 PDTs 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+
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 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