Visão geral
Com os refinamentos do LookML, você pode adaptar uma visualização ou Explorar sem editar o arquivo do LookML que a contém. Isso é ideal para:
- Projetos com blocos do Looker, que usam partes pré-criadas do LookML
- Projetos que importam arquivos de outros projetos
- Projetos em que você precisa gerar arquivos com base em tabelas do banco de dados
- Situações em que você quer compartilhar o LookML entre modelos ou projetos enquanto faz personalizações em cada lugar (configurações hub e spoke)
Por exemplo, se você tiver o seguinte arquivo de visualização no 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
, conforme mostrado neste exemplo: 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.
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 do LookML no projeto, como um arquivo de modelo, de visualização ou no próprio arquivo do LookML. Consulte a seção Como usar refinamentos no seu projeto do LookML para saber como funciona.
O refinamento combinado com o LookML original gera o resultado final como se este 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 interface do Looker, os usuários vão encontrar a dimensão Air Carrier, como se você a tivesse adicionado ao arquivo de visualização original.
Consulte a seção Exemplo para mais informações detalhadas sobre a implementação.
Refinamentos comparados a extensões
O Looker também oferece suporte à extensão de objetos LookML. A extensão é útil quando você quer criar uma nova cópia de uma visualização já existente ou Explorar para adicionar novos objetos a ela. Por exemplo, você pode criar uma visualização base que define todos os campos e, em seguida, criar várias novas visualizações que estendem a base. Essas novas visualizações podem ser modificadas para ocultar determinados campos na visualização base ou para alterar definições ou rótulos dos campos da visualização base.
Os refinamentos são úteis quando você quer modificar uma visualização existente ou uma Análise com alguns ajustes em certos objetos, mas sem criar cópias deles. Os refinamentos são ideais para situações em que você não pode ou não quer modificar a visualização básica ou a Análise detalhada e para situações em que a criação de uma nova visualização ou Análise detalhada exigiria mudanças extensas em outras referências do LookML. Consulte a seção Exemplo nesta página para conferir um exemplo desse caso de uso.
Na maioria dos casos de uso, os refinamentos são uma alternativa mais simples e limpa do que extends
.
Os desenvolvedores avançados do LookML podem usar o parâmetro extends
em um refinamento do LookML. Consulte a seção Os refinamentos podem conter extensões nesta página para mais informações.
Os refinamentos substituem a maioria dos parâmetros
É importante observar que, na maioria dos casos, um refinamento sobrescreverá 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 dessa 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 é exibida na visualização final.
Em alguns casos, os refinamentos são aditivos em vez de substituir. Consulte a seção Alguns parâmetros são aditivos desta página para mais informações.
Alguns parâmetros são aditivos
Em muitos casos, se o refinamento tiver o mesmo parâmetro que o objeto a ser refinado, ele vai substituir os valores do 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 junto com os do objeto refinado.
Os parâmetros a seguir são aditivos:
Para dimensões e medições:
Para parâmetros:
Para tabelas derivadas:
Para visualizações:
extends
(consulte a seção O refinamentoextends
é aditivo nesta página para mais informações).
Para as Análises:
access_filter
aggregate_table
extends
Consulte a seção Refinamentoextends
são incrementais nesta página para mais informações.join
query
Por exemplo, esta é uma visualização com uma dimensão name
e 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"
}
}
}
Confira um refinamento na 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, então a dimensão name
vai mostrar 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 que os desenvolvedores do Looker usem refinamentos de muitas maneiras criativas. Mas isso também significa que os desenvolvedores precisam estar muito atentos à ordem em que os refinamentos são aplicados:
- Dentro de 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 vão substituir os refinamentos dos arquivos já incluídos.
- Em um único arquivo, os refinamentos são aplicados linha por linha em baixo. Os refinamentos com o número de linha mais alto são aplicados por último e substituem os refinamentos anteriores, se houver conflitos.
Por exemplo, no arquivo de visualização abaixo, há dois refinamentos da visualização faa_flights
. O primeiro refinamento oculta uma dimensão (hidden: yes
), e o segundo mostra 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 nos includes terão precedência. Por exemplo, se um arquivo de modelo incluir estes arquivos:
include: "/refinements/distance_analysis.lkml"
include: "/refinements/finishing_touches.lkml"
Os refinamentos no distance_analysis.lkml
serão aplicados primeiro, e depois os refinamentos no arquivo finishing_touches.lkml
. Se houver algum conflito, os refinamentos do ú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 diversos lugares, e o último refinamento substituirá todos os refinamentos anteriores.
Se você tem um refinamento e quer que ele seja considerado o refinamento final da visualização ou da Análise, adicione a sinalização final: yes
a ele. O ambiente de desenvolvimento integrado do Looker vai retornar um erro do LookML se houver refinamentos atuais que serão aplicados após esse refinamento final ou se um desenvolvedor tentar adicionar um novo refinamento. Por exemplo, a segunda refinação neste arquivo de visualização criaria um erro do LookML porque a refinação anterior tem a flag 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 flag final: yes
a um refinamento é uma boa maneira de verificar se os refinamentos estão sendo aplicados na ordem desejada.
Os refinamentos podem conter extensões
Os desenvolvedores avançados do LookML podem querer usar um parâmetro extends
em um refinamento do LookML, que adiciona o objeto estendido ao objeto que está sendo refinado.
Para resumir o comportamento de extends
e refinamentos:
- A extensão cria uma nova cópia do objeto e se baseia nela. Por exemplo, você pode criar uma visualização base que define todos os campos e, em seguida, criar várias novas visualizações que estendem a base. Cada uma dessas novas visualizações vai incorporar uma cópia da visualização básica, e a partir daí o desenvolvedor pode adicionar campos, filtros ou outras propriedades diferentes para modificar o que está na visualização básica. A ideia é começar com um objeto base e usá-lo de maneiras diferentes em vários outros objetos. Acesse a página de documentação Como reutilizar o código com extends para uma discussão completa sobre como trabalhar com extends.
- O refinamento de um objeto adiciona uma camada de modificações a ele, mas, ao contrário da extensão, o refinamento não faz várias cópias do objeto. A ideia é basear-se em um objeto base sem modificar o LookML original.
Como exemplo do uso padrão de refinamentos, esta é uma Análise chamada orders
e a Análise +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, você pode adicionar um refinamento que inclui um extends
. Com base no exemplo, temos a mesma Análise orders
. Além disso, há uma Análise 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
agora vai estender a guia users_base
"Explorar".
Como o Looker implementa o extends
nos refinamentos
Estender um objeto dentro de um refinamento é um conceito avançado do LookML. Antes de usar extends
em um refinamento, você precisa entender bem o seguinte:
- Como o Looker implementa o
extends
: se um elemento do LookML for definido tanto no objeto estendido quanto no de extensão, a versão no objeto expansível será usada, a menos que o parâmetro seja aditivo. Consulte a página de documentação Como reutilizar código com extends para mais detalhes. - Como o Looker implementa refinamentos: se um elemento do LookML for definido com vários refinamentos, o último vai substituir os anteriores. Consulte a seção Os refinamentos são aplicados em ordem nesta página para 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 conflitos:
- Valores do
extends
especificados no objeto - Valores do
extends
especificados nos refinamentos do objeto - Valores do objeto
- Valores dos refinamentos do objeto
Para ilustrar, confira 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]
}
Confira como o Looker implementa o valor de label
para a análise detalhada orders
neste exemplo:
- Valores do
extends
especificado no objeto. Como a Análiseorders
tem um parâmetroextends
, o Looker começa com os elementos do LookML do objeto que está sendo estendido, que neste caso é a Análiseorders_base
. Nesse ponto, o valor delabel
é "Orders Base". - Valores do
extends
especificados nos refinamentos do objeto. Comoorders
tem um refinamento e ele tem um parâmetroextends
, o Looker aplica elementos do LookML da extensão do refinamento, que neste caso é a Análiseusers_base
. Nesse ponto, o valor delabel
é "Base de usuários". - Valores do objeto. Agora que todas as extensões foram tratadas, o Looker aplica elementos do objeto de extensão, que neste caso é a Análise
orders
. Se houver conflitos, o objeto de extensão vai prevalecer. Agora, o valor delabel
é "Orders". - Valores dos refinamentos do objeto. Por fim, o Looker aplica elementos de qualquer refinamento da análise
orders
. Se houver algum conflito, o objeto de refinamento vencerá. Agora, o valor delabel
é "Orders Refined".
Os refinamentos extends
são cumulativos
Conforme descrito na seção Parâmetros de substituição de refinamentos desta página, os refinamentos geralmente 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. Então, se houver algum conflito, a prioridade será dada ao último item na cadeia de extensões.
Por exemplo, esta é uma Análise básica chamada orders_base
e uma Análise orders
que estende a base. Além disso, há uma seção "Explorar" users_base
e o refinamento +orders
que estende 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 Análise de orders
estende o orders_base
. Em seguida, os refinamentos +orders
adicionam o users_base
à lista de extends
. O resultado é que a análise +orders
vai estender orders_base
e users_base
, como se fosse o LookML original da análise:
explore: orders {
extends: [orders_base, users_base]
}
Então, se houver algum conflito, a prioridade será dada ao último item na cadeia de extensões. Nesse exemplo, os elementos em users_base
substituem os elementos em conflito em orders_base
.
O conceito de estender mais de um objeto por vez é discutido na página de documentação Reutilizar código com extensões.
Uma última observação: nesse exemplo, a ordem dos parâmetros explore
não importa. Mas, nos casos com vários refinamentos do mesmo objeto, a ordem deles é importante. Conforme descrito na seção Os refinamentos são aplicados em ordem desta página, o último refinamento em um arquivo substitui os refinamentos anteriores.
Como usar refinamentos no projeto do LookML
Estas são as etapas gerais para refinar visualizações e Análises no seu projeto:
- Identifique a visualização ou a seção "Explorar" que você quer refinar.
- Decida onde você deseja abrigar seus refinamentos. Você pode adicionar refinamentos a qualquer arquivo do LookML ou criar arquivos separados. Consulte o procedimento para criar um arquivo de teste de dados na página de documentação Como entender outros arquivos de projeto para conferir um exemplo de criação de arquivos genéricos do LookML.
- Use o parâmetro
include
para incorporar seus refinamentos ao modelo:- No arquivo em que você escreve os refinamentos, deve incluir os arquivos do LookML que está refinando. O Looker IDE vai mostrar avisos se você tentar refinar um objeto não incluído.
- No arquivo de modelo, inclua os arquivos em que os refinamentos sã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 mais detalhes.
Exemplo
Refinar objetos do LookML é uma maneira fácil de adaptar visualizações e análises detalhadas sem precisar editar o LookML original. Isso é muito útil quando as visualizações e as Análises estão no modo somente leitura no projeto, como no caso de arquivos importados de outros projetos. Este é um exemplo de como refinar uma Análise.
Este é o LookML da Análise 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
}
}
Essa Análise contém diversas visualizações, cada uma com muitas dimensões.
Agora, outro projeto do LookML chamado e_faa_refined
importa o arquivo aircraft
Explore. No projeto e_faa_refined
, você pode usar um refinamento para simplificar drasticamente a Análise do aircraft
.
Como o aircraft
Explore é um arquivo importado, não é possível editá-lo diretamente. Em vez disso, você pode adicionar um refinamento. Confira 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 arquivoaircraft.explore.lkml
original do projeto importado. Consulte a página de documentação Como importar arquivos de outros projetos para ver detalhes sobre como consultar arquivos de projetos importados. - Refinamentos na Análise de
aircraft
:
O resultado final é como se fosse a visualização original de aircraft
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 conferir um exemplo de como usar refinamentos para personalizar uma única visualização para vários casos de uso, consulte a receita do manual Maximizar a reutilização de código com o DRY LookML: personalizar uma única visualização de base para vários casos de uso.
Outros casos de uso para refinamentos
Como mencionado anteriormente, os refinamentos são ideais para adaptar objetos do LookML que são somente leitura, como blocos do Looker ou arquivos importados.
No entanto, depois de entender como adicionar refinamentos e incluí-los nos modelos, você poderá 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 originais do LookML. Por exemplo, em um projeto em que as visualizações e as Análises são geradas com base em tabelas do banco de dados e armazenadas em um arquivo do LookML chamado faa_basic.lkml
, você pode criar um arquivo faa_analysis.lkml
com refinamentos para adicionar análises. Confira um exemplo de uma nova tabela derivada chamada distance_stats
que tem uma análise de distância. Este exemplo mostra os refinamentos da Análise flights
atual do arquivo faa_basic.lkml
que combina a tabela derivada distance_stats
com a Análise flights
. Além disso, na parte de baixo do exemplo, a visualização flights
foi 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 modelo
Outro caso de uso interessante para refinamentos é adicionar camadas ao seu projeto. É possível criar vários arquivos de refinamento e incluí-los estrategicamente para acrescentar camadas.
Por exemplo, no projeto da FAA, há um arquivo faa_raw.lkml
que contém todas as visualizações e Análises geradas de tabelas no banco de dados. Esse arquivo tem uma visualização para cada tabela no banco de dados, cada uma com dimensões 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 mesclagens às suas Análises ou incluir 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} ;;
}
}
Em seguida, adicione um arquivo faa_analysis.layer.lkml
para adicionar uma nova camada com análises. Consulte a subseção Usar refinamentos para adicionar análises para conferir um exemplo de arquivo de análise.
A partir daí, você só precisa incluir todos os arquivos de refinamento no arquivo de modelo. Também é possível usar o arquivo de modelo para adicionar refinamentos e apontar as 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 incluir diferentes arquivos de refinamento que você criou para definir outras camadas que quer no modelo.
Como usar refinamentos para TDPs
Como 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 de tabelas derivadas persistentes (PDTs), não use extensões, já que cada extensão de uma PDT vai criar uma nova cópia da tabela no seu banco de dados.
No entanto, é possível adicionar refinamentos à visualização da PDT, já que eles não criam uma nova cópia do objeto que está sendo refinado.
Como usar metadados para conferir refinamentos de um objeto
Clique em um parâmetro explore
ou view
no ambiente de desenvolvimento integrado do Looker e use o painel de metadados para conferir os refinamentos no objeto. Consulte a página de documentação Metadados de objetos do LookML para 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 seus refinamentos. Se você estiver refinando um objeto e, em seguida, definindo novos rótulos ou descrições, deverá fornecer definições de localização nos arquivos de strings de localidade do projeto. Consulte a página de documentação Como localizar seu modelo LookML para mais informações.