Refinamentos do LookML

Informações gerais

Com os refinamentos do LookML, você pode adaptar uma visualização ou exploração já existentes sem precisar editar o arquivo LookML que o contém. Isso é ideal para:

Por exemplo, se você tiver o seguinte arquivo de visualização no seu projeto:

view: flights {
  sql_table_name: flightstats.accidents ;;

  dimension: id {
    label: "id"
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }
}

Você pode refinar a visualização flights como mostrado abaixo: use o parâmetro view com o mesmo nome de visualização, mas adicione um sinal de adição (+) na frente do nome para indicar que se trata de um refinamento de uma visualização existente.

Esse refinamento adiciona uma dimensão air_carrier à visualização flights:

view: +flights {
  dimension: air_carrier {
    type: string
    sql: ${TABLE}.air_carrier ;;
  }
 }

Esse refinamento pode ser colocado em qualquer arquivo LookML no projeto, como um arquivo de modelo, um arquivo de visualização ou seu próprio arquivo LookML dedicado. Consulte a seção Como usar refinamentos no seu projeto do LookML para saber como ele funciona.

O refinamento combinado com o LookML original tem o resultado final, como se fosse o LookML original da visualização:

view: flights {
  sql_table_name: flightstats.accidents ;;

  dimension: id {
    label: "id"
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }

  dimension: air_carrier {
    type: string
    sql: ${TABLE}.air_carrier ;;
  }
}

Na IU do Looker, os usuários verão a dimensão Air Carrier, como se você tivesse adicionado a dimensão ao próprio arquivo de visualização.

Veja o exemplo abaixo para informações de implementação mais detalhadas.

Refinamentos em comparação com extensões

O Looker também é compatível com a extensão de objetos LookML. A extensão é útil para criar uma nova cópia de uma visualização existente ou "Explorar" para adicionar novos objetos a ela. Por exemplo, você pode criar uma visualização base que defina todos os seus campos e, em seguida, várias visualizações novas que estendam a visualização base. Essas novas visualizações podem ser modificadas para ocultar determinados campos na visualização base ou para alterar definições ou marcadores dos campos da visualização base.

Os refinamentos são úteis quando você deseja modificar uma visualização existente ou "Explorar" com alguns ajustes ou ajustes em determinados objetos, mas não quer criar cópias da visualização ou explorar. Eles são ideais para situações em que não é possível modificar a visualização base ou "Explorar", e para criar uma nova visualização ou "Explorar" que exigem mudanças significativas em outras referências do LookML. Consulte a seção Exemplo nesta página para ver um exemplo desse caso de uso.

Para a maioria dos casos de uso, os refinamentos são uma alternativa mais simples e limpa para extends.

Os desenvolvedores avançados do LookML podem usar o parâmetro extends dentro de um refinamento do LookML. Consulte a seção Os refinamentos podem conter extensões desta página para obter mais informações.

Os refinamentos substituem a maioria dos parâmetros

É importante observar que, na maioria dos casos, um refinamento modifica as configurações originais de um objeto. No exemplo a seguir, a visualização original tem uma dimensão oculta (hidden: yes):

view: faa_flights {
  dimension: carrier {
    hidden: yes
  }
}

Em outro arquivo, há um refinamento nessa dimensão com hidden: no:


include: "/views/faa_flights.view.lkml"

view: +faa_flights {
  dimension: carrier {
    hidden: no
  }
}

O último refinamento tem precedência. Portanto, hidden: no é aplicado e a dimensão será exibida na visualização final.

Em alguns casos, os refinamentos são aditivos em vez de substituídos. Consulte a seção Alguns parâmetros são aditivos para mais informações.

Alguns parâmetros são aditivos

Em muitos casos, se o refinamento contiver o mesmo parâmetro que o objeto que está sendo refinado, o refinamento substituirá os valores de parâmetro do objeto refinado.

No entanto, os refinamentos podem ser aditivos para alguns parâmetros, o que significa que os valores do objeto base são usados em conjunto com os do objeto refinado.

Os seguintes parâmetros são aditivos:

Por exemplo, veja uma visualização que tem uma dimensão name com um parâmetro link:

view: carriers {
  sql_table_name: flightstats.carriers ;;

  dimension: name {
    sql: ${TABLE}.name ;;
    type: string
    link: {
      label: "Google {{ value }}"
      url: "http://www.google.com/search?q={{ value }}"
      icon_url: "http://google.com/favicon.ico"
    }
  }
}

Veja um refinamento da visualização carriers, com uma dimensão name que tem valores diferentes para o parâmetro link:


include: "/views/carriers.view.lkml"

view: +carriers {
  label: "Refined carriers"

  dimension: name {
    sql: ${TABLE}.name ;;
    type: string
    link: {
      label: "Dashboard for {{ value }}"
      url: "https://docsexamples.dev.looker.com/dashboards/307?Carrier={{ value }}"
      icon_url: "https://www.looker.com/favicon.ico"
    }
  }
}

Na visualização carriers refinada, os dois parâmetros link são aditivos. Portanto, a dimensão name exibirá os dois links.

Os refinamentos são aplicados em ordem

Um objeto pode ser refinado várias vezes e em vários lugares, o que permite aos desenvolvedores do Looker usar refinamentos de várias maneiras criativas. Mas isso também significa que os desenvolvedores precisam estar muito atentos à ordem em que os refinamentos são aplicados:

  • Em um projeto, os refinamentos são aplicados na ordem em que seus arquivos são incluídos. Os refinamentos dos arquivos incluídos por último substituirão os refinamentos dos arquivos incluídos anteriormente.
  • Em um único arquivo, os refinamentos são aplicados linha por linha para baixo. Os refinamentos com o maior número de linha são aplicados por último e substituirão qualquer refinamento anterior, se houver conflitos.

Por exemplo, no arquivo de visualização a seguir, há dois refinamentos da visualização faa_flights. O primeiro refinamento oculta uma dimensão (hidden: yes), e o segundo exibe a dimensão (hidden: no). Quando há conflitos como esse, o refinamento mais abaixo no arquivo tem precedência: 

include: "//e_faa_original/views/faa_flights.view.lkml"

view: +faa_flights {
  dimension: carrier {
    hidden: yes
  }
}

view: +faa_flights {
  dimension: carrier {
    hidden: no
  }
}

A lógica é semelhante para incluir vários arquivos em um projeto: os refinamentos no último arquivo listado nas inclusões terão prioridade. Por exemplo, se um arquivo de modelo incluir estes arquivos:

include: "/refinements/distance_analysis.lkml"
include: "/refinements/finishing_touches.lkml"

Todos os refinamentos no distance_analysis.lkml serão aplicados primeiro e os refinamentos no arquivo finishing_touches.lkml serão aplicados primeiro. Se houver algum conflito, os refinamentos no último arquivo, finishing_touches.lkml, terão precedência.

Como usar final: yes para evitar mais refinamentos

Conforme descrito anteriormente, o mesmo objeto pode ser refinado várias vezes em vários lugares, e o último refinamento modifica todos os refinamentos anteriores.

Se você quer que um refinamento seja considerado o refinamento final da visualização ou da exploração, adicione a sinalização final: yes ao refinamento. O ambiente de desenvolvimento integrado do Looker retornará um erro de LookML se houver refinamentos existentes que seriam aplicados depois do refinamento final ou se um desenvolvedor tentar adicionar um novo refinamento que seria aplicado depois dele. Por exemplo, o segundo refinamento nesse arquivo de visualização criaria um erro de LookML porque o refinamento anterior tem a sinalização final: yes:

include: "//e_faa_original/views/faa_flights.view.lkml"

view: +faa_flights {
  final: yes
  dimension: carrier {
    hidden: yes
  }
}

view: +faa_flights {
  dimension: carrier {
    hidden: no
  }
}

Adicionar a sinalização final: yes a um refinamento é uma boa maneira de verificar se os refinamentos estão sendo aplicados na ordem pretendida.

Os refinamentos podem conter extensões

Os desenvolvedores avançados do LookML podem usar um parâmetro extends dentro de um refinamento do LookML, que adiciona o objeto estendido ao objeto que está sendo refinado.

Para resumir o comportamento de extends e refinamentos:

  • Estender um objeto cria uma nova cópia do objeto e a partir dele. Por exemplo, você pode criar uma visualização base que defina todos os seus campos e, em seguida, várias visualizações novas que estendam a visualização base. Cada uma dessas novas visualizações incorporará uma cópia da visualização base e, a partir daí, um desenvolvedor pode adicionar diferentes campos, filtros ou outras propriedades para modificar o que está na visualização base. A ideia é começar com um objeto base e usá-lo de maneiras diferentes em vários outros objetos. Você pode ver a página de documentação Reutilização de código com extensões para ver uma discussão completa sobre como trabalhar com extensões.
  • Refinar um objeto adiciona uma camada de modificações ao objeto, mas, ao contrário da extensão, refinar não faz várias cópias do objeto. A ideia é criar com base em um objeto base sem modificar seu LookML original.

Como um exemplo do uso padrão dos refinamentos, veja uma exploração chamada orders e a exploração +orders que a refina:

explore: orders {
  view_name: orders
  # other Explore parameters
}

explore: +orders {
  label: "Orders Information"
  # other Explore parameters to build on the original Explore
}

Além disso, é possível adicionar um refinamento que inclui um extends. Com base no exemplo, veja a mesma seção "Explorar" do orders. Além disso, há uma exploração básica chamada users_base, e agora o refinamento +orders tem um parâmetro extends que traz o users_base:


explore: users_base {
  view_name: users
  extension: required
  # other Explore parameters
}

explore: orders {
  view_name: orders
  # other Explore parameters
}

explore: +orders {
  label: "Orders Information"
  extends: [users_base]
  # other Explore parameters to build on the original Explore
}

O que é especial aqui é que o refinamento +orders tem um extends. O resultado é que a visualização +orders ampliará a visualização users_base.

Como o Looker implementa o extends nos refinamentos

Estender um objeto dentro de um refinamento é um conceito avançado do LookML. Antes de usar o extends em um refinamento, você precisa ter um entendimento profundo do seguinte:

  • Como o Looker implementa extends: se um elemento LookML é definido no objeto estendidoed e no objeto extensão, a versão no objeto estendido é usada, a menos que o parâmetro seja additive. Consulte a página de documentação Reutilização de código com extensões para mais detalhes.
  • Como o Looker implementa refinamentos: se um elemento LookML é definido em vários refinamentos, o último refinamento substitui os refinamentos anteriores. Consulte a seção Os refinamentos são aplicados em ordem nesta página para obter mais detalhes.

Por fim, você precisa entender como o Looker combina esses princípios para implementar o extends usado nos refinamentos. Esta é a ordem que o Looker implementa, com cada etapa substituindo a anterior em caso de conflito:

  1. Valores de extends especificados no objeto
  2. Valores de extends especificados em refinamentos do objeto
  3. Valores do objeto
  4. Valores dos refinamentos do objeto

Para ilustrar, veja um exemplo que segue o valor do parâmetro label em cada etapa da implementação:

explore: orders_base {
  label: "Orders Base"
  view_name: orders
  extension: required
}

explore: users_base {
  label: "Users Base"
  view_name: users
  extension: required
}

explore: orders {
  label: "Orders"
  extends: [orders_base]
}

explore: +orders {
  label: "Orders Refined"
  extends: [users_base]
}

Veja como o Looker implementa o valor de label para a exploração orders neste exemplo:

  1. Valores do extends especificado no objeto. Como a exploração orders tem um parâmetro extends, o Looker começa com os elementos LookML do objeto que está sendo estendido. Neste caso, a exploração orders_base. Neste ponto, o valor de label é "Base de pedidos".
  2. Valores do extends especificado nos refinamentos do objeto. Como orders tem um refinamento e o parâmetro tem um parâmetro extends, o Looker aplica elementos LookML da extensão do refinamento, que, neste caso, é a exploração users_base. Neste ponto, o valor de label é "Base de usuários".
  3. Valores do objeto. Agora que todas as extensões foram abordadas, o Looker aplica elementos do objeto de extensão, que, neste caso, é a exploração orders. Se houver conflitos, o objeto de extensão vencerá. Agora, o valor de label é "Orders".
  4. Valores dos refinamentos do objeto. Por fim, o Looker aplica elementos de qualquer refinamento da ferramenta Explorar orders. Se houver conflitos, o objeto de refinamento vencerá. Então, agora o valor label é "Pedidos refinados".

Os refinamentos extends são aditivos

Conforme descrito na seção Parâmetros de modificação de refinamentos nesta página, os refinamentos normalmente substituem as configurações originais de um objeto. Esse não é o caso do parâmetro extends. Quando extends é usado em um refinamento, o valor no parâmetro extends é anexado à lista de itens estendidos no objeto original ou em refinamentos anteriores, se houver. Se houver algum conflito, a prioridade será dada ao último item na cadeia de estende.

Por exemplo, aqui está uma exploração básica chamada orders_base e uma exploração orders que estende a base. Além disso, há uma exploração users_base e o refinamento +orders que estende o users_base:

explore: orders_base {
  view_name: orders
  extension: required
  # other Explore parameters
}

explore: users_base {
  view_name: users
  extension: required
  # other Explore parameters
}

explore: orders {
  extends: [orders_base]
  # other Explore parameters to build on the base Explore
}

explore: +orders {
  extends: [users_base]
  # other Explore parameters to build on the base Explores
}

A exploração orders estende o orders_base, e os refinamentos +orders adicionam o users_base à lista extends. O resultado é que o +orders vai ampliar o orders_base e o users_base, como se fosse o LookML original dele:

explore: orders {
  extends: [orders_base, users_base]
}

Se houver algum conflito, a prioridade será dada ao último item na cadeia de estende. Nesse exemplo, os elementos em users_base substituem todos os elementos conflitantes em orders_base.

O conceito de extensão de mais de um objeto é discutido na página da documentação Como reutilizar código com extensões.

Uma última observação: neste exemplo, a ordem dos parâmetros explore não importa. Porém, em casos com vários refinamentos do mesmo objeto, a ordem dos refinamentos é importante. Conforme descrito na seção Os refinamentos são aplicados em ordem nesta página, o último refinamento em um arquivo substitui os refinamentos anteriores.

Como usar refinamentos no seu projeto LookML

Veja as etapas gerais para refinar visualizações e explorações no seu projeto:

  1. Identifique a visualização ou a exploração que você quer refinar.
  2. Decida onde você quer armazenar seus refinamentos. Você pode adicionar refinamentos a qualquer arquivo LookML existente ou pode criar arquivos LookML separados para seus refinamentos. Consulte o procedimento para criar um arquivo de teste de dados na página de documentação Como entender outros arquivos de projeto para ver um exemplo de como criar arquivos genéricos LookML.
  3. Use o parâmetro include para incorporar os refinamentos ao seu modelo:
    • No arquivo onde você escreve os refinamentos, é necessário incluir os arquivos do LookML que você está refinando. O ambiente de desenvolvimento integrado do Looker exibirá avisos se você tentar refinar um objeto que não está incluído.
    • No arquivo de modelo, inclua os arquivos em que seus refinamentos estão definidos. Você pode combinar arquivos e usar inclusões de maneiras muito criativas. Consulte a seção Como usar refinamentos para adicionar camadas ao seu modelo nesta página para obter detalhes.

Exemplo

Refinar objetos LookML é uma maneira fácil de adaptar visualizações e explorações sem precisar editar o LookML original. Isso é muito útil quando as visualizações e explorações são somente leitura no projeto, como nos arquivos importados de outros projetos. Veja um exemplo de como refinar uma exploração.

Veja o LookML para a exploração aircraft:


explore: aircraft {
  join: aircraft_types {
    type: left_outer
    sql_on: ${aircraft.id} = ${aircraft_types.id} ;;
    relationship: many_to_one
  }

  join: aircraft_engine_types {
    type: left_outer
    sql_on: ${aircraft.id} = ${aircraft_engine_types.id} ;;
    relationship: many_to_one
  }
}

Esta guia "Explorar" contém várias vistas, cada uma com muitas dimensões.

Agora, outro projeto do LookML chamado e_faa_refined importa o arquivo aircraft de exploração. No projeto e_faa_refined, é possível usar um refinamento para simplificar muito o aircraft Explore.

Como o aircraft "Explorar" é um arquivo importado, não é possível editá-lo diretamente. Em vez disso, você pode adicionar um refinamento. Veja um exemplo de um arquivo separado chamado refinements.lkml que contém este LookML:

include: "//e_faa_original/Explores/aircraft.explore.lkml"

explore: +aircraft {
  label: "Aircraft Simplified"
  fields: [aircraft.aircraft_serial, aircraft.name, aircraft.count]
}

O arquivo refinements.lkml contém o seguinte:

  • O parâmetro include para trazer o arquivo aircraft.explore.lkml original do projeto importado. Consulte a página de documentação Importação de arquivos de outros projetos para detalhes sobre como fazer referência aos arquivos de projeto importados.
  • Refinamentos para a exploração aircraft:
    • O sinal + na frente do nome "Explorar" indica um refinamento.
    • O parâmetro label altera o rótulo "Explorar" para "Aeronaves simplificadas".
    • O parâmetro fields especifica que apenas três campos serão exibidos em "Explorar".

O resultado final é como se essa fosse a visualização original de aircraft "Explorar" e aircraft:

explore: aircraft {
  label: "Aircraft Simplified"
  }

view: aircraft {
  sql_table_name: flightstats.aircraft ;;

  dimension: aircraft_serial {
    type: string
    sql: ${TABLE}.aircraft_serial ;;
  }

  dimension: name {
    type: string
    sql: ${TABLE}.name ;;
  }

  measure: count {
    type: count
  }
}

Para ver um exemplo de como usar refinamentos para personalizar uma única visualização para vários casos de uso, consulte o roteiro do manual Como maximizar a reutilização de código com DRY LookML: como personalizar uma visualização básica para vários casos de uso.

Outros casos de uso para refinamentos

Como mencionado anteriormente, os refinamentos são ideais para adaptar objetos LookML que são somente leitura, como Looker Blocks ou arquivos importados.

Mas, depois que você tiver uma ideia de como adicionar refinamentos e incluí-los nos modelos, é possível fazer coisas muito legais com seus projetos, conforme descrito nos exemplos a seguir.

Como usar refinamentos para adicionar análises

É possível usar refinamentos para adicionar análises ao modelo sem tocar nos arquivos LookML originais. Por exemplo, se houver um projeto em que as visualizações e explorações são geradas a partir de tabelas no seu banco de dados e armazenadas em um arquivo LookML chamado faa_basic.lkml, você pode criar um arquivo faa_analysis.lkml em que usa refinamentos para adicionar análises. Veja um exemplo de uma nova tabela derivada chamada distance_stats que tem uma análise de distância. Este exemplo mostra refinamentos da exploração flights atual do arquivo faa_basic.lkml, que mescla a tabela derivada distance_stats à exploração flights. Além disso, na parte inferior do exemplo, a visualização flights existente é refinada para adicionar novos campos da análise:

include: "faa_basic.lkml"

explore: +flights {
  join: distance_stats {
    relationship: one_to_one
    type: cross
  }
}

view: distance_stats {
  derived_table: {
    explore_source: flights {
      bind_all_filters: yes
      column: distance_avg {field:flights.distance_avg}
      column: distance_stddev {field:flights.distance_stddev}
    }
  }
  dimension: avg {
    type:number
    sql: CAST(${TABLE}.distance_avg as INT64) ;;
  }
  dimension: stddev {
    type:number
    sql: CAST(${TABLE}.distance_stddev as INT64) ;;
  }
}
view: +flights {
  measure: distance_avg {
    type: average
    sql: ${distance} ;;
  }
  measure: distance_stddev {
    type: number
    sql: STDDEV(${distance}) ;;
  }
  dimension: distance_tiered2 {
    type: tier
    sql: ${distance} ;;
    tiers: [500,1300]
  }
}

Como usar refinamentos para adicionar camadas ao seu modelo

Outro caso de uso interessante para refinamentos é adicionar camadas ao projeto. Você pode criar vários arquivos de refinamento e incluí-los estrategicamente para adicionar camadas.

Por exemplo, no projeto FAA, há um arquivo faa_raw.lkml que contém todas as visualizações e explorações geradas a partir de tabelas no seu banco de dados. Esse arquivo tem uma visualização para cada tabela no banco de dados, cada uma com uma dimensão para cada coluna do banco de dados.

Além do arquivo bruto, você pode criar um arquivo faa_basic.lkml para adicionar uma nova camada com refinamentos básicos, como adicionar junções a suas explorações ou adicionar medidas às suas visualizações, desta forma:

include: "faa_raw.lkml"

explore: +flights {
  join: carriers {
    sql_on: ${flights.carrier} = ${carriers.name} ;;
  }
}

view: +flights {
  measure: total_seats {
    type: sum
    sql: ${aircraft_models.seats} ;;
  }
}

É possível adicionar um arquivo faa_analysis.layer.lkml para adicionar uma nova camada com análises. Consulte a subseção Como usar refinamentos para adicionar análises para ver um exemplo de arquivo de análise.

A partir daí, basta incluir todos os arquivos de refinamento no arquivo de modelo. Também é possível usar o arquivo de modelo para adicionar refinamentos de modo que apontem suas visualizações para as tabelas de banco de dados que você quer referenciar:

connection: "publicdata_standard_sql"

include: "faa_raw.lkml"
include: "faa_basic.lkml"
include: "faa_analysis.lkml"

view: +flights {
  sql_table_name: lookerdata.faa.flights;;
}
view: +airports {
  sql_table_name: lookerdata.faa.airports;;
}
view: +aircraft {
  sql_table_name: lookerdata.faa.aircraft;;
}
view: +aircraft_models{
  sql_table_name: lookerdata.faa.aircraft_models;;
}
view: +carriers {
  sql_table_name: lookerdata.faa.carriers;;
}

Você pode duplicar esse arquivo de modelo e apontar para diferentes tabelas de banco de dados ou pode incluir diferentes arquivos de refinamento criados para definir outras camadas que você queira em seu modelo.

Como usar refinamentos para TDPs

Conforme descrito na seção Refinamentos em comparação com extensões nesta página, uma extensão cria uma nova cópia do objeto que está sendo estendido. No caso das tabelas derivadas permanentes (PDTs, na sigla em inglês), não use extensões, já que cada extensão cria uma nova cópia da tabela no banco de dados.

No entanto, é possível adicionar refinamentos à visualização do PDT, já que eles não criam uma nova cópia do objeto que está sendo refinado.

Como usar metadados para ver refinamentos para um objeto

É possível clicar em um parâmetro explore ou view no ambiente de desenvolvimento integrado do Looker e usar o painel de metadados para ver os refinamentos no objeto. Consulte a página de documentação Metadados para objetos LookML e veja mais informações.

Informações importantes

Projetos com localização

Ao refinar um objeto, lembre-se de que as regras de localização também se aplicam aos refinamentos. Se você estiver refinando um objeto e definindo novos rótulos ou descrições, forneça definições de localização nos arquivos de strings de localidade do seu projeto. Consulte a página de documentação Como localizar seu modelo do LookML para mais informações.