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 do seu grupo de dados, além de subparâmetros que definem as propriedades dele.

Definição

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

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

É possível adicionar um rótulo e uma descrição ao grupo de dados:

  • label: especifica um rótulo opcional para o grupo de dados. Consulte a seção label e description nesta página para mais detalhes.
  • description: especifica uma descrição opcional para o grupo de dados 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 vai enviá-la 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, o grupo de dados vai 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 grupo de dados, 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 um valor max_cache_age que invalide os dados antigos se a ETL falhar. O parâmetro max_cache_age garante que, se o cache de um grupo de dados não for limpo por sql_trigger ou interval_trigger, as entradas de cache vão expirar em um determinado momento. Assim, o modo de falha de um grupo de dados será consultar o banco de dados em vez de veicular dados desatualizados do cache do Looker.

Um grupo de dados não pode ter os parâmetros sql_trigger e interval_trigger. Se você definir um datagroup com os dois parâmetros, ele vai 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, crie uma conexão separada usando os campos de substituição de PDT se quiser definir uma política de cache de grupo de dados usando um gatilho de consulta SQL.

Sem as substituições de PDT, ainda é possível usar um datagroup para o modelo e as análises detalhadas, 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 que os resultados armazenados em cache podem ser usados pelas consultas do recurso Detalhar que usam o grupo de dados.

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 vai enviá-la 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, e não aciona a recriação das TDPs. Se você definir um datagroup apenas com max_cache_age, vai receber um aviso de validação do LookML se alguma tabela derivada for atribuída a ele. 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 a tabela derivada ficará no esquema de rascunho indefinidamente e nunca será recriada, mesmo que seja consultada novamente. Se a intenção for reconstruir uma PDT em um intervalo de tempo específico, adicione um parâmetro interval_trigger ao datagroup para definir uma programação de reconstrução de PDT.

Ao configurar max_cache_age para datagroups usados com estruturas de TDP profundamente aninhadas (cadeias de TDPs em cascata com vários níveis de dependências), verifique se o período de armazenamento do cache é longo o suficiente para evitar disputas durante a atualização. Consulte Práticas recomendadas para PDTs com aninhamento profundo para mais informações.

sql_trigger

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

Normalmente, sql_trigger especifica uma consulta SQL que indica quando uma nova carga de dados (ETL) ocorreu, por exemplo, consultando o max(ID) em uma tabela. Você também pode usar sql_trigger para especificar um determinado horário do dia. Para isso, consulte a data atual e adicione mais horas a esse carimbo de data/hora, conforme necessário, para chegar ao horário desejado, por exemplo, 4h.

Observe 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 acontece porque o Looker precisa de credenciais estáticas para acessar seu banco de dados e executar a consulta especificada no parâmetro sql_trigger. Quando as TDPs estão ativadas, você pode usar os campos Substituições de TDP para fornecer ao Looker credenciais de login estáticas e separadas para processos de TDP, mesmo que sua 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 estáticas necessárias para consultas sql_trigger.
  • O Looker não faz a conversão de fuso horário para sql_trigger. Se você quiser acionar seu grupo de dados em um horário específico do dia, defina o acionador no fuso horário em que seu banco de dados está configurado.

Confira estes exemplos da documentação do parâmetro sql_trigger para ter ideias sobre como configurar consultas SQL para acionar um grupo de dados.

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, transmita uma string que contenha 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 grupo de dados. Também é possível localizar esses subparâmetros usando arquivos de strings de localidade.

Esses subparâmetros são mostrados na página Grupos de dados, na seção Banco de dados do painel Administrador. Consulte a página de documentação Configurações de administrador - Grupos de dados para mais informações sobre como eles são exibidos.

Exemplos

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

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 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 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 são atualizados, essa consulta retorna um novo número.
  • Use a configuração max_cache_age para invalidar os dados se eles estiverem em cache há 24 horas.
  • Use os parâmetros opcionais label e description para adicionar um rótulo personalizado e uma descrição do grupo de dados.
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 as 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 cache orders_datagroup em uma Análise específica, adicione o parâmetro persist_with em explore e especifique orders_datagroup. Se houver um datagroup padrão especificado no nível do modelo, use o parâmetro persist_with em um 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 grupo de dados orders_datagroup na recriação de uma PDT, adicione datagroup_trigger ao parâmetro derived_table e especifique o orders_datagroup:

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

Criar um grupo de dados para programar entregas no último dia de cada mês

Você pode criar uma programação que envie uma entrega de conteúdo no fim de cada mês. No entanto, nem todos os meses têm o mesmo número de dias. Você pode criar um grupo de dados para acionar a entrega de conteúdo no fim de cada mês, independente do número de dias em um mês específico.

  1. Crie um grupo de dados 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 de amanhã. No último dia do mês, amanhã é o mês seguinte, então o grupo de dados será acionado. Em todos os outros dias, o dia seguinte está no mesmo mês, então o grupo de dados não é acionado.

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

Os programações baseadas em grupos de dados são enviadas somente depois que o processo de regeneração é concluído para todas as TDPs persistidas com esse parâmetro de grupo de dados, garantindo que a entrega inclua os dados mais recentes.

Como usar um grupo de dados com PDTs em cascata

No caso de tabelas derivadas em cascata persistentes, em que uma tabela derivada persistente (TDP) é referenciada na definição de outra, é possível usar um grupo de dados 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 user_stuff Análise detalhada é mantida 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 as visualizações user_facts_pdt_1 e user_facts_pdt_2. Ambas as visualizações são baseadas em PDTs que usam o grupo de dados user_facts_etl como um gatilho de persistência. A tabela derivada user_facts_pdt_2 faz referência à tabela derivada user_facts_pdt_1. Portanto, essas são TDPs em cascata. Confira parte da LookML dos arquivos de visualização para essas PDTs:

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 cache de grupo de dados incompatíveis.

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

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

  • Quando o datagroup user_facts_etl é acionado, o regenerador do Looker recria todas as PDTs que usam o datagroup (ou seja, todas as PDTs definidas com datagroup_trigger: user_facts_etl). Neste exemplo, o regenerador recria user_facts_pdt_1 e depois user_facts_pdt_2.

    Quando as TDPs compartilham o mesmo datagroup_trigger, o regenerador as recria por 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 grupo de dados, ele tira o grupo de dados user_facts_etl do estado acionado.

  • Quando o datagroup user_facts_etl não está mais no estado acionado, o Looker redefine o cache de 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 da Análise user_stuff.

  • Todas as entregas de conteúdo programadas baseadas no grupo de dados 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 gerar resultados atualizados.

Práticas recomendadas para PDTs com aninhamento profundo

Ao trabalhar com estruturas de PDT profundamente aninhadas (cadeias de PDTs em cascata com vários níveis de dependências), configurar períodos curtos de retenção de cache (por exemplo, 15 minutos) pode causar uma condição de disputa que resulta em um erro 409 Conflict durante a atualização.

Essa disputa ocorre porque o cache para TDPs aninhadas de nível inferior pode expirar enquanto os TDPs de nível superior ainda estão em processo de criação. Quando isso acontece, o Looker aciona uma nova solicitação de build duplicada para as PDTs de nível inferior enquanto o job inicial ainda está sendo processado no data warehouse, o que resulta no conflito.

Para resolver ou evitar esse erro, siga estas práticas recomendadas:

  • Aumente o período de armazenamento do cache:defina o período de armazenamento do cache (max_cache_age ou persist_for) para as TDPs em pelo menos duas a três vezes o tempo máximo necessário para concluir o build completo de todas as TDPs aninhadas.
  • Aumente o intervalo de atualização do datagroup:permita tempo suficiente para que os builds de PDTs profundamente aninhadas sejam concluídos, o que reduz o risco de processos de build sobrepostos.

Compartilhar grupos de dados entre arquivos de modelo

Este exemplo mostra como compartilhar grupos de dados com vários arquivos de modelo. Essa abordagem é vantajosa porque, se você precisar editar um grupo de dados, basta fazer isso em um só lugar para que as mudanças sejam aplicadas a todos os modelos.

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

Como criar um arquivo de datagroups

Crie um arquivo .lkml separado para conter seus grupos de dados. Você pode criar um arquivo de datagroup .lkml da mesma forma que cria um arquivo de Análise .lkml separado.

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

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

Incluir o arquivo datagroups nos arquivos do modelo

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

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

O nome do arquivo é 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 {
}