Personalizar blocos do Looker

Esta página oferece uma visão geral das práticas recomendadas e exemplos de como adaptar os seguintes blocos do Looker do Cortex Framework aos seus requisitos de negócios específicos:

Instalação

É possível instalar os blocos do Looker do Cortex Framework de algumas maneiras, conforme detalhado na documentação Implantar blocos do Looker. No entanto, recomendamos fazer um fork do repositório como o método mais simples para personalizar blocos de acordo com as necessidades da sua empresa.

Os blocos do Looker do Cortex Framework foram criados em uma abordagem em camadas em que cada camada adiciona uma parte incremental da lógica à camada anterior:

Camada de base: visualizações do LookML geradas por máquina que referenciam tabelas de origem.
Camada principal: mudanças manuscritas que adicionam novos campos ou modificam campos da camada de base.
Camada lógica: definições de análise e junções em diferentes visualizações.

O uso de refinamentos é fundamental para essa abordagem em camadas e para a personalização. Para seguir o princípio DRY (Não se repita), as extensões e constantes são aproveitadas. O conteúdo dinâmico para rótulos, instruções SQL, HTML e propriedades de link é gerado usando a linguagem de modelo Liquid.

Práticas recomendadas gerais do Google:

Organização de arquivos e pastas

No Looker Block, cada pasta representa uma coleção de tipos de objetos (como visualizações, Análises, dashboards e outros). Cada objeto individual é definido em um arquivo separado. A raiz do projeto contém os seguintes arquivos principais:

Arquivo .model
Arquivo de manifesto
README e outros arquivos Markdown
Arquivos do Marketplace (se o bloco também estiver disponível no Marketplace do Looker)

Navegador de arquivos

Figura 1. Exemplo de organização de pastas no Looker Block.

Modelo

O gerenciamento modular de arquivos torna o arquivo model do projeto mais enxuto com os seguintes parâmetros:

conexão
include

Os tipos de arquivos incluídos são os seguintes:
- Components (grupos de dados, named_value_formats quando relevante)
- Análises (as análises não são definidas no arquivo modelo)
- Dashboards

As instruções include para as visualizações usadas no block são definidas em cada arquivo do Explore individual, e não neste local, como mostra o exemplo a seguir:

connection: "@{CONNECTION_NAME}"

include: "/components/**/*.lkml"
include: "/explores/**/*.explore"
include: "/dashboards/**/*.dashboard"

Manifesto

O arquivo de manifesto especifica as constantes referenciadas em um projeto. Confira alguns exemplos das constantes usadas nos nossos blocos:

Nome da conexão
ID do projeto
Conjunto de dados de relatórios

Os blocos do Looker do Cortex Framework também usam constantes para definir o seguinte:

Rótulos de visualização
Rótulos de campo
Formatos HTML
Links de URL
Nomes dos painéis

Analise as constantes definidas para o Looker Block e modifique os valores para atender às suas necessidades. As mudanças são aplicadas em qualquer lugar em que a constante seja referenciada.

Atributos do usuário

Alguns blocos do Looker exigem que os atributos do usuário sejam definidos na instância do Looker por um administrador. Esses atributos de usuário para idioma ou moeda padrão permitem personalizar a forma como os painéis são exibidos por usuário ou grupo. Consulte a visão geral de cada bloco para mais informações sobre os atributos de usuário necessários.

Visualizações

As visualizações encontradas na pasta "Base" são geradas automaticamente usando a opção "Criar visualização da tabela". Esses arquivos foram alterados minimamente:

Substituímos o ID do projeto e o nome do conjunto de dados por constantes.
Movemos as visualizações com base em registros aninhados para arquivos separados.
Removemos todas as definições de campo de detalhamento desnecessárias.

Modificações significativas dessas visualizações, como rótulos, novas dimensões e métricas, foram criadas na pasta Core usando refinamentos, extensões ou tabelas derivadas.

Na pasta principal, as visualizações são nomeadas com um sufixo que indica o tipo de visualização:

_rfn para refinamento.
_ext para visualização que exige extensão.
_sdt para tabela derivada com base em SQL.
_ndt para tabela derivada nativa.
_pdt para tabela derivada persistente.
_xvw para visualização que referencia campos de várias visualizações.

Exemplo de sufixo

Figura 2. Exemplo de sufixo que indica o tipo de visualização.

Cada definição de visualização começa com anotações que fornecem informações de contexto, incluindo descrições, fontes, referências, campos estendidos e outras observações relevantes.

Anotações

Figura 3. Exemplo de anotações em uma definição de visualização.

Registros repetidos aninhados

Para tabelas subjacentes que contêm registros repetidos aninhados, o Looker cria visualizações separadas para desagrupar esses registros. Por exemplo, no Looker Block do Oracle EBS, a tabela sales_orders tem uma estrutura repetida aninhada chamada lines. O Looker trata esses registros como duas visualizações distintas: sales_orders e sales_orders__lines.

Para unir esses registros desagrupados na análise, defina a junção usando a propriedade sql em conjunto com o comando UNNEST.

Comando UNNEST

Figura 4. Exemplo de junção usando a propriedade "sql" em conjunto com o comando UNNEST.

Para mais informações, consulte Como modelar dados aninhados do BigQuery no Looker.

Como navegar e entender o código do Looker Block

Os blocos do Looker do Cortex Framework contêm comentários extensos nas visualizações e em outros objetos. Para melhorar a navegação e a compreensão do código, recomendamos usar a opção "Dobrar LookML" disponível no ambiente de desenvolvimento do LookML.

Dobrar LookML

Figura 5. Como clicar em "Dobrar LookML".

Desdobrar o LookML

Figura 6. Como clicar para desdobrar o LookML.

Dobre de novo

Figura 7. Como clicar para dobrar o LookML novamente.

Campos

O termo field se refere a objetos como dimension, measure, filter ou parameter. Nesses blocos mais recentes, seguimos estes princípios:

As dimensões são nomeadas usando snake_case (minúsculas e sublinhado entre as palavras). Por exemplo: customer_name.
Os nomes das colunas das tabelas subjacentes são usados para nomear dimensões. Os rótulos podem ser aplicados às dimensões para fornecer um nome adequado aos negócios. Por exemplo, uma dimensão chamada division_hdr_spart pode ser rotulada como "ID da divisão".
Para tabelas com muitas colunas, os campos ficam ocultos por padrão. Usando um refinamento da visualização, defina a propriedade hidden como "no" para o subconjunto de campos a serem exibidos em uma análise. Se um campo não aparecer como esperado, editar essa propriedade de campo poderá resolver o problema.
As propriedades View_label e group_label são usadas para organizar campos em uma análise, quando aplicável.
Para campos usados em várias visualizações, propriedades como o rótulo são estabelecidas em uma visualização "comum", que é estendida para outras visualizações. Essa abordagem centraliza a definição da propriedade, promovendo a reutilização. Todas as modificações necessárias são gerenciadas na visualização "comum", garantindo que as mudanças sejam refletidas em todas as visualizações em que a visualização "comum" é estendida.
Os parâmetros usados em várias análises ou campos que referenciam várias visualizações são definidos em uma visualização somente de campo com o sufixo _xvw. Para mais informações, consulte Como evitar inconsistências nas análises.

Exemplos de edição

Esta seção fornece exemplos de personalizações comuns.

Como mostrar um campo

A visualização de base abrange todas as dimensões de uma tabela subjacente. Quando a maioria das dimensões não precisa ficar visível, um refinamento é usado para ocultar todos os campos por padrão. Isso é feito definindo a propriedade fields_hidden_by_default como "yes". O subconjunto de campos relevantes para os painéis do LookML incluídos foi mostrado. O exemplo a seguir considera uma visualização de base chamada sales_orders com uma dimensão chamada item_posnr.

view: sales_order {
  sql_table_name: reporting.sales_order ;;

  dimension: item_posnr {
    type: string
    sql: ${TABLE}.Item_POSNR
  }
}

O refinamento dessa visualização é definido no arquivo com o sufixo _rfn. O refinamento define a propriedade de visualização fields_hidden_by_default como "yes", o que significa que todos os campos ficam ocultos inicialmente. Para mostrar o campo item_posnr na visualização, defina a propriedade oculta como "no".

view: +sales_order {
   fields_hidden_by_default: yes

   dimension: item_posnr {
     hidden: no
   }
}

Como mudar o rótulo da visualização de parâmetros

Vários blocos do Looker usam um conjunto compartilhado de parâmetros definidos em um arquivo independente. Por exemplo, o bloco do Oracle EBS usa o arquivo otc_common_parameters_xvw. Essa visualização mostra o rótulo "🔍 Filtros", que é definido como uma constante no arquivo de manifesto.

Para modificar esse rótulo:

Localize a constante label_view_for_filters no arquivo de manifesto.
Edite o valor da constante para o rótulo escolhido.
Salve o arquivo de manifesto. A mudança será refletida automaticamente em qualquer lugar em que a constante label_view_for_filters seja referenciada.

Manifest

constant: label_view_for_filters {
  value: "My Filters"
}

Como alternativa, navegue até a visualização otc_common_parameters_xvw e edite a propriedade "label" para o valor escolhido.

view: otc_common_parameters_xvw {
  label: "My Filters"
}

Como adicionar uma nova métrica

Novas métricas podem ser adicionadas diretamente ao refinamento relevante. O exemplo a seguir mostra uma nova métrica adicionada ao refinamento de pedidos de venda:

view: +sales_orders {

  measure: customer_count {
    type: count_distinct
    sql: ${customer_id}
   }
}

Como adicionar uma segunda camada de refinamento

Novos refinamentos podem ser criados com base em refinamentos atuais. Considere o refinamento de sales_orders no arquivo sales_orders_rfn.view, que cria a métrica average_sales como o exemplo a seguir:

include: "/views/base/sales_orders"
view: +sales_orders {
  measure: average_sales {
    type: average
    sql: ${order_value}
  }
}

Para criar um segundo arquivo de refinamento:

Crie um novo arquivo de refinamento: nomeie-o como sales_orders_rfn2.view.
Inclua o primeiro arquivo de refinamento: isso vai incorporar todas as definições de sales_orders_rfn em sales_orders_rfn2.
Edite a propriedade de rótulo: mude a propriedade label de average_sales para "gasto médio" ou qualquer outro rótulo escolhido.

Adicione uma nova dimensão: inclua o código da nova dimensão em o arquivo sales_orders_rfn2.view.

include: "/views/core/sales_orders_rfn.view"
view: +sales_orders {

  measure: average_sales {
    label: "Average Spend"
  }

  dimension: customer_name_with_id {
    type: string
    sql: CONCAT(${customer_id},' ',${customer_name})
  }
}

Inclua o segundo arquivo de refinamento na análise: isso vai incorporar todas as definições e melhorias de sales_orders_rfn2 na análise.
```
include: "/views/core/sales_orders_rfn2.view"
explore: sales_orders {
}
```

Como criar uma nova camada de refinamento

O refinamento de qualquer visualização de base definida no Looker Block do Cortex Framework pode ser substituído se não atender aos seus requisitos específicos. O arquivo _rfn pode ser editado diretamente para remover definições de campo desnecessárias ou adicionar novas.

Como alternativa, crie um novo arquivo de refinamento:

Crie um novo arquivo de refinamento: nomeie-o como sales_invoices_rfn e salve-o.
Inclua a visualização de base: isso vai incorporar todas as definições da visualização de base sales_invoices em sales_invoices_rfn.

Adicione as personalizações escolhidas: defina também uma dimensão como chave primária.

include: "/views/base/sales_invoices.view"

view: +sales_invoices {

  fields_hidden_by_default: yes

  dimension: invoice_id {
    hidden: no
    primary_key: yes
    value_format_name: id
  }

  dimension: business_unit_name {
    hidden: no
    sql: CONCAT(${business_unit_id}, ":",${TABLE}.BUSINESS_UNIT_NAME) ;;
  }
}

Inclua o novo refinamento na Análise: use o novo arquivo na propriedade include em vez do refinamento fornecido no Looker Block do Cortex Framework.
```
include: "/views/my_customizations/sales_invoices_rfn.view"

explore: sales_invoices {
}
```

Como editar filtros de painel do LookML

O conjunto comum de filtros de painel usado em vários painéis do LookML é definido em um painel nomeado com o sufixo _template e estendido para cada painel. Depois de estendido, os objetos de filtro podem ser modificados conforme necessário para um painel específico.

Como editar todos os painéis

Para mudar o tipo de filtro de todos os painéis, localize o arquivo de modelo que define o filtro. Edite o tipo ui_config e mostre as propriedades para as configurações escolhidas. Essa mudança será aplicada a todos os painéis que estendem o modelo. Confira a seguir um exemplo de otc_template.dashboard:

- dashboard: otc_template
  extension: required

  filters:
  - name: customer_country
    title: "Sold to Customer: Country"
    type: field_filter
    default_value: ''
    allow_multiple_values: true
    required: false
    ui_config:
      type: dropdown_menu
      display: popover
    explore: countries_md
    field: countries_md.country_name_landx

Como editar um painel específico

Para modificar um filtro em um dashboard específico, localize o arquivo do dashboard e inclua o nome do filtro com as propriedades de seleção que exigem modificação. Essa mudança será limitada ao painel único. Por exemplo, para mudar o título, o tipo de UI e a exibição do filtro customer_country para o otc_order_status.dashboard, apenas essas propriedades seriam incluídas no arquivo do painel. As propriedades restantes seriam herdadas do modelo estendido.

- dashboard: otc_order_status
  title: Order Status
  extends: otc_template

  filters:
  - name: customer_country
    title: "Customer Country"
    ui_config:
      type: dropdown_menu
      display: inline

Para mais informações sobre como criar e modificar painéis do LookML, consulte Como criar painéis do LookML.