Personalizar blocos do Looker

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

Instalação

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

Os blocos de pesquisa do Cortex Framework foram criados em uma abordagem em camadas em que cada camada adiciona um fragmento incremental de lógica à camada anterior:

  • Camada de base: visualizações do LookML geradas por máquina que fazem referência a tabelas de origem.
  • Camada principal: mudanças manuscritas que adicionam novos campos ou modificam os campos da camada de base.
  • Camada lógica: conheça as definições e as mesclagens em diferentes visualizações.

O uso de refinamentos é fundamental para essa abordagem em camadas e para a personalização. E para seguir o princípio "não se repita" (DRY, na sigla em inglês), extensões e constantes são aproveitadas. O conteúdo dinâmico para rótulos, instruções SQL, propriedades html e de link é gerado usando a linguagem de modelos Liquid.

Práticas recomendadas gerais do Google:

Organização de arquivos e pastas

No Bloco do Looker, cada pasta representa uma coleção de tipos de objetos (como visualizações, análises, painéis e outros). E 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 bloco do Looker.

Modelo

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

  1. conexão

  2. include

    Os tipos de arquivos incluídos são os seguintes:

    • Componentes (grupos de dados, named_value_formats quando relevante)
    • Análises detalhadas (não são definidas no arquivo de modelo)
    • Painéis

As instruções include para as visualizações utilizadas no bloco são definidas em cada arquivo individual da Análise em vez de neste local, conforme mostrado neste exemplo:

connection: "@{CONNECTION_NAME}"

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

Manifesto

O arquivo de manifesto especifica as constantes referenciadas em todo um projeto. Confira alguns exemplos de constantes usadas nos 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:

  • Ver marcadores
  • Rótulos de campo
  • Formatos HTML
  • Links de URL
  • Nomes dos painéis

Analise as constantes definidas para o bloco Looker e modifique os valores de acordo com 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 um administrador defina atributos do usuário na instância do Looker. Esses atributos do usuário para o idioma ou a moeda padrão permitem personalizar a forma como os painéis são mostrados 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 a partir da tabela". Estes arquivos foram alterados minimamente:

  • Substituiu o ID do projeto e o nome do conjunto de dados por constantes.
  • As visualizações movidas com base em registros aninhados foram movidas para arquivos separados.
  • As definições de campo de detalhamento desnecessárias foram removidas.

Modificações significativas nessas visualizações, como rótulos, novas dimensões e medidas, 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 a tabela derivada persistente.
  • _xvw para campos de referência de várias visualizações.

Exemplo de sufixo

Figura 2. Exemplo de sufixo indicando 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 notas relevantes.

Anotações

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

Registros repetidos aninhados

Para tabelas principais com registros repetidos aninhados, o Looker cria visualizações separadas para desaninhar esses registros. Por exemplo, no bloco de busca do Oracle EBS, a tabela sales_orders tem uma estrutura repetida anexada chamada lines. O Looker trata essas como duas visualizações distintas: sales_orders e sales_orders__lines.

Para mesclar esses registros não aninhados na Análise detalhada, defina a mesclagem usando a propriedade sql com o comando UNNEST.

Comando UNNEST

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

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

Os blocos de visualização 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, é recomendável usar a opção de dobrar o LookML disponível no ambiente de desenvolvimento do LookML.

Dobrar o LookML

Figura 5. Clicar em "Dobrar o LookML".

Desdobrar o LookML

Figura 6. Clique para abrir o LookML.

Dobrar novamente

Figura 7. Clique para dobrar novamente o LookML.

Campos

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

  1. As dimensões são nomeadas usando snake_case (letras minúsculas e sublinhado entre palavras). Por exemplo, customer_name.
  2. Os nomes das colunas das tabelas são usados para nomear as dimensões. Os rótulos podem ser aplicados a dimensões para fornecer um nome amigável para empresas. Por exemplo, uma dimensão chamada division_hdr_spart pode ser rotulada como "ID da divisão".
  3. 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 que o subconjunto de campos seja mostrado em uma Análise. Se um campo não aparecer como esperado, editar essa propriedade pode resolver o problema.
  4. As propriedades View_label e group_label são usadas para organizar campos em uma Análise, quando aplicável.
  5. Para campos usados em várias visualizações, propriedades como rótulo são estabelecidas em uma visualização "comum", que é estendida posteriormente 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.
  6. Parâmetros usados em várias análises ou campos que fazem referência a 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 detalhadas.

Exemplos de edição

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

Mostrar um campo

A visualização básica inclui todas as dimensões de uma tabela subjacente. Quando a maioria das dimensões não precisa estar 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 desocultado. O exemplo a seguir considera uma visualização 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 "sim", o que significa que todos os campos são ocultos inicialmente. Para mostrar o campo item_posnr na visualização, defina a propriedade oculta como "não".

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 EBS do Oracle 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:

  1. Localize a constante label_view_for_filters no arquivo de manifesto.
  2. Edite o valor da constante para o rótulo escolhido.
  3. Salve o arquivo de manifesto. A mudança será refletida automaticamente sempre que a constante label_view_for_filters for 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 medida

Novas medidas podem ser adicionadas diretamente ao refinamento relevante. O exemplo a seguir mostra uma nova medida 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

É possível criar novos refinamentos com base nos já existentes. Considere o refinamento de sales_orders no arquivo sales_orders_rfn.view, que cria a medida average_sales, como no exemplo abaixo:

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

Para criar um segundo arquivo de refinamento:

  1. Crie um novo arquivo de refinamento: nomeie-o como sales_orders_rfn2.view.
  2. Incluir o primeiro arquivo de refinamento: isso vai incorporar todas as definições de sales_orders_rfn em sales_orders_rfn2.
  3. Editar a propriedade do rótulo: mude a propriedade label de average_sales para "gastos médios" ou qualquer outro rótulo escolhido.

  4. Adicionar uma nova dimensão: inclua o código da nova dimensão no 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})
  }
}

  5. Incluir o segundo arquivo de refinamento na seção "Explorar": isso vai incorporar todas as definições e melhorias de sales_orders_rfn2 na seção "Explorar".

    include: "/views/core/sales_orders_rfn2.view"
explore: sales_orders {
}

Criação de uma nova camada de refinamento

O refinamento de qualquer visualização base definida no bloco de pesquisa do Cortex Framework pode ser substituído se não atender aos 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:

  1. Crie um novo arquivo de refinamento: nomeie-o como sales_invoices_rfn e salve.
  2. Incluir a visualização básica:isso vai incorporar todas as definições da visualização básica sales_invoices em sales_invoices_rfn.

  3. Adicionar as personalizações escolhidas: defina 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) ;;
  }
}

  4. Incluir o novo refinamento na seção "Explorar": use o novo arquivo na propriedade include em vez do refinamento fornecido no bloco de pesquisa do Cortex Framework.

    include: "/views/my_customizations/sales_invoices_rfn.view"

explore: sales_invoices {
}

Editar filtros do dashboard do LookML

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

Edição para todos os painéis

Para mudar o tipo de filtro em 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 vai ser aplicada a todos os painéis que estendem o modelo. Confira abaixo 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 painel específico, localize o arquivo do painel e inclua o nome do filtro com as propriedades selecionadas que precisam de modificação. Essa mudança será limitada ao painel único. Por exemplo, para mudar o título e o tipo de interface 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.