Refinamentos do LookML

Este é um tópico avançado que pressupõe que o leitor tenha um conhecimento sólido de LookML.

Visão geral

Com os refinamentos do LookML, você pode adaptar uma visualização ou uma exploração existentes sem 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 ;;
  }
}

É possível refinar a visualização flights, conforme mostrado abaixo: use o parâmetro view com o mesmo nome de visualização, mas adicione um sinal de adição (+) em frente ao nome para indicar que ele é um refinamento de uma visualização existente.

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

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

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

O refinamento combinado ao LookML original tem o resultado final como se fosse o LookML original para a 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 original.

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

Refinamentos comparados a estendidos

O Looker também oferece suporte para estender objetos LookML. A extensão é útil quando você quer criar uma nova cópia de uma visualização ou de um recurso "Explorar" para adicionar novos objetos a ela. Por exemplo, você pode criar uma visualização base que define todos os seus campos e depois criar várias novas visualizações que estendem 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.

Eles são úteis quando você quer 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 ou não quer modificar a visualização base ou Explorar, e, para criar uma nova visualização ou Explorar, é preciso fazer mudanças abrangentes em outras referências LookML. Consulte a seção Exemplo nesta página para ver um caso de uso.

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

Desenvolvedores avançados do LookML podem querer usar o parâmetro extends em um refinamento LookML. Consulte a seção Os refinamentos podem conter estendidos nesta página para mais informações.

Os refinamentos substituem a maioria dos parâmetros

É importante observar que, na maioria dos casos, um refinamento substituirá 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 desta página 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 refinanciamento substituirá os valores de parâmetro do objeto refinado.

Mas 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, esta é 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"
    }
  }
}

E 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 carriers refinada, os dois parâmetros link são incrementais, então a dimensão name terá os dois links. A dimensão é semelhante a esta em um Explorar:

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:

  • 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 substituirão os refinamentos dos arquivos incluídos anteriormente.
  • Em um único arquivo, os refinamentos são aplicados linha por linha. Os refinamentos com o número de linha mais alto serão aplicados por último e substituirão os refinamentos anteriores se houver conflitos.

É possível usar a sinalização final: yes para verificar se os refinamentos estão sendo aplicados na ordem esperada. Consulte a seção Como usar final: yes para evitar outros refinamentos para mais detalhes.

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 precedência. 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, em seguida, todos os refinamentos no arquivo finishing_touches.lkml serão aplicados. Se houver algum conflito, os refinamentos no último arquivo, finishing_touches.lkml, terão precedência.

Como os refinamentos aproveitam a ordem de inclusão, não use caracteres curingas em suas inclusões caso queira usar refinamentos. Como prática geral, é melhor evitar o uso de caracteres curinga com visualizações de qualquer maneira, especialmente se o projeto tiver um grande número de arquivos de visualização ou se o projeto usar tabelas derivadas permanentes (PDTs, na sigla em inglês). Mas, principalmente em casos de refinamentos, não é recomendável usar caracteres curinga nas opções incluídas.

Uso de 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 substituirá todos os refinamentos anteriores.

Se você tiver um refinamento que gostaria de ser considerado o refinamento final da visualização ou 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 após o refinamento final ou se um desenvolvedor tentar adicionar um novo refinamento que seria aplicado depois do refinamento final. Por exemplo, o segundo refinamento neste arquivo de visualização criaria um erro 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 desejada.

Os refinamentos podem conter extensões

Desenvolvedores avançados do LookML podem querer usar um parâmetro extends em um refinamento 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, em seguida, cria nele. Por exemplo, você pode criar uma visualização base que define todos os seus campos e depois criar várias novas visualizações que estendem a visualização base. Cada uma dessas novas visualizações incorporam uma cópia da visualização base. A partir daí, um desenvolvedor pode adicionar diferentes campos, filtros ou outras propriedades para modificar o que está na visualização base. A ideia é que você comece com um objeto base e depois o use de maneiras diferentes em vários outros objetos. Consulte a página de documentação Como reutilizar código com estende para uma discussão completa sobre como trabalhar com estendes.
  • Refinar um objeto adiciona uma camada de modificações ao objeto, mas, ao contrário do alongamento, refiná-lo não faz várias cópias do objeto. A ideia é criar com base em um objeto base sem modificar o LookML original.

Como exemplo de uso padrão de refinamentos, veja uma exploração chamada orders e a exploração +orders, que faz os refinamentos:

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 uma extends. Com base no exemplo, veja o mesmo orders Explorar. 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 estenderá o recurso Explorar users_base.

Como o Looker implementa 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 entender o seguinte:

  • Como o Looker implementa extends: se um elemento LookML for definido no objeto estendidosed e no objeto estendidosing, a versão no objeto estendido será usada, a menos que o parâmetro seja additive. Consulte a página de documentação Como reutilizar código com estende 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 ver mais detalhes.

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

  1. Valores da extends especificada no objeto
  2. Valores da extends especificada nos 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 da extends especificada no objeto. Como o ordersExplorar tem um parâmetro extends, o Looker começa com os elementos LookML do objeto que está sendo estendido, que neste caso é o orders_base Explore. Nesse momento, o valor de label é "Orders Base".
  2. Valores de extends especificados em refinamentos do objeto. Como orders tem um refinamento, e o refinamento tem um parâmetro extends, o Looker aplica elementos LookML da extensão refinamento, que, neste caso, é a exploração users_base. Nesse momento, o valor de label é "Users Base".
  3. Valores do objeto. Agora que todas as extensões foram resolvidas, o Looker aplica elementos do objeto de extensão, que, nesse caso, é a exploração orders. Se houver conflitos, o objeto de extensão vencerá. Portanto, agora o valor de label é "Orders".
  4. Valores dos refinamentos do objeto. Por fim, o Looker aplica elementos de qualquer refinamento da exploração orders. Se houver conflitos, o objeto de refinamento vencerá. Portanto, agora o valor de label é "Orders refine".

O refinamento extends é aditivo

Conforme descrito na seção Parâmetros de modificaçã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. Assim, se houver algum conflito, a prioridade será atribuída ao último item da cadeia de estendes.

Por exemplo, aqui está uma exploração base 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 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 Explorar +orders estenderá o orders_base e o users_base, como se fosse o LookML original para o Explorar:

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

Assim, se houver algum conflito, a prioridade será atribuída ao último item da cadeia de estendes. Nesse exemplo, os elementos na users_base modificam todos os elementos conflitantes em orders_base.

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

Por fim, a ordem dos parâmetros explore não importa. No entanto, 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 em seu projeto:

  1. Identifique a visualização ou a exploração que você quer refinar.
  2. Decida onde você quer armazenar seus refinamentos. É possível adicionar refinamentos em qualquer arquivo LookML existente ou criar arquivos LookML separados para seus refinamentos. Veja o procedimento para criar um arquivo de teste de dados na página de documentação Noções básicas sobre outros arquivos de projeto (em inglês) para ver um exemplo de arquivos genéricos do LookML.
  3. Use o parâmetro include para incorporar os refinamentos no seu modelo:
    • No arquivo em que você escreve os refinamentos, é preciso incluir os arquivos do LookML que você está refinando. O ambiente de desenvolvimento integrado do Looker avisará se você tentar refinar um objeto que não está incluído.
    • No arquivo do modelo, inclua os arquivos em que seus refinamentos são definidos. É possível 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 ver mais detalhes.

Exemplo

Refinar objetos LookML é uma maneira fácil de adaptar visualizações e explorações sem precisar editar o LookML original. Isso é útil principalmente quando as visualizações e os Explorars são somente leitura no seu projeto, como com 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
  }
}

Essa exploração contém várias visualizações, cada uma com muitas dimensões.

Agora, outro projeto LookML chamado e_faa_refined importa o arquivo "Explorar" aircraft. No projeto e_faa_refined, você pode usar um refinamento para simplificar muito os resultados da exploração de aircraft.

Como o aircraft"Explorar"é um arquivo importado, não é possível editá-lo diretamente. Em vez disso, é possível adicionar um refinamento a ele. 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 ver detalhes sobre como consultar arquivos de projeto importados).
  • Refinamentos para a exploração aircraft:
    • O sinal + na frente do nome do Explorar indica um refinamento para um Explorar atual.
    • O parâmetro label muda o marcador "Explorar" para "quot;Aircraft Simplificado".
    • O parâmetro fields especifica que somente três campos serão exibidos em "Explorar".

O resultado final é como se 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
  }
}

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 de adicionar os 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 seu modelo sem tocar nos arquivos LookML originais. Por exemplo, se houver um projeto em que as visualizações e os Explorars são gerados de tabelas no seu banco de dados e armazenados 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 o exemplo de uma nova tabela derivada chamada distance_stats que tem uma análise de distância. Este exemplo mostra refinamentos do recurso Explorar flights do arquivo faa_basic.lkml que une a tabela derivada distance_stats ao Explorar 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 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.

No projeto FAA, por exemplo, há um arquivo faa_raw.lkml que contém todas as visualizações e explorações que foram geradas de tabelas no seu 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 a"explos"ou adicionar medidas às visualizações, como este:

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, é 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 e veja um exemplo de arquivo de análise.

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

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 que criou para definir outras camadas que quer adicionar ao seu modelo.

Como usar refinamentos para PDTs

Conforme descrito na seção Refinamentos em comparação com as extensões desta página, uma extensão cria uma nova cópia do objeto que está sendo estendido. No caso de tabelas derivadas permanentes (PDTs, na sigla em inglês), 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 PDT, já que eles não criam uma nova cópia do objeto que está sendo refinado.

Como usar metadados para ver refinamentos de 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 qualquer refinamento no objeto. Consulte a página de documentação Metadados para objetos LookML para saber mais.

Considerações

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 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 Como localizar seu modelo LookML para mais informações.