datagroup

Uso

datagroup: datagroup_name {
  max_cache_age: "24 hours"
  sql_trigger: SELECT max(id) FROM my_tablename ;;
  interval_trigger: "12 hours"
  label: "desired label"
  description: "description string"
}
Hierarquia
datagroup
Valor padrão
Nenhum

Aceita
Um identificador para o datagroup, além de subparâmetros que definem as propriedades dele.

Definição

Use datagroup para atribuir uma política de armazenamento em cache às Análises e/ou especificar uma estratégia de persistência para tabelas derivadas persistentes (TDPs). Se você quiser várias políticas para diferentes Análises e TDPs, use um parâmetro datagroup separado para especificar cada política.

Forneça um nome exclusivo para o datagroup usando apenas letras, números e sublinhados. Nenhum outro caractere é permitido.

É possível adicionar um rótulo e uma descrição para o datagroup:

  • label: especifica um rótulo opcional para o datagroup. Consulte a seção label e description nesta página para mais detalhes.
  • description: especifica uma descrição opcional para o datagroup que pode ser usada para explicar a finalidade e o mecanismo dele. Consulte a seção label e description nesta página para mais detalhes.

Especifique os detalhes da política de armazenamento em cache e persistência usando os subparâmetros datagroup:

  • max_cache_age: especifica uma string que define um período. Quando a idade do cache de uma consulta excede o período, o Looker invalida o cache. Na próxima vez que a consulta for emitida, o Looker a enviará ao banco de dados para receber resultados atualizados. Consulte a seção max_cache_age nesta página para mais detalhes.
  • sql_trigger: especifica uma consulta SQL que retorna uma linha com uma coluna. Se o valor retornado pela consulta for diferente dos resultados anteriores da consulta, o datagroup entrará em um estado acionado. Consulte a seção sql_trigger nesta página para mais detalhes.
  • interval_trigger: especifica uma programação para acionar o datagroup, como "24 hours". Consulte a seção interval_trigger nesta página para mais detalhes.

Muitas vezes, a melhor solução é usar max_cache_age em combinação com sql_trigger ou interval_trigger. Especifique um valor sql_trigger ou interval_trigger que corresponda ao carregamento de dados (ETL) no banco de dados e, em seguida, especifique um valor max_cache_age que invalide dados antigos se o ETL falhar. O parâmetro max_cache_age garante que, se o cache de um datagroup não for limpo por sql_trigger ou interval_trigger, as entradas de cache vão expirar em um determinado momento. Dessa forma, o modo de falha de um datagroup será consultar o banco de dados em vez de fornecer dados desatualizados do cache do Looker.

Um datagroup não pode ter parâmetros sql_trigger e interval_trigger. Se você definir um datagroup com os dois parâmetros, ele usará o valor interval_trigger e ignorará o valor sql_trigger, já que o parâmetro sql_trigger exige o uso de recursos do banco de dados ao consultar o banco de dados.

Para conexões que usam atributos do usuário para especificar os parâmetros de conexão, é necessário criar uma conexão separada usando os campos de substituição de TDP se você quiser definir uma política de armazenamento em cache de datagroup usando um gatilho de consulta SQL.

Sem as substituições de TDP, ainda é possível usar um datagroup para o modelo e as Análises dele, desde que você defina a política de armazenamento em cache do datagroup usando apenas max_cache_age, não sql_trigger.

max_cache_age

O parâmetro max_cache_age especifica uma string que contém um número inteiro seguido de "seconds", "minutes" ou "hours". Esse período é o máximo para que os resultados armazenados em cache sejam usados por consultas de Análise que usam o datagroup.

Quando a idade do cache de uma consulta excede o max_cache_age, o Looker invalida o cache. Na próxima vez que a consulta for emitida, o Looker a enviará ao banco de dados para receber resultados atualizados. Consulte a página de documentação Consultas de armazenamento em cache para saber por quanto tempo os dados são armazenados no cache.

O parâmetro max_cache_age define apenas quando o cache é invalidado. Ele não aciona a recriação de TDPs. Se você definir um datagroup apenas com max_cache_age, receberá um aviso de validação do LookML se alguma tabela derivada for atribuída ao datagroup. Se você deixar uma tabela derivada atribuída a um datagroup com apenas um parâmetro max_cache_age, a tabela derivada será criada quando for consultada pela primeira vez, mas ela ficará no esquema de rascunho indefinidamente e nunca será recriada, mesmo que seja consultada novamente. Se você quiser que uma TDP seja recriada em um intervalo de tempo específico, adicione um interval_trigger parâmetro ao datagroup para definir uma programação de recriação de TDP.

sql_trigger

Use o parâmetro sql_trigger para especificar uma consulta SQL que retorna exatamente uma linha com uma coluna. O Looker executa a consulta SQL em intervalos especificados no campo Programação de manutenção de datagroup e TDP da conexão do banco de dados. Se a consulta retornar um valor diferente do resultado anterior, o datagroup entrará em um estado acionado. Depois que o datagroup for acionado, o Looker vai recriar todas as TDPs com esse datagroup especificado no parâmetro datagroup_trigger. Após a conclusão da recriação da TDP, o datagroup entra em um estado pronto e o Looker invalida os resultados armazenados em cache de todas as Análises que usam esse datagroup.

Normalmente, sql_trigger especifica uma consulta SQL que indica quando um novo carregamento de dados (ETL) ocorreu, por exemplo, consultando o max(ID) em uma tabela. Também é possível usar sql_trigger para especificar um determinado horário do dia consultando a data atual e adicionando mais horas a essa marcação de tempo, conforme necessário, para chegar ao horário desejado, por exemplo, 4h.

Confira os seguintes pontos importantes sobre sql_trigger:

  • Não é possível usar sql_trigger se a conexão do banco de dados usar OAuth ou atributos do usuário e você tiver desativado as TDPs para a conexão. Isso ocorre porque o Looker precisa de credenciais estáticas para acessar o banco de dados e executar a consulta especificada no parâmetro sql_trigger. Quando as TDPs estão ativadas, é possível usar os campos Substituições de TDP para fornecer ao Looker credenciais de login estáticas separadas para processos de TDP, mesmo que a conexão use credenciais dinâmicas, como OAuth ou atributos do usuário. No entanto, com as TDPs desativadas, se a conexão usar OAuth ou atributos do usuário, não será possível fornecer ao Looker as credenciais de usuário estáticas necessárias para consultas sql_trigger.
  • O Looker não realiza a conversão de fuso horário para sql_trigger. Se você quiser acionar o datagroup em um horário específico do dia, defina o gatilho no fuso horário para o qual o banco de dados está configurado.

Consulte estes exemplos da documentação do parâmetro sql_trigger para ter ideias sobre como configurar consultas SQL para acionar um datagroup.

interval_trigger

É possível usar o subparâmetro opcional interval_trigger para especificar uma duração para a recriação. No parâmetro interval_trigger, você transmite uma string que contém um número inteiro seguido de "seconds", "minutes" ou "hours".

label e description

É possível usar os subparâmetros opcionais label e description para adicionar um rótulo personalizado e uma descrição do datagroup. Também é possível localizar esses subparâmetros usando arquivos de strings de localidade.

Esses subparâmetros são exibidos na página Datagroups na seção Database do painel Admin. Consulte a página de documentação Configurações do administrador: datagroups para mais informações sobre como eles são exibidos.

Exemplos

Os exemplos a seguir destacam os casos de uso de datagroup, incluindo:

Como criar uma política de armazenamento em cache para recuperar novos resultados sempre que houver novos dados disponíveis ou pelo menos a cada 24 horas

Para criar uma política de armazenamento em cache que recupere novos resultados sempre que houver novos dados disponíveis ou pelo menos a cada 24 horas, faça o seguinte:

  • Use o datagroup orders_datagroup (no arquivo de modelo) para nomear a política de armazenamento em cache.
  • Use o parâmetro sql_trigger para especificar a consulta que indica que há dados atualizados: select max(id) from my_tablename. Sempre que os dados forem atualizados, essa consulta retornará um novo número.
  • Use a configuração max_cache_age para invalidar os dados se eles tiverem sido armazenados em cache por 24 horas.
  • Use os parâmetros opcionais label e description para adicionar um rótulo personalizado e uma descrição do datagroup.
datagroup: orders_datagroup {
  sql_trigger: SELECT max(id) FROM my_tablename ;;
  max_cache_age: "24 hours"
  label: "ETL ID added"
  description: "Triggered when new ID is added to ETL log"
}

Para usar a política de armazenamento em cache orders_datagroup como padrão para Análises em um modelo, use o parâmetro persist_with no nível do modelo e especifique o orders_datagroup:

persist_with: orders_datagroup

Para usar a política de armazenamento em cache orders_datagroup para uma Análise específica, adicione o parâmetro persist_with no parâmetro explore e especifique o orders_datagroup. Se houver um datagroup padrão especificado no nível do modelo, é possível usar o parâmetro persist_with em uma explore para substituir a configuração padrão.

explore: customer_facts {
  persist_with: orders_datagroup
  ...
}

Para usar a política de armazenamento em cache do datagroup orders_datagroup para recriar uma TDP, adicione datagroup_trigger no parâmetro derived_table e especifique o orders_datagroup:

view: customer_order_facts {
  derived_table: {
    datagroup_trigger: orders_datagroup
    ...
  }
}

Como criar um datagroup para programar entregas no último dia de cada mês

Talvez você queira criar uma programação que envie uma entrega de conteúdo no final de cada mês. No entanto, nem todos os meses têm o mesmo número de dias. É possível criar um datagroup para acionar entregas de conteúdo no final de cada mês, independentemente do número de dias em um mês específico.

  1. Crie um datagroup usando uma instrução SQL para acionar no final de cada mês:

    datagroup: month_end_datagroup {
sql_trigger: SELECT (EXTRACT(MONTH FROM DATEADD( day, 1, GETDATE()))) ;;
description: "Triggered on the last day of each month"
}

    Este exemplo está em SQL do Redshift e pode exigir pequenas adaptações para diferentes bancos de dados.

    Essa instrução SQL retorna o mês em que o dia seguinte está. No último dia do mês, o dia seguinte é o mês seguinte. Portanto, o datagroup será acionado. Para todos os outros dias, o dia seguinte está no mesmo mês, então o datagroup não é acionado.

  2. Selecione o datagroup em uma programação nova ou atual.

As programações baseadas em datagroups são enviadas somente após a conclusão do processo de regeneração para todas as TDPs que são persistidas com esse parâmetro de datagroup, garantindo que a entrega inclua os dados mais recentes.

Como usar um datagroup com TDPs em cascata

No caso de tabelas derivadas persistentes em cascata, em que uma tabela derivada persistente (TDP) é referenciada na definição de outra, é possível usar um datagroup para especificar uma estratégia de persistência para a cadeia de TDPs em cascata.

Por exemplo, aqui está parte de um arquivo modelo que define um datagroup chamado user_facts_etl e uma Análise chamada user_stuff. A Análise user_stuff persiste com o datagroup user_facts_etl:

datagroup: user_facts_etl {
  sql_trigger: SELECT max(ID) FROM etl_jobs ;;
}

explore: user_stuff {
  persist_with: user_facts_etl
  from: user_facts_pdt_1
  join: user_facts_pdt_2 {
    ...
  }
  ...
}

A Análise user_stuff une a visualização user_facts_pdt_1 com a visualização user_facts_pdt_2. Essas duas visualizações são baseadas em TDPs que usam o datagroup user_facts_etl como um gatilho de persistência. A tabela derivada user_facts_pdt_2 referencia a tabela derivada user_facts_pdt_1, então essas são TDPs em cascata. Confira parte do LookML dos arquivos de visualização dessas TDPs:

view: user_facts_pdt_1 {
  derived_table: {
    datagroup_trigger: user_facts_etl
    explore_source: users {
      column: customer_ID {field:users.id}
      column: city {field:users.city}
      ...
    }
  }
}

view: user_facts_pdt_2 {
  derived_table: {
    sql:
      SELECT ...
      FROM ${users_facts_pdt_1.SQL_TABLE_NAME} ;;
  datagroup_trigger: user_facts_etl
  }
}

Se você tiver TDPs em cascata, verifique se elas não têm políticas de armazenamento em cache de datagroup incompatíveis.

O regenerador do Looker verifica o status e inicia as recriações dessas TDPs da seguinte maneira:

  • Por padrão, o regenerador do Looker verifica a consulta sql_trigger do datagroup a cada cinco minutos. O administrador do Looker pode especificar esse intervalo usando a configuração Programação de manutenção de datagroup e TDP na conexão do banco de dados.
  • Se o valor retornado pela sql_trigger consulta for diferente do resultado da consulta na verificação anterior, o datagroup entrará no estado acionado. Neste exemplo, se a tabela etl_jobs tiver um novo valor ID, o datagroup user_facts_etl será acionado.

  • Depois que o datagroup user_facts_etl for acionado, o regenerador do Looker vai recriar todas as TDPs que usam o datagroup (ou seja, todas as TDPs definidas com datagroup_trigger: user_facts_etl). Neste exemplo, o regenerador recria user_facts_pdt_1 e, em seguida, user_facts_pdt_2.

    Quando as TDPs compartilham o mesmo datagroup_trigger, o regenerador recria as TDPs em ordem de dependência, primeiro criando tabelas referenciadas por outras tabelas. Consulte a página de documentação Tabelas derivadas no Looker para mais informações sobre como o Looker recria tabelas derivadas em cascata.

  • Quando o regenerador recria todas as TDPs no datagroup, ele retira o datagroup user_facts_etl do estado acionado.

  • Quando o datagroup user_facts_etl não estiver mais no estado acionado, o Looker vai redefinir o cache para todos os modelos e Análises que usam o datagroup user_facts_etl (ou seja, todos os modelos e Análises definidos com persist_with: user_facts_etl). Neste exemplo, isso significa que o Looker redefine o cache para a Análise user_stuff.

  • Todas as entregas de conteúdo programadas que são baseadas no datagroup user_facts_etl serão enviadas. Neste exemplo, se houver uma entrega programada que inclua uma consulta da Análise user_stuff, a consulta programada será recuperada do banco de dados para receber resultados atualizados.

Como compartilhar datagroups em arquivos de modelo

Este exemplo mostra como compartilhar datagroups com vários arquivos de modelo. Essa abordagem é vantajosa porque, se você precisar editar um datagroup, só precisará editar o datagroup em um lugar para que essas mudanças entrem em vigor em todos os modelos.

Para compartilhar datagroups com vários arquivos de modelo, primeiro crie um arquivo separado que contenha apenas os datagroups e, em seguida, use o include parâmetro para include o arquivo de datagroups nos arquivos de modelo.

Como criar um arquivo de datagroups

Crie um arquivo .lkml separado para conter seus datagroups. É possível criar um arquivo de datagroup .lkml da mesma forma que você pode criar um arquivo do Explore .lkml separado.

Neste exemplo, o arquivo de datagroups é chamado de datagroups.lkml:

datagroup: daily {
 max_cache_age: "24 hours"
 sql_trigger: SELECT CURRENT_DATE();;
}

Como incluir o arquivo de datagroups nos arquivos de modelo

Agora que você criou o arquivo de datagroups, é possível include nos dois modelos e usar persist_with, seja para aplicar o datagroup a Análises individuais nos modelos ou para aplicar o datagroup a todas as Análises em um modelo.

Por exemplo, os dois arquivos de modelo a seguir include o arquivo datagroups.lkml.

Esse arquivo é chamado de ecommerce.model.lkml. O datagroup daily é usado no nível explore para que seja aplicado apenas à Análise orders:

include: "datagroups.lkml"

connection: "database1"

explore: orders {
  persist_with: daily
}

O próximo arquivo é chamado de inventory.model.lkml. O datagroup daily é usado no nível model para que seja aplicado a todas as Análises no arquivo de modelo:

include: "datagroups.lkml"
connection: "database2"
persist_with: daily

explore: items {
}

explore: products {
}