Como reutilizar código 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 seu modelo LookML aumenta em tamanho e complexidade, torna-se cada vez mais útil reutilizá-lo em vários locais. O parâmetro extends permite reutilizar o código, o que ajuda você a fazer o seguinte:

  • Escrever um 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 seu projeto
  • Reutilizar conjuntos de junções, dimensões ou medições em um projeto

Para estender um objeto do LookML, crie um novo objeto do LookML e adicione o parâmetro extends para indicar que o novo objeto é uma extensão de um objeto existente. Isso significa que o projeto terá duas versões do objeto do LookML. Se houver conflitos, o objeto de extensão terá precedência e substituirá as configurações do objeto que está sendo estendido. Consulte a seção Detalhes da implementação para extends mais adiante nesta página para 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 dela. Mas se o seu objetivo é simplesmente modificar uma visualização ou uma Análise sem editar o arquivo do LookML que a contém, você pode 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:

Os modelos não podem ser estendidos e não é possível incluir um arquivo de modelo em outro arquivo de modelo. Em vez disso, se você quiser reutilizar ou estender Análises em vários modelos, crie um arquivo separado e inclua-o em um arquivo de modelo.

Confira os exemplos a seguir de estendendo um Explore e estendendo um dashboard do LookML.

Como estender uma Análise

Confira um exemplo de extensão de uma Análise:

explore: customer {
  persist_for: "12 hours"
}

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

Nesse exemplo, temos uma Análise chamada Customer e criamos uma segunda chamada Transaction que a estende. Tudo o que está em Cliente, como junções, será incluído em Transação. Tudo que estiver em Transação permanecerá em Transação.

Observe que há um conflito: a Análise do cliente diz que a configuração persist_for deve ser de 12 horas, mas a Análise de transações diz que deve ser de 5 minutos. Para a Análise de transação, a configuração persist_for: "5 minutes" será usada, porque substitui a configuração da Análise que é estendida.

Estender um dashboard do LookML

Para estender um dashboard do LookML, os dashboards estendidos e estendidos precisam ser incluídos no arquivo de modelo. Se um dashboard que usa o parâmetro extends for incluído em um arquivo de modelo sem a extensão do dashboard básico, vai ocorrer um erro de validação do LookML informando que o dashboard básico não foi encontrado, entre outros erros.

Confira um exemplo de arquivo de 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 de dashboard do LookML e estender o dashboard da 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 amplia o dashboard da FAA, o dashboard extra da FAA inclui todos os blocos definidos no arquivo faa.dashboard.lookml. Além disso, o painel de controle extra da FAA (link em inglês) tem blocos definidos no próprio arquivo faa_additional.dashboard.lookml.

A maneira mais fácil de criar um dashboard do LookML é obter o LookML de um dashboard definido pelo usuário. Você também pode usar essa técnica para obter o LookML para blocos individuais de dashboard. Se você estiver usando esse método, tenha cuidado para que as posições dos blocos não se sobreponham. Nos exemplos faa.dashboard.lookml e faa_additional.dashboard.lookml, 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 FAA additional (em inglês) está em col: 8. Portanto, ele é exibido ao lado do bloco do painel estendido:

Arquivo: faa_additional.dashboard.lookml


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

É fácil não perceber esses elementos, já que eles estão em arquivos de dashboard diferentes. Portanto, se você estiver adicionando blocos a um painel de controle estendido, verifique se há conflitos de posicionamento entre blocos no painel de controle estendido e blocos no painel de controle estendido.

Exigindo extensão

É possível usar o parâmetro extension: required para sinalizar um objeto do LookML como requisito de extensão, o que significa que o objeto não pode ser usado por conta própria. Um objeto com extension: required não é visível para os usuários por conta própria. Ele serve apenas como um ponto de partida a ser estendido por outro objeto do 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 LookML Validator vai gerar um erro informando que o explore_source não foi encontrado.

Como usar metadados para ver as extensões de um objeto

Você pode 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. Consulte a página de documentação Metadados de objetos do LookML para mais informações.

Detalhes de implementação de extends

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

  1. Copiar o objeto que está sendo estendido: o Looker faz uma cópia do LookML para a visualização, Análise ou dashboard do LookML que está sendo estendido. Essa nova cópia é o objeto ing estendido.
  2. Mesclar o LookML das duas cópias: o Looker mescla o LookML do objeto estendido ao objeto estendido.
  3. Resolver conflitos entre as cópias: na maioria dos casos, se um elemento do LookML for definido tanto no objetoed como no objetoing estendido, a versão no objeto expansível será usada. No entanto, em outros casos, as extensões combinarão valores de parâmetro em vez de substituir os valores. Consulte a seção Combinar parâmetros nesta página para mais informações.
  4. Aplique o LookML: depois que todos os conflitos são resolvidos, o Looker interpreta o LookML resultante usando a lógica padrão. Em outras palavras, o Looker usa 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 as especificidades dessas etapas, estendendo uma visualização como exemplo. Este é o LookML da nossa visualização básica, 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. Aqui, não é muito importante saber que uma cópia é feita. É importante saber que a visualização user original não foi alterada e pode ser usada.

Etapa 2: mesclar as cópias

Na próxima etapa, todo o LookML da visualização estendida (user) é mesclado na visualização ing estendida (user_with_age_extensions). É importante entender a natureza dessa mesclagem, que é simplesmente uma mesclagem de objetos do LookML. Em termos práticos, isso significa que qualquer LookML escrito explicitamente é mesclado, mas os valores padrão do LookML que você não anotou 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 quaisquer conflitos entre as visualizações mescladas.

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

No caso do exemplo user_with_age_extensions, nenhum dos parâmetros é aditivo e nenhuma opção de lista especial ou palavra-chave sql é especificada. Portanto, os valores de parâmetro na visualização estendida substituirã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 estendido para suggestions: no substitui o valor estendido 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 estendida (sem conflito).
  • O valor type: string da dimensão status na visualização ampliada substitui o valor type: number na visualização estendida.
  • A dimensão status tem um parâmetro sql, que não existe na visualização de extensão (sem conflito).

O fato de que os valores padrão do LookML ainda não estão 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 sendo ignorados nesta etapa. É por isso que precisamos adicionar explicitamente mais 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 como normal

Na etapa final, o LookML resultante é interpretado como normal, incluindo todos os valores padrão. Nesse exemplo específico, a visualização resultante 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 nosso 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 às Análises que serão estendidas evita problemas semelhantes.

Combinação de extensões

Há algumas maneiras de aproveitar os objetos do LookML com extensões:

Para conferir um exemplo de caso de uso avançado e as dicas de solução de problemas, consulte a página Práticas recomendadas de um exemplo de caso de uso avançado do extends.

Estender mais de um objeto ao mesmo tempo

É possível estender mais de um painel, visualização ou 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 anterior, se houvesse conflitos entre user_info e marketing_info, a Análise marketing_info venceria.

Encadear várias extensões

Você também pode encadear quantos extensões 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 será 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.

Combinação de parâmetros

Na maioria dos casos, se um elemento do LookML for definido no objeto ed estendido e no objeto ing estendido, a versão no objeto expansível será usada. Foi o caso no exemplo de implementação desta página.

No entanto, nos casos abaixo, as extensões combine os valores dos parâmetros em vez de substituir:

Alguns parâmetros são aditivos

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

Os parâmetros a seguir 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 aditivos, de modo que 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 de extensão 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, portanto, 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 vai conter [dog, cat, goldfish, guppy].

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

Na maioria das vezes, se houver conflitos durante a extensão, o objeto de extensão vencerá. 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 ;;
  }
}

É possível ver 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, também é possível combine as definições. Para fazer isso, você usará 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 da definição product_short_descriptions vencedora, ele pegará a definição de products e a inserirá no local em que ${EXTENDED} é usado. A definição resultante para description nesse caso será: LEFT(${TABLE}.full_description, 50).

Informações importantes

Projetos com localização

Ao estender um objeto, saiba que as regras de localização também se aplicam às suas extensões. Se você estiver estendendo um objeto e 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.