Como reutilizar códigos com extensões

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

Visão geral

À medida que o modelo do LookML aumenta de tamanho e complexidade, torna-se cada vez mais útil reutilizá-lo em vários lugares. O parâmetro extends permite reutilizar o código, o que ajuda você a fazer o seguinte:

  • Programar o código DRY (não se repita) para que você possa definir tudo em apenas um lugar, tornando seu código mais consistente e rápido de editar
  • Gerenciar conjuntos de campos diferentes para usuários diferentes
  • Compartilhar padrões de design em diferentes partes do projeto
  • Reutilizar conjuntos de mesclagens, dimensões ou medidas em um projeto.

Para estender um objeto LookML, crie um novo objeto LookML e adicione o parâmetro extends para indicar que o novo objeto é uma extensão de um que já existe. Isso significa que o projeto terá duas versões do objeto LookML. Se houver conflitos, o objeto estendido terá precedência e substituirá as configurações do objeto que estiver sendo estendido. Consulte a seção Detalhes de implementação do extends mais adiante nesta página para conferir mais detalhes.

Confira os refinamentos do LookML:estender uma visualização ou uma Análise é ideal para cenários em que você quer ter várias versões da visualização ou do Explore. Mas se seu objetivo é simplesmente modificar uma visualização ou um Explore sem editar o arquivo LookML que o contém, é recomendável usar um refinamento. Também é possível usar um parâmetro extends dentro de um refinamento. Consulte a página de documentação Refinamentos do LookML para mais informações e casos de uso.

É possível estender visualizações, Análises e painéis do LookML:

Não é possível estender modelos nem incluir um arquivo de modelo em outro arquivo de modelo. Em vez disso, para reutilizar ou estender as Análises nos modelos, crie um arquivo da Análise separado e inclua esse arquivo em um modelo.

Confira os exemplos a seguir de como ampliar um Explore e estender um dashboard do LookML.

Ampliar um Explore

Confira um exemplo de extensão de Explore:

explore: customer {
  persist_for: "12 hours"
}

explore: transaction {
  extends: [customer]
  persist_for: "5 minutes"
}

Neste exemplo, temos uma Análise chamada Customer, e criamos uma segunda Análise chamada Transaction que a estende. Tudo o que estiver em Customer, como as mesclagens, será incluído em Transaction. Tudo o que estiver em Transação permanecerá em Transação.

Mas observe que há um conflito: a Análise de cliente informa que a configuração persist_for precisa ser de 12 horas, mas a Análise de Transação informa que precisa ter 5 minutos. Para a Análise de transação, a configuração persist_for: "5 minutes" vai ser usada, porque substitui a configuração da Análise que está sendo estendida.

Como ampliar um dashboard do LookML

Para ampliar um dashboard do LookML, os dashboards estendidos e estendidos precisam ser incluídos no arquivo do modelo. Se um dashboard que usa o parâmetro extends for incluído em um arquivo de modelo sem o dashboard base que ele se estende, você vai receber um erro de validação do LookML informando que o dashboard base não foi encontrado (entre outros erros).

Confira um exemplo de arquivo do dashboard:

Arquivo: faa.dashboard.lookml

- dashboard: faa
  title: FAA Dashboard
  layout: newspaper
  elements:
  - title: Aircraft Location
    name: Aircraft Location
    model: e_faa
    explore: aircraft
    type: looker_map
    fields:
    - aircraft.zip
    - aircraft.count
    sorts:
    - aircraft.count desc
    limit: 500
    query_timezone: America/Los_Angeles
    series_types: {}
    row: 0
    col: 0
    width: 8
    height: 6

Podemos criar um novo arquivo do dashboard do LookML e estender o dashboard do FAA adicionando um novo bloco:

Arquivo: faa_additional.dashboard.lookml

- dashboard: faa_additional
  title: FAA Additional
  extends: faa
  elements:
  - title: Elevation Count
    name: Elevation Count
    model: e_faa
    explore: airports
    type: looker_scatter
    fields:
    - airports.elevation
    - airports.count
    sorts:
    - airports.count desc
    limit: 500
    query_timezone: America/Los_Angeles
    row: 0
    col: 8
    width: 8
    height: 6

Como ele estende o dashboard do FAA, o painel de FAA Adicional vai incluir todos os blocos definidos no arquivo faa.dashboard.lookml. Além disso, o painel FAA adicional terá todos os blocos definidos no próprio arquivo faa_additional.dashboard.lookml.

A maneira mais fácil de criar um dashboard do LookML é conseguir o LookML de um painel definido pelo usuário. Essa técnica também pode ser usada para conseguir o LookML de blocos individuais do dashboard. Se você estiver usando esse método, confira se as posições dos blocos não se sobrepõem. No exemplo acima, os blocos estão na linha superior do painel, indicada por row: 0:

Arquivo: faa.dashboard.lookml


    row: 0
    col: 0
    width: 8
    height: 6

No entanto, o novo bloco que estamos adicionando ao dashboard FAAAdditional está em col: 8. Portanto, ele é exibido ao lado do bloco no dashboard estendido:

Arquivo: faa_additional.dashboard.lookml


    row: 0
    col: 8
    width: 8
    height: 6

Isso pode passar despercebido, já que esses elementos estão em diferentes arquivos do dashboard. Portanto, ao adicionar blocos a um dashboard estendido, verifique a existência de conflitos de posicionamento entre os blocos no painel de controle estendido e os blocos no painel expandido.

Solicitando extensão

É possível usar o parâmetro extension: required para sinalizar um objeto LookML como extensão, o que significa que o objeto não pode ser usado sozinho. Um objeto com extension: required não fica visível para os usuários por conta própria. Ele serve apenas como ponto de partida a ser estendido por outro objeto LookML. O parâmetro extension é compatível com Análises, visualizações e painéis do LookML.

Um explore com extension: required não pode ser usado como explore_source para um teste de dados. O validador do LookML vai gerar um erro informando que o explore_source não foi encontrado.

Como usar metadados para ver as extensões 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 conferir as extensões no objeto ou qual objeto ele estende. Para mais informações, consulte a página de documentação Metadados para objetos do LookML.

Detalhes de implementação de extends

Estas são as etapas que o Looker segue ao estender um objeto LookML:

  1. Copiar o objeto que está sendo estendido: o Looker faz uma cópia do LookML para a visualização, a Análise ou o dashboard do LookML que está sendo estendido. Essa nova cópia é o objeto ing.
  2. Mesclar o LookML das duas cópias: o Looker mescla o LookML do objeto estendido com o objeto de extensãoing.
  3. Resolver conflitos entre as cópias: em sua maioria, se um elemento LookML for definido tanto no objeto estendido quanto no objeto de extensão, a versão no objeto de extensão será usada. No entanto, em outros casos, as extensões combinarão valores de parâmetros em vez de substituir os valores. Consulte a seção Como combinar parâmetros nesta página para mais informações.
  4. Aplicar o LookML: quando todos os conflitos são resolvidos, o Looker interpreta o LookML resultante usando a lógica padrão. Em outras palavras, o Looker vai usar todos os padrões e suposições padrão, como em qualquer outra visualização, Análise ou dashboard do LookML.

As seções a seguir mostram os detalhes dessas etapas, estendendo uma visualização como exemplo. Este é o LookML da nossa visualização base, a visualização User:

view: user {
  suggestions: yes

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

  }
  dimension: status {
    sql: ${TABLE}.status ;;
    type: number
  }
}

Este é o LookML da visualização User with Age Extensions, que estende a visualização User:

include: "/views/user.view"

view: user_with_age_extensions {
  extends: [user]
  suggestions: no

  dimension: age {
    type: number
    sql: ${TABLE}.age ;;
  }

  dimension: status {
    type: string
  }
}

Etapa 1: copiar o LookML

Nesse caso, a visualização user está sendo estendida para a visualização user_with_age_extensions. Como user é a visualização que está sendo estendida, uma cópia dela é feita antes da mesclagem. Nesse caso, não é muito importante saber o fato de que uma cópia foi feita. É importante saber que a visualização user original permanece inalterada e pode ser usada normalmente.

Etapa 2: mesclar as cópias

A próxima etapa é que todo o LookML da visualização estendida (user) seja mesclado com a visualização estendida (user_with_age_extensions). É importante entender a natureza dessa mesclagem, que é simplesmente uma mesclagem de objetos LookML. Em termos práticos, isso significa que qualquer LookML explicitamente gravado é mesclado, mas os valores padrão do LookML que você não gravou não são mesclados. De certa forma, é apenas o texto do LookML que está sendo reunido, e nenhum significado desse texto.

Etapa 3: resolver conflitos

A terceira etapa é resolver conflitos entre as visualizações mescladas.

Na maioria dos casos, se um elemento do LookML for definido no objeto estendido e no objeto estendido, a versão no objeto é usada. No entanto, em outros casos, as extensões combinarão valores de parâmetros em vez de substituir os valores. Consulte a seção Como combinar parâmetros nesta página para mais informações.

No caso do exemplo de user_with_age_extensions, nenhum dos parâmetros é aditivo, e nenhuma opções de lista ou palavras-chave sql especiais são especificadas. Portanto, os valores de parâmetro na visualização estendida modificarão os valores de parâmetro na visualização estendida:

  • O nome da visualização estendida (user_with_age_extensions) substitui o nome da visualização estendida (user).
  • O valor de extensãoing para suggestions: no substitui o valor estendido de suggestions: yes.
  • A visualização estendida tem uma dimensão chamada age, que não existe na visualização estendida (sem conflito).
  • A visualização estendida tem uma dimensão chamada name, que não existe na visualização ampliada (sem conflito).
  • O valor type: string da dimensão status na visualização ampliada substitui o valor type: number na visualização ampliada.
  • A dimensão status tem um parâmetro sql, que não existe na visualização ampla (sem conflito).

O fato de os valores padrão do LookML ainda não estarem sendo considerados é importante, porque você não quer cometer o erro de pensar que os conflitos entre os valores padrão estão sendo resolvidos. Na verdade, eles estão apenas sendo ignorados nessa etapa. É por isso que precisamos adicionar explicitamente outros parâmetros ao estender objetos:

Neste exemplo específico, não adicionamos sql_table_name à visualização Usuário, o que vai causar alguns problemas na próxima etapa.

Etapa 4: interpretar o LookML normalmente

Na etapa final, o LookML resultante é interpretado como normal, incluindo todos os valores padrão. Neste exemplo específico, a visualização resultante do LookML seria interpretada da seguinte maneira:

include: "/views/user.view"

view: user_with_age_extensions {
  suggestions: no

  dimension: age {
    type: number
    sql: ${TABLE}.age ;;
  }

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

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

O LookML resultante inclui view: user_with_age_extensions, mas nenhum parâmetro sql_table_name. Como resultado, o Looker vai presumir que o valor de sql_table_name é igual ao nome da visualização.

O problema é que provavelmente não há uma tabela chamada user_with_age_extensions no banco de dados. É por isso que precisamos adicionar um parâmetro sql_table_name a qualquer visualização que será estendida. Adicionar view_name e view_label a "Explores" que serão estendidas evita problemas semelhantes.

Combinar extensões

Há algumas maneiras de usar objetos LookML com extensões:

Para conferir um exemplo de caso de uso avançado e ler dicas de solução de problemas, consulte a página de práticas recomendadas Resolver problemas de um exemplo de caso de uso avançado da extends.

Extensão de mais de um objeto ao mesmo tempo

É possível estender mais de um dashboard, uma visualização ou uma Análise ao mesmo tempo. Exemplo:

explore: orders {
  extends: [user_info, marketing_info]
}
# Also works for dashboards and views

O processo de extensão funciona exatamente como descrito no exemplo de implementação, mas há uma regra extra sobre como os conflitos são resolvidos. Se houver conflitos entre os vários itens listados no parâmetro extends, a prioridade será concedida aos últimos itens listados. Portanto, no exemplo acima, se houvesse conflitos entre user_info e marketing_info, a Análise marketing_info venceria.

Encadear várias extensões

Também é possível encadear quantas extensões você quiser. Exemplo:

explore: orders {
  extends: [user_info]
  ...
}
explore: user_info {
  extends: [marketing_info]
  ...
}

Novamente, o processo de extensão funciona exatamente como descrito no exemplo de implementação, com uma regra extra sobre a resolução de conflitos. Se houver conflitos, a prioridade é dada ao último item na cadeia de extensões. Neste exemplo:

  • orders teria prioridade sobre user_info e marketing_info.
  • user_info teria prioridade sobre marketing_info.

Combinar parâmetros

Na maioria dos casos, se um elemento do LookML for definido no objeto estendido e no objeto estendido, a versão no objeto é usada. Esse foi o caso do exemplo de implementação desta página.

No entanto, nos casos a seguir, as extensões combine valores de parâmetros em vez de modificar os valores:

Alguns parâmetros são aditivos

Em muitos casos, se o objeto de extensão tiver o mesmo parâmetro que o objeto que está sendo estendido, os valores do objeto de extensão vão substituir os de parâmetro do objeto estendido. Mas as extensões podem ser aditivas para alguns parâmetros, o que significa que os valores do objeto de extensão são usados em conjunto com os valores do objeto estendido.

Os seguintes parâmetros são aditivos:

No exemplo a seguir, a visualização carriers 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 esta é a visualização carriers_extended, que estende a visualização carriers. A visualização carriers_extended também tem uma dimensão name com configurações diferentes no parâmetro link:


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

view: carriers_extended {
  extends: [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_extended, os dois parâmetros link são cumulativos. Portanto, a dimensão name exibirá os dois links.

Outras opções com listas

Ao trabalhar com listas, você pode optar por combiná-las, em vez de fazer com que a lista do objeto estendido seja a vencedora. Considere esta extensão simples com uma lista conflitante chamada animals:

view: pets {
  extends: fish
  set: animals {
    fields: [dog, cat]
  }
}
view: fish {
  set: animals {
    fields: [goldfish, guppy]
  }
}

Nesse caso, a visualização pets está fazendo a extensão e vence, fazendo com que animals contenha [dog, cat]. No entanto, usando o conjunto especial EXTENDED*, você pode combinar as listas:

view: pets {
  extends: fish
  set: animals {
    fields: [dog, cat, EXTENDED*]
  }
}
view: fish {
  set: animals {
    fields: [goldfish, guppy]
  }
}

Agora, a lista animals conterá [dog, cat, goldfish, guppy].

Combinar em vez de substituir durante a resolução de conflitos

Em sua maioria, se houver conflitos durante a extensão, o objeto estendido prevalece. Por exemplo, veja esta extensão simples:

view: product_short_descriptions {
  extends: products
  dimension: description {
    sql: ${TABLE}.short_description ;;
  }
}
view: products {
  dimension: description {
    sql: ${TABLE}.full_description ;;
  }
}

Observe que há um conflito do parâmetro sql na dimensão description. Normalmente, a definição de product_short_descriptions simplesmente substitui a definição de products porque está fazendo a extensão.

No entanto, você também pode combine as definições, se quiser. Para isso, use a palavra-chave ${EXTENDED} desta forma:

view: product_short_descriptions {
  extends: products
  dimension: description {
    sql: LEFT(${EXTENDED}, 50) ;;
  }
}
view: products {
  dimension: description {
    sql: ${TABLE}.full_description ;;
  }
}

Agora, o conflito do parâmetro sql será tratado de maneira diferente. Em vez de a definição do product_short_descriptions vencer, ela vai usar a definição de products e inseri-la onde ${EXTENDED} é usada. Nesse caso, a definição resultante para description será: LEFT(${TABLE}.full_description, 50).

Informações importantes

Projetos com localização

Ao estender um objeto, saiba que regras de localização também se aplicam a suas extensões. Se você estiver estendendo um objeto e definir novos rótulos ou descrições, forneça definições de localização nos arquivos de strings de localidade do seu projeto. Para mais informações, consulte a página de documentação Como localizar seu modelo LookML.