Aprimoramentos do LookML

Visão geral

Com os refinamentos do LookML, é possível adaptar uma visualização ou um Explorar sem editar o arquivo do LookML que o contém. Isso é ideal para:

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 ;;
  }
}

É possível refinar a visualização flights, conforme mostrado no exemplo a seguir: use o parâmetro view com o mesmo nome de visualização, mas adicione um sinal de mais (+) na frente do nome para indicar que é um refinamento de uma visualização existente.

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

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

Esse refinamento pode ser incluído em qualquer arquivo do LookML no projeto, como um arquivo de modelo, um arquivo de visualização ou em um arquivo dedicado 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 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 interface do Looker, os usuários vão ver a dimensão Transportadora aérea, como se você tivesse adicionado a dimensão ao arquivo de visualização original.

Consulte a seção Exemplo para informações de implementação mais detalhadas.

Refinamentos comparados a extensões

O Looker também permite estender objetos LookML. A extensão é útil quando você quer criar uma nova cópia de uma análise detalhada ou visualização para adicionar novos objetos a ela. Por exemplo, é possível criar uma visualização básica que define todos os campos e, em seguida, criar várias visualizações novas que estendem a visualização básica. Essas novas visualizações podem ser modificadas para ocultar determinados campos na visualização de base ou para mudar definições ou rótulos dos campos da visualização de base.

Os refinamentos são úteis quando você quer modificar uma visualização ou análise detalhada com alguns ajustes em determinados objetos, mas não quer criar cópias. Os refinamentos são ideais para situações em que não é possível ou não se quer modificar a visualização ou a análise detalhada básica, 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 da LookML. Consulte a seção Exemplo nesta página para ver um exemplo desse caso de uso.

Na maioria dos casos de uso, os refinamentos são uma alternativa mais simples e limpa ao 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 substitui 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 aparece 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 do objeto refinado, o refinamento vai 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 valores do objeto refinado.

Os seguintes parâmetros são aditivos:

Por exemplo, confira 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"
    }
  }
}

Aqui está 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 refinada carriers, os dois parâmetros link são aditivos. Portanto, 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 prestar muita atenção na ordem em que os refinamentos são aplicados:

  • Em um projeto, os refinamentos são aplicados na ordem em que os arquivos são incluídos. Os refinamentos dos arquivos incluídos por último vão substituir os dos arquivos incluídos antes.
  • Em um único arquivo, os refinamentos são aplicados linha por linha de cima para baixo. Os refinamentos com o maior número de linha são aplicados por último e substituem os anteriores, 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 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 nas inclusões têm precedência. Por exemplo, se um arquivo de modelo incluir estes arquivos:

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

Primeiro, as melhorias no distance_analysis.lkml e, depois, no arquivo finishing_touches.lkml. Se houver conflitos, os refinamentos no último arquivo, finishing_touches.lkml, terão precedência.

Usar final: yes para evitar mais refinamentos

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

Se você tiver um refinamento que quer considerar como o refinamento final da visualização ou da análise detalhada, adicione a flag final: yes a ele. O IDE do Looker vai retornar um erro de LookML se houver refinamentos que seriam aplicados depois desse refinamento final ou se um desenvolvedor tentar adicionar um novo refinamento que seria aplicado depois desse refinamento final. Por exemplo, o segundo refinamento neste arquivo de visualização criaria um erro de LookML porque o refinamento 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 eles estão sendo aplicados na ordem desejada.

Os refinamentos podem conter extensões

Os desenvolvedores avançados de LookML podem 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:

  • Estender um objeto cria uma nova cópia dele e a usa como base. Por exemplo, é possível criar uma visualização básica que define todos os campos e, em seguida, criar várias visualizações novas que estendem a visualização básica. Cada uma dessas novas visualizações vai incorporar uma cópia da visualização de base. A partir daí, um desenvolvedor pode adicionar diferentes campos, filtros ou outras propriedades para modificar o que está na visualização de base. A ideia é começar com um objeto de base e usá-lo de diferentes maneiras em vários outros objetos. Consulte a página de documentação Reutilizar código com "extends" para uma discussão completa sobre como trabalhar com "extends".
  • Refinar um objeto adiciona uma camada de modificações a ele, mas, ao contrário da extensão, não faz várias cópias. A ideia é criar um objeto de base sem modificar o LookML original.

Como exemplo do uso padrão de refinamentos, confira uma análise detalhada 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 inclua um extends. Com base no exemplo, aqui está a mesma análise detalhada 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 a 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 dentro dele. Como resultado, a visualização +orders agora vai estender a análise detalhada users_base.

Como o Looker implementa extends em 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 extends: se um elemento da LookML for definido no objeto estendido e no objeto estendendo, a versão no objeto de extensão será usada, a menos que o parâmetro seja aditivo. Consulte a página de documentação Reutilizar código com "extends" para mais detalhes.
  • Como o Looker implementa refinamentos: se um elemento da LookML for definido em 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 extends usado em refinamentos. Esta é a ordem que o Looker implementa, com cada etapa substituindo a anterior em caso de conflitos:

  1. Valores do extends especificado no objeto
  2. Valores do extends especificado nos refinamentos do objeto
  3. Valores do objeto
  4. 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]
}

Veja como o Looker implementa o valor de label para a análise detalhada orders neste exemplo:

  1. Valores do extends especificado no objeto. Como a análise orders tem um parâmetro extends, o Looker começa com os elementos do LookML do objeto que está sendo estendido, que, nesse caso, é a análise 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 refinamento tem um parâmetro extends, o Looker aplica elementos da LookML da extensão do refinamento, que, nesse caso, é a Análise users_base. Nesse 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 Análise orders. Se houver conflitos, o objeto de extensão vai vencer. Agora, o valor de label é "Pedidos".
  4. Valores dos refinamentos do objeto. Por fim, o Looker aplica elementos de todos os refinamentos da análise detalhada orders. Se houver conflitos, o objeto de refinamento vai vencer. Agora, o valor de label é "Pedidos refinados".

Os refinamentos extends são cumulativos

Conforme descrito na seção Substituir parâmetros 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. Em seguida, se houver conflitos, a prioridade será dada ao último item na cadeia de extensões.

Por exemplo, confira uma análise detalhada básica chamada orders_base e uma análise detalhada orders que estende a base. Além disso, há uma users_base análise detalhada 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 detalhada orders estende o orders_base. Em seguida, os refinamentos +orders adicionam o users_base à lista extends. O resultado é que a análise +orders agora vai estender orders_base e users_base, como se fosse a LookML original da análise:

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

Em seguida, se houver conflitos, a prioridade será dada ao último item na cadeia de extensões. Neste exemplo, os elementos em users_base substituem qualquer elemento conflitante 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: neste exemplo, a ordem dos parâmetros explore não importa. No entanto, em 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 anteriores.

Como usar refinamentos no projeto do LookML

Confira as etapas gerais para refinar visualizações e análises detalhadas no seu projeto:

  1. Identifique a visualização ou a análise detalhada que você quer refinar.
  2. Decida onde você quer colocar os refinamentos. Você pode adicionar refinamentos a qualquer arquivo LookML ou criar arquivos separados para eles. Consulte o procedimento para criar um arquivo de teste de dados na página de documentação Entender outros arquivos de projeto para ver um exemplo de como criar arquivos genéricos do LookML.
  3. Use o parâmetro include para incorporar os refinamentos ao modelo:
    • No arquivo em que você escreve os refinamentos, inclua os arquivos da LookML que está refinando. O IDE do Looker vai mostrar avisos se você tentar refinar um objeto que não está incluído.
    • No arquivo de modelo, inclua os arquivos em que os refinamentos estão definidos. É possível combinar arquivos e usar inclusões de maneiras muito criativas. Consulte a seção Usar refinamentos para adicionar camadas ao modelo nesta página para mais detalhes.

Exemplo

Refinar objetos LookML é uma maneira fácil de adaptar visualizações e análises detalhadas sem precisar editar o LookML original. Isso é especialmente útil quando suas visualizações e análises detalhadas são somente leitura no projeto, como arquivos importados de outros projetos. Confira um exemplo de refinamento de uma análise detalhada.

Confira 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 detalhada contém várias visualizações, cada uma com muitas dimensões.

Agora, outro projeto do LookML chamado e_faa_refined importa o arquivo de Análise aircraft. No projeto e_faa_refined, você pode usar um refinamento para simplificar drasticamente a análise detalhada aircraft.

Como a análise detalhada aircraft é um arquivo importado, não é possível editá-la diretamente. Em vez disso, adicione 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 Como importar arquivos de outros projetos para saber como se referir a arquivos de projetos importados.
  • Refinamentos na análise detalhada aircraft:
    • O sinal + na frente do nome da Análise indica um refinamento de uma Análise existente.
    • O parâmetro label muda o rótulo da análise detalhada para "Aeronave simplificada".
    • O parâmetro fields especifica que apenas três campos serão mostrados na Análise.

O resultado final é como se esta fosse a visualização original de aircraft Detalhar 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 um exemplo de uso de refinamentos para personalizar uma única visualização para vários casos de uso, consulte a receita do manual Como maximizar a reutilização de código com DRY LookML: personalização de 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 somente leitura, como blocos do Looker ou arquivos importados.

Mas, depois de entender como adicionar refinamentos e incluí-los nos seus modelos, você pode 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 alterar os arquivos originais do LookML. Por exemplo, se houver um projeto em que as visualizações e as análises detalhadas são geradas de tabelas no banco de dados e armazenadas em um arquivo do LookML chamado faa_basic.lkml, você poderá criar um arquivo faa_analysis.lkml em que usa refinamentos para adicionar análises. Confira um exemplo de uma nova tabela derivada chamada distance_stats com uma análise de distância. Este exemplo mostra um refinamento da análise detalhada flights do arquivo faa_basic.lkml que une a tabela derivada distance_stats à análise detalhada flights. Além disso, na parte de baixo do exemplo, a visualização flights atual é 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 seu projeto. É possível criar vários arquivos de refinamento e incluí-los estrategicamente para adicionar camadas.

Por exemplo, no projeto da FAA, há um arquivo faa_raw.lkml que contém todas as visualizações e análises detalhadas geradas 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 junções às suas análises detalhadas ou medidas às suas visualizações, assim:

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 incluir uma nova camada com análises. Consulte a subseção Usar refinamentos para adicionar análises para ver um exemplo de arquivo de análise.

Depois disso, basta incluir todos os arquivos de refinamento no arquivo do modelo. Você também pode usar o arquivo de modelo para adicionar refinamentos e direcionar suas visualizações às tabelas de banco de dados que 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;;
}

É possível duplicar esse arquivo de modelo e apontar para diferentes tabelas de banco de dados ou incluir arquivos de refinamento diferentes que você criou para definir outras camadas que quer no modelo.

Como usar refinamentos para TDPs

Conforme descrito na seção Refinamentos em comparação com extensões desta 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 cria uma nova cópia da tabela no 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 refinado.

Usar metadados para ver refinamentos de um objeto

Clique em um parâmetro explore ou view no Looker IDE e use o painel de metadados para conferir os refinamentos no objeto. Consulte a página de documentação Metadados para objetos da 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 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 projeto. Consulte a página de documentação Localizar seu modelo LookML para mais informações.