Termos e conceitos do LookML

As seções Operador de substituição ($), Escopo e nomeação, Dialeto SQL e Bloqueio SQL foram movidas para a nova página de documentação Como incorporar o SQL e fazer referência aos objetos LookML.

Visão geral

Esta página define termos e conceitos que aparecem repetidamente no desenvolvimento LookML. O diagrama a seguir mostra as relações entre os elementos contidos em outros. Todos os termos mostrados aqui são definidos nas seções a seguir.

Aparências e painéis definidos pelo usuário não fazem parte deste diagrama, já que os usuários os criam sem usar LookML. No entanto, as consultas dependem dos elementos LookML subjacentes mostrados no diagrama anterior.

projeto do LookML

Um projeto é uma coleção de arquivos LookML que descrevem como as tabelas do banco de dados estão relacionadas entre si e como o Looker interpretará essas tabelas. Cada projeto LookML reside no próprio repositório Git para controle de versões.

Veja os tipos de arquivo comuns em um projeto LookML:

• Um modelo contém informações sobre quais tabelas usar e como elas precisam ser unidas. Normalmente, você define o modelo, os Explorars e as junções dele.
• Uma visualização contém informações sobre como acessar ou calcular informações de cada tabela (ou de várias tabelas mescladas). Normalmente, você define a visualização, as dimensões e medidas dela e os conjuntos de campos dela.
• Uma exploração costuma ser definida em um arquivo de modelo, mas às vezes você precisa de um arquivo de exploração separado para uma tabela derivada ou para estender ou refinar uma exploração entre modelos.
• Um arquivo de manifesto pode conter instruções para usar arquivos importados de outro projeto ou para as configurações de localização do seu projeto.

Consulte a página de documentação Arquivos de projeto do LookML para ver informações sobre outros tipos de arquivo que você pode ter no seu projeto do LookML.

Depois de conectar o Looker ao banco de dados, especifique a conexão do banco de dados a ser usada no seu projeto do Looker:

No Looker, é possível acessar os projetos no menu Desenvolver:

A partir do Looker 21.12, se seu administrador tiver ativado o recurso do Labs Enhanced Navigation, você poderá acessar seus projetos selecionando a opção Develop no novo painel de navegação aprimorado à esquerda.

De onde vêm os projetos e arquivos LookML?

A maneira mais comum de criar arquivos LookML é gerar um projeto LookML do seu banco de dados. Também é possível criar um projeto em branco e criar manualmente os arquivos LookML, ou criar um projeto clonando um repositório Git existente.

Quando você gera um novo projeto a partir do banco de dados, o Looker cria um conjunto de valores de referência que podem ser usados como modelo para criar o projeto:

• Vários arquivos de visualização, um arquivo para cada tabela no banco de dados.
• Um arquivo de modelo. O arquivo de modelo declara uma exploração para cada visualização. Cada declaração "Explorar" inclui a lógica join para mesclar qualquer visualização que o Looker possa determinar que esteja relacionada à área "Explorar".

Nela, você pode personalizar o projeto removendo visualizações e explorações indesejadas e adicionando dimensões e medidas personalizadas.

Principais estruturas do LookML

Como mostrado no diagrama anterior, um projeto normalmente contém um ou mais arquivos de modelo que contêm parâmetros que definem um modelo e os Explorars e mesclagens dele. Além disso, os projetos normalmente contêm um ou mais arquivos de visualização, cada um contendo parâmetros que definem essa visualização e os campos (incluindo dimensões e medidas) e os conjuntos de campos. O projeto também pode conter um arquivo de manifesto com parâmetros para usar arquivos de visualização de outros projetos ou configurar padrões de localização. Esta seção descreve essas principais estruturas.

Modelo

Um modelo é um portal personalizado no banco de dados, projetado para fornecer exploração de dados intuitiva para usuários comerciais específicos. Vários modelos podem existir para a mesma conexão de banco de dados em um único projeto LookML. Cada modelo pode expor dados diferentes para usuários distintos. Por exemplo, os agentes de vendas precisam de dados diferentes dos executivos da empresa. Portanto, é provável que você desenvolva dois modelos para oferecer visualizações do banco de dados adequadas para cada usuário.

No Looker, as consultas são agrupadas pelo modelo a que pertencem. Seus usuários veem modelos listados no menu Explorar:

A partir do Looker 21.12, se seu administrador tiver ativado o recurso do Labs Enhanced Navigation, você poderá acessar o Explorar e ver uma lista de Explorars selecionando a opção Explorar no novo painel de navegação à esquerda aprimorado.

Um arquivo de modelo especifica o banco de dados a que se conectar e define um conjunto de explores para essa conexão. Por convenção, cada arquivo declara exatamente um modelo e, no novo LookML, os nomes de arquivos de modelo terminam em .model.lkml. O nome do arquivo de modelo determina o nome que é exibido no Looker.

A forma geral de uma declaração de modelo no LookML é mostrada a seguir. Consulte a página de documentação Parâmetros do modelo para ver mais detalhes.

connection: connection_name
persist_for: timeframe
case_sensitive: yes | no
include: "filename_pattern"   # for example: *.view.lkml
# More include declarations

explore: explore_name {
  view_name: view_name
  join: view_name {
    # join parameters
  }
  # More join declarations
}
# More explore declarations

Ver

Uma declaração de visualização define uma lista de campos (dimensões ou medidas) e a vinculação deles a uma tabela subjacente ou derivada. No LookML, uma visualização normalmente faz referência a uma tabela de banco de dados subjacente, mas ela também pode representar uma tabela derivada.

Uma visualização pode se unir a outras. A relação entre as visualizações é geralmente definida como parte de uma declaração Explore em um arquivo de modelo.

No Looker, os nomes de visualização aparecem no início da dimensão e medem os nomes na tabela de dados. Essa convenção de nomenclatura deixa claro a qual visualização o campo pertence:

Uma visualização é armazenada em um arquivo .view.lkml. A forma geral de uma declaração de visualização é mostrada a seguir. Consulte a página de documentação Ver parâmetros para ver todos os detalhes de uso.

view: view_name {
  dimension: field_name {
    # dimension_parameters
  }
  # more dimension declarations
  measure: field_name {
    # measure_parameters
  }
  # more measure declarations
  set: first_set {
    fields: [field_one, field_two]
  }
}

Quando você usa uma medida de type: count em uma exploração, a visualização identifica os valores resultantes com o nome da visualização, em vez da palavra "Count." Para evitar confusão, recomendamos pluralizar o nome da visualização, selecionando Mostrar nome do campo completo em Séries nas configurações de visualização ou usar um view_label com uma versão plural do nome da visualização.

Explorar

"Explorar" é uma visualização que os usuários podem consultar. Pense em Explorar como um ponto de partida para uma consulta ou, em termos SQL, como FROM em uma instrução SQL. Nem todas as visualizações são "explores", porque nem todas descrevem uma entidade de interesse. Por exemplo, uma visualização de Estados correspondente a uma tabela de consulta para nomes de estado não garante uma exploração, porque os usuários comerciais nunca precisam consultá-la diretamente. Por outro lado, os usuários comerciais provavelmente querem uma maneira de consultar uma visualização Pedidos. Portanto, faz sentido definir uma exploração para Pedidos.

Uma declaração explore especifica as relações de mesclagem para outras visualizações. Continuando com os exemplos anteriores, a visualização Orders pode se unir à visualização states, identificando o estado em que uma venda ocorreu. Consulte JOINs para mais detalhes.

No Looker, seus usuários podem ver "explores" listados no menu Explorar:

Por convenção, os "explores" são declarados no arquivo de modelo. O exemplo a seguir demonstra a declaração de uma exploração orders para um banco de dados de comércio eletrônico. As visualizações orders e customers são definidas em outro lugar, nos respectivos arquivos de visualização.

# ———————————————
# file: ecommercestore.model.lookml
# ———————————————
connection: order_database
include: "filename_pattern"   # include all the views
explore: orders {
  join: customers {
    sql_on: ${orders.customer_id} = ${customers.id} ;;
  }
}

Para detalhes sobre declarações join, consulte Mesclagens. Consulte a página de documentação Parâmetros de mesclagem para ver detalhes de uso completos.

Campos de dimensão e medida

As visualizações contêm campos, principalmente dimensões e medidas, que são os elementos fundamentais das consultas do Looker.

No Looker, uma dimensão é um campo agrupável e pode ser usado para filtrar os resultados da consulta. Você pode usar:

• Um atributo, que tem uma associação direta a uma coluna em uma tabela subjacente
• Um fato ou um valor numérico
• Um valor derivado, calculado com base nos valores de outros campos em uma única linha.

Por exemplo, as dimensões de uma visualização Produtos podem incluir o nome, o modelo, a cor, o preço, a data de criação e a data de término de vida do produto.

Uma medida é um campo que usa uma função agregada SQL, como COUNT, SUM, AVG, MIN ou MAX. Qualquer campo calculado com base nos valores de outros valores de medidas também é uma medida. As medidas podem ser usadas para filtrar valores agrupados. Por exemplo, as medidas para uma vista Vendas podem incluir o total de itens vendidos (uma contagem), o preço total de vendas (uma soma) e o preço médio de venda (uma média).

O comportamento e os valores esperados para um campo dependem do tipo declarado, como string, number ou time. Para medições, os tipos incluem funções agregadas, como sum e percent_of_previous. Para ver mais detalhes, consulte os tipos de dimensão e os tipos de medição.

No Looker, os campos são listados na página Explorar no seletor de campos do lado esquerdo da página.

Por convenção, os campos são declarados como parte da visualização a que pertencem, armazenados em um arquivo de visualização. O exemplo a seguir mostra várias declarações de dimensão e medida. Observe o uso do operador de substituição ($) para referenciar campos sem usar um nome de coluna SQL com escopo completo.

Veja alguns exemplos de declarações de dimensões e medidas:

view: orders {
  dimension: id {
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }
  dimension: customer_id {
    sql: ${TABLE}.customer_id ;;
  }
  dimension: amount {
    type: number
    value_format: "0.00"
    sql: ${TABLE}.amount ;;
  }
  dimension_group: created {
    type: time
    timeframes: [date, week]
    sql: ${TABLE}.created_at ;;
  }
  measure: count {
    type: count           # creates sql COUNT(orders.id)
    sql: ${id} ;;
  }
  measure: total_amount {
    type: sum             # creates sql SUM(orders.amount)
    sql: ${amount} ;;
  }
}

Também é possível definir uma dimension_group, que cria várias dimensões relacionadas ao tempo de uma só vez, e campos filter, que têm vários casos de uso avançados, como filtros modelo.

Consulte a página de documentação Parâmetros de campo para ver detalhes completos sobre como declarar campos e as várias configurações que podem ser aplicadas a eles.

Mesclagens

Como parte de uma declaração explore, cada declaração join especifica uma visualização que pode ser mesclada ao explore. Quando um usuário cria uma consulta que inclui campos de várias visualizações, o Looker gera automaticamente a lógica de mesclagem SQL para trazer todos os campos corretamente.

Veja um exemplo de join em uma declaração explore:

# ———————————————
# file: ecommercestore.model.lookml
# ———————————————
connection: order_database
include: "filename_pattern"   # include all the views
explore: orders {
  join: customers {
    sql_on: ${orders.customer_id} = ${customers.id} ;;
  }
}

Para ver mais detalhes, confira Como trabalhar com mesclagens no LookML.

Arquivos de manifesto do projeto

O projeto pode conter um arquivo de manifesto do projeto, usado para configurações no nível do projeto. Por exemplo, para especificar outros projetos a serem importados para o projeto atual, definir constantes do LookML, especificar configurações de localização de modelos e adicionar extensões e visualizações personalizadas ao projeto.

Cada projeto pode ter apenas um arquivo de manifesto. O arquivo precisa ter o nome manifest.lkml e estar localizado no nível raiz do repositório Git. Ao usar pastas no ambiente de desenvolvimento integrado, verifique se o arquivo manifest.lkml é mantido no nível raiz da estrutura de diretórios do seu projeto.

Você pode usar um arquivo de manifesto do projeto para importação ou localização, mas não para as duas funções.

Para importar arquivos LookML de um projeto diferente, use o arquivo de manifesto do projeto para especificar o nome do projeto atual e o local dos projetos externos que podem ser armazenados local ou remotamente. Exemplo:

# This project
project_name: "my_project"

# The project to import
local_dependency: {
  project: "my_other_project"
}

remote_dependency: ga_360_block {
  url: "https://github.com/llooker/google_ga360"
  ref: "4be130a28f3776c2bf67a9acc637e65c11231bcc"
}

Depois de definir os projetos externos no arquivo de manifesto do projeto, use o parâmetro include no arquivo de modelo para adicionar arquivos do projeto externo ao atual. Exemplo:

include: "//my_other_project/imported_view.view"
include: "//ga_360_block/*.view"

Para mais informações, consulte a página de documentação Como importar arquivos de outros projetos.

Para adicionar a localização ao seu modelo, use o arquivo de manifesto do projeto para especificar as configurações de localização padrão. Exemplo:

localization_settings: {
  default_locale: en
  localization_level: permissive
}

Especificar as configurações padrão de localização é uma etapa para localizar o modelo. Para mais informações, consulte a página de documentação Como localizar seu modelo LookML.

Conjuntos

No Looker, um conjunto é uma lista que define um grupo de campos usados juntos. Normalmente, os conjuntos são usados para especificar quais campos serão exibidos depois que um usuário detalhar os dados. Os conjuntos de exercícios são especificados campo por campo. Assim, você tem controle total sobre os dados que são exibidos quando um usuário clica em um valor em uma tabela ou painel. Os conjuntos também podem ser usados como um recurso de segurança para definir grupos de campos visíveis para usuários específicos.

O exemplo a seguir mostra uma declaração definida em uma visualização order_items, definindo campos que listam detalhes relevantes sobre um item comprado. O conjunto referencia campos de outras visualizações, especificando o escopo.

set: order_items_stats_set {
  fields: [
    id,  # scope defaults to order_items view
    orders.created_date,  # scope is "orders" view
    orders.id,
    users.name,
    users.history,  # show all products this user has purchased
    products.item_name,
    products.brand,
    products.category,
    total_sale_price
  ]
}

Consulte a página de documentação do parâmetro set para ver detalhes completos de uso dos conjuntos.

Detalhar

No Looker, é possível detalhar todos os campos que são configurados dessa maneira ao escrever o LookML. O detalhamento funciona em tabelas e resultados de consultas. O detalhamento inicia uma nova consulta restrita pelo valor em que você clicou.

O comportamento do detalhamento é diferente para dimensões e medidas:

• Ao fazer o detalhamento de uma dimensão, a nova consulta filtra o valor. Por exemplo, se você clicar em uma data específica em uma consulta de pedidos do cliente por data, a nova consulta mostrará os pedidos somente nessa data.
• Ao analisar uma medida, a nova consulta mostrará o conjunto de dados que contribuiu para ela. Por exemplo, ao analisar uma contagem, a nova consulta mostrará as linhas para calcular essa contagem. Ao analisar métricas de valor máximo, mínimo e médio, a perfuração ainda mostra todas as linhas que contribuíram para essa medida. Isso significa que a perfuração em uma medida máxima, por exemplo, mostra todas as linhas que foram usadas para calcular o valor máximo, não apenas uma linha para o valor máximo.

Os campos da nova consulta de detalhamento podem ser definidos por um conjunto ou pelo parâmetro drill_fields (para campos) ou drill_fields (para visualizações).

Tabelas derivadas

Uma tabela derivada é uma consulta cujos resultados são usados como se fosse uma tabela real no banco de dados. As tabelas derivadas são criadas usando o parâmetro derived_table em uma declaração view. O Looker acessa tabelas derivadas como se fossem tabelas físicas com o próprio conjunto de colunas. Uma tabela derivada é exposta como a própria visualização usando o parâmetro derived_table e define dimensões e medidas da mesma maneira que as visualizações convencionais. A visualização de uma tabela derivada pode ser consultada e mesclada com outras visualizações, assim como qualquer outra visualização.

As tabelas derivadas também podem ser definidas como tabelas derivadas permanentes (PDTs, na sigla em inglês), que são tabelas derivadas escritas em um esquema de raspadinha no banco de dados e geradas automaticamente de acordo com a programação especificada por uma estratégia de persistência.

Consulte a página de documentação Tabelas derivadas no Looker para mais informações.

Conexão com o banco de dados

Outro elemento importante de um projeto LookML é a conexão do banco de dados que o Looker usará para executar consultas no seu banco de dados. Um administrador do Looker usa a página Conexões para configurar conexões de banco de dados, e os desenvolvedores do LookML usam o parâmetro connection em um arquivo de modelo para especificar qual conexão usar para o modelo. Se você gerar um projeto LookML do seu banco de dados, o Looker preencherá automaticamente o parâmetro connection no arquivo de modelo.