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 é compatível apenas com tabelas persistentes e somente para dialetos específicos

Definição

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

increment_key é o parâmetro que transforma uma PDT em uma PDT incremental, especificando o incremento de tempo para o qual os dados novos precisam ser consultados e anexados à PDT. 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 contabilizar dados recebidos com atraso.

A increment_key de uma PDT é independente do acionador de persistência da PDT. Consulte a página de documentação sobre PDTs incrementais para alguns cenários de exemplo 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 somente com tabelas que têm uma estratégia de persistência, como PDTs e tabelas agregadas (que são um tipo de PDT).

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

Além disso, a increment_key precisa ser:

  • Um horário absoluto truncado, como dia, mês, ano, trimestre fiscal e assim por diante. Períodos como dia da semana não são compatíveis.
  • 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ó pode 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 novos usuários adicionados à tabela.

Como criar uma PDT 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 a PDT's explore_source é baseada.

Por exemplo, aqui está um arquivo de visualização para uma PDT baseada em LookML, usando o explore_source parâmetro do LookML. A PDT é criada na Análise flights, que, nesse 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 PDT 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 date período 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 é a explore_source dessa 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 baseadas em LookML (nativas) como base para PDTs incrementais, em vez de usar tabelas derivadas baseadas em SQL. As tabelas derivadas nativas processam inerentemente a lógica complexa necessária para PDTs incrementais. As PDTs baseadas em SQL dependem de uma lógica criada manualmente, que é propensa a erros quando usada com funcionalidades altamente complexas.

Para definir uma PDT incremental baseada em SQL, use increment_key e (opcionalmente) increment_offset como faria com uma PDT baseada em LookML. No entanto, como as PDTs baseadas em SQL não são baseadas em arquivos de visualização do LookML, há outros requisitos para transformar uma PDT baseada em SQL em uma PDT 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 {% incrementcondition %} filtro Liquid na PDT para conectar a chave de incremento à coluna de tempo do banco de dados em que a chave de incremento é baseada. 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, aqui está 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 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 que é baseada na coluna flights.leaving_time no 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 o grupo de dimensões é baseado na coluna departure na tabela derivada.
    • O parâmetro timeframes do grupo de dimensões inclui date como um período.
  • A tabela derivada increment_key usa a dimensão dep_date, que é uma dimensão 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 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 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 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 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 voltar muitos anos, você poderá criar um filtro para que a build inicial da PDT use apenas dados após uma determinada data. Esse 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'

Você também pode usar a cláusula WHERE para analisar dados em SQL em um carimbo de data/hora e, em seguida, atribuir um alias a ele. Por exemplo, a PDT incremental a seguir usa um incremento de 15 minutos baseado na text_column, que são dados de string que foram 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
  }
}

Você pode usar o alias para o SQL na definição sql do grupo de dimensões, mas precisa usar a expressão SQL na cláusula WHERE. E, como minute15 foi configurado como período no grupo de dimensões event, você pode usar event_minute15 como a chave de incremento para receber um incremento de 15 minutos para a PDT.

Como criar uma tabela de agregação incremental

Para criar uma tabela de agregação 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 é baseada.

Por exemplo, essa tabela agregada é baseada na Análise accidents, que, nesse 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 é baseada no week período 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, 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 usada para a chave de incremento. 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 PDTs incrementais

Para que o Looker ofereça suporte a PDTs incrementais no seu projeto do Looker, o dialeto do banco de dados precisa oferecer suporte a comandos da linguagem de definição de dados (DDL) que permitam excluir e inserir linhas.

A tabela a seguir mostra quais dialetos oferecem suporte a 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.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