Termos e conceitos do LookML

Nesta página, definimos os seguintes termos e conceitos principais, que você provavelmente encontrará com frequência durante o desenvolvimento do LookML:

Looks e painéis definidos pelo usuário não são descritos nesta página, porque os usuários os criam sem usar LookML. No entanto, as consultas dependem dos elementos do LookML subjacentes que são discutidos nesta página.

Consulte o glossário do Looker para conferir uma lista abrangente de termos e definições usados no Looker. Para ter uma visão geral abrangente dos parâmetros do LookML que podem ser usados em um projeto do LookML, consulte a página de referência rápida do LookML.

projeto do LookML

No Looker, um projeto é uma coleção de arquivos que descreve os objetos, as conexões do banco de dados e os elementos da interface do usuário que serão usados para realizar consultas SQL. No nível mais básico, esses arquivos descrevem como as tabelas de banco de dados se relacionam entre si e como o Looker deve interpretá-las. Os arquivos também podem incluir parâmetros LookML que definem ou alteram as opções apresentadas na UI do Looker. Cada projeto do LookML fica no próprio repositório Git para controle de versão (link em inglês).

Depois de conectar o Looker ao seu banco de dados, especifique a conexão dele para seu projeto.

Você pode acessar seus projetos no menu Develop no Looker. Consulte Acessar arquivos de projeto para mais detalhes e outras opções.

Para mais informações sobre como criar um novo projeto, consulte Como criar um novo projeto do LookML. Para saber como acessar e fazer alterações em projetos atuais do LookML, consulte Como acessar e editar informações do projeto.

Partes de um projeto

Um projeto do LookML pode conter modelos, visualizações e dashboards do LookML. Cada um deles é composto de outros elementos do LookML.

Conforme mostrado no diagrama, estes são alguns dos tipos mais comuns de arquivos em um projeto do LookML:

  • Um model contém informações sobre quais tabelas usar e como elas devem ser mescladas. Normalmente, aqui você define o modelo, as Análises e as mesclagens dele.
  • Uma visualização contém informações sobre como acessar ou calcular informações de cada tabela (ou de várias tabelas unidas). Normalmente, aqui você define a visualização, suas dimensões e medidas e seus conjuntos de campos.
  • Em geral, uma Análise é definida em um arquivo de modelo, mas, às vezes, você precisa de um arquivo diferente para uma tabela derivada ou para estender ou refinar uma Análise entre modelos.
  • Um arquivo de manifesto pode conter instruções de uso de arquivos importados de outro projeto ou para as configurações de localização do seu projeto.

Além de modelos, visualização, análise e arquivos de manifesto, um projeto pode ter outros tipos de arquivos relacionados a painéis integrados, documentação, localização e muito mais. Consulte a página de documentação Arquivos do projeto LookML para mais informações sobre esses tipos de arquivos e outros que podem ser incluídos no projeto do LookML.

Esses arquivos juntos formam um projeto. Se você estiver usando o Git para controle de versões, geralmente o backup de cada projeto é feito pelo próprio repositório Git.

De onde vêm os projetos e arquivos do LookML?

A maneira mais comum de criar arquivos LookML é gerar um projeto LookML do seu banco de dados. Você também pode criar um projeto em branco e gerar manualmente os arquivos LookML dele ou criar um projeto clonando um repositório Git existente.

Quando você gera um novo projeto com base no seu banco de dados, o Looker cria um conjunto de arquivos de referência que pode ser usado como modelo para desenvolver o projeto:

  • Vários arquivos de visualização, um arquivo para cada tabela no banco de dados.
  • Um arquivo de model. O arquivo de modelo declara um Explore para cada visualização. Cada declaração do Explore inclui a lógica join para unir qualquer visualização que o Looker possa determinar que está relacionada à Análise.

Aqui, é possível personalizar o projeto removendo visualizações e Análises indesejadas e adicionando dimensões e medidas personalizadas.

Principais estruturas do LookML

Conforme mostrado no diagrama de partes de um projeto, normalmente ele contém um ou mais arquivos de modelo com parâmetros que definem um modelo e as respectivas Análises e mesclas. Além disso, os projetos geralmente 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 conjuntos de campos. O projeto também pode conter um arquivo de manifesto, que permite definir as configurações do projeto. Esta seção descreve essas principais estruturas.

Modelo

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

Um modelo especifica uma conexão com um único banco de dados. Um desenvolvedor também define as Explores de um modelo no arquivo de modelo. Por padrão, as Análises são organizadas sob o nome do modelo em que são definidas. Os usuários verão os modelos listados no menu Explorar.

Consulte a página de documentação Tipos de arquivos em um projeto do LookML para mais informações sobre os arquivos de modelo, incluindo a estrutura e a sintaxe geral desses arquivos.

Consulte a página de documentação Parâmetros de modelo para mais detalhes sobre os parâmetros do LookML que podem ser usados em um arquivo de modelo.

View

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, mas também pode representar uma tabela derivada.

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

Por padrão, os nomes das visualizações aparecem no início dos nomes da dimensão e da medição na tabela de dados "Explorar". Essa convenção de nomenclatura deixa claro a qual visualização o campo pertence. No exemplo a seguir, os nomes de visualização Pedidos e Usuários estão listados antes dos nomes dos campos na tabela de dados:

Tabela de dados de uma consulta de amostra com os campos Data de criação de pedidos, ID de usuários e Contagem de pedidos selecionados.

Consulte a documentação Tipos de arquivos em um projeto do LookML para mais informações sobre arquivos de visualização, incluindo a sintaxe de estrutura e geral dos arquivos de visualização.

Consulte a página de documentação Visualizar parâmetros para mais detalhes sobre os parâmetros do LookML que podem ser usados em um arquivo de visualização.

Analisar

Uma Análise é uma visualização que os usuários podem consultar. Pense na Análise como um ponto de partida para uma consulta ou, em termos de SQL, como o 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 que corresponde a uma tabela de consulta para nomes de estado não justifica uma Análise, 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 Orders. Portanto, é recomendável definir uma opção "Explore" para Orders. Consulte a página de documentação Como visualizar e interagir com Análises no Looker para informações sobre como os usuários interagem com as Análises para consultar dados.

No Looker, os usuários encontram as Análises listadas no menu Explorar. Os Explores estão listados abaixo dos nomes dos modelos a que pertencem.

Por convenção, as Análises são declaradas no arquivo modelo com o parâmetro explore. No exemplo a seguir de um arquivo de modelo, a Análise orders de um banco de dados de e-commerce é definida no arquivo de modelo. As visualizações orders e customers que são referenciadas na declaração explore são definidas em outro lugar, nos respectivos arquivos de visualização.

connection: order_database
include: "filename_pattern"

explore: orders {
  join: customers {
    sql_on: ${orders.customer_id} = ${customers.id} ;;
  }
}

Neste exemplo, o parâmetro connection é usado para especificar a conexão com o banco de dados para o modelo, e o parâmetro include é usado para especificar os arquivos que estarão disponíveis para o modelo fazer referência.

A declaração explore nesse exemplo também especifica as relações de mesclagem entre visualizações. Para detalhes sobre as declarações join, acesse a seção sobre mesclagens nesta página. Acesse a página de documentação Parâmetros de mesclagem para mais detalhes sobre os parâmetros do LookML que podem ser usados com o parâmetro join.

Campos de dimensão e medição

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

No Looker, uma dimensão é um campo agrupável e pode ser usada para filtrar os resultados da consulta. Pode ser qualquer um dos seguintes valores:

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

No Looker, as dimensões sempre aparecem na cláusula GROUP BY do SQL gerado pelo Looker.

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

Uma medida é um campo que usa uma função agregada do SQL, como COUNT, SUM, AVG, MIN ou MAX. Qualquer campo calculado com base nos valores de outros valores de medição também é uma medida. As medições podem ser usadas para filtrar valores agrupados. Por exemplo, as medidas da visualização Vendas podem incluir o total de itens vendidos (uma contagem), o preço total de venda (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 medidas, os tipos incluem funções de agregação, como sum e percent_of_previous. Para mais detalhes, consulte os tipos de dimensão e tipos de medidas.

No Looker, os campos são listados na página Explorar do seletor de campo, no lado esquerdo da página. É possível expandir uma visualização no seletor de campo para mostrar a lista de campos disponíveis para consulta nessa visualização.

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.

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

Você também pode definir um 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 com modelo.

Consulte a página de documentação Parâmetros de campo para ver todos os detalhes sobre a declaração de 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 unida à Explore. Quando um usuário cria uma consulta que inclui campos de várias visualizações, o Looker gera automaticamente uma lógica de mesclagem SQL para inserir todos os campos da forma correta.

Confira um exemplo de mesclagem 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 mais detalhes, acesse a página de documentação Como trabalhar com mesclagens no LookML.

Arquivos de manifesto do projeto

Seu projeto pode conter um arquivo de manifesto do projeto, que é usado em configurações para envolvidos no projeto. Por exemplo, para especificar outros projetos que serão importados para o projeto atual, definir constantes do LookML, especificar configurações de localização de modelo e adicionar extensões e visualizações personalizadas ao seu projeto.

Cada projeto pode ter apenas um arquivo de manifesto. O arquivo precisa ser nomeado como manifest.lkml e estar localizado no nível raiz do repositório Git. Ao usar pastas no ambiente de desenvolvimento integrado, mantenha o arquivo manifest.lkml no nível raiz da estrutura de diretórios do projeto.

Para importar arquivos LookML de outro projeto, use o arquivo de manifesto do projeto para especificar um nome para o projeto atual e o local dos projetos externos, que podem ser armazenados de forma local ou remota. 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, use o parâmetro include no arquivo de modelo para adicionar arquivos desses projetos externos 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 localização ao 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 na localização do seu 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 detalhamento são especificados campo a campo para que você tenha controle total sobre quais dados 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 de conjunto em uma visualização order_items, definindo campos que listam detalhes relevantes sobre um item comprado. Observe que o conjunto faz referência a 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 todos os detalhes de uso dos conjuntos.

Detalhar

No Looker, é possível configurar um campo para que os usuários possam detalhar ainda mais os dados. O detalhamento funciona em tabelas de resultados de consulta e em painéis. O detalhamento inicia uma nova consulta restrita pelo valor em que você clica.

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

  • Quando você detalha uma dimensão, a nova consulta filtra o valor detalhado. Por exemplo, se você clicar na data específica em uma consulta de pedidos dos clientes por data, a nova consulta mostrará os pedidos somente nessa data específica.
  • Ao detalhar uma medida, a nova consulta mostrará o conjunto de dados que contribuiu para a medida. Por exemplo, ao detalhar uma contagem, a nova consulta mostrará as linhas para calcular essa contagem. Ao detalhar as medidas máxima, mínima e média, o detalhamento ainda mostra todas as linhas que contribuíram para essa medida. Isso significa que o detalhamento de uma medida máxima, por exemplo, mostra todas as linhas que foram usadas para calcular o valor máximo, não apenas uma única linha para o valor máximo.

Os campos que serão exibidos para a nova consulta de detalhamento podem ser definidos por um conjunto ou pelos parâmetros drill_fields (para campos) ou drill_fields (para visualizações).

Tabelas derivadas

Uma tabela derivada é uma consulta com resultados 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 elas fossem tabelas físicas com um conjunto próprio de colunas. Uma tabela derivada é exposta como uma visualização própria 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 combinada a outras visualizações, assim como qualquer outra visualização.

As tabelas derivadas também podem ser definidas como tabelas derivadas persistentes (TDPs), que são tabelas derivadas gravadas em um esquema de rascunho no banco de dados e regeneradas automaticamente de acordo com a programação especificada com uma estratégia de persistência.

Para mais informações, consulte a página de documentação Tabelas derivadas no Looker.

Conexão com o banco de dados

Outro elemento importante de um projeto do LookML é a conexão do banco de dados que o Looker usa para executar consultas. 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. Se você gerar um projeto LookML no banco de dados, o Looker vai preencher automaticamente o parâmetro connection no arquivo de modelo.

Diferenciação entre maiúsculas e minúsculas

O LookML diferencia maiúsculas de minúsculas. Portanto, faça a correspondência entre elas ao se referir a elementos do LookML. O Looker alerta você se você mencionar um elemento que não existe.

Por exemplo, suponha que você tenha uma Análise chamada e_flights_pdt e um desenvolvedor do LookML use letras maiúsculas incorretamente (e_FLIGHTS_pdt) para fazer referência a essa Análise. Neste exemplo, o ambiente de desenvolvimento integrado do Looker mostra um aviso de que a e_FLIGHTS_pdt da Análise não existe. Além disso, o ambiente de desenvolvimento integrado sugere o nome de uma Análise já existente, que é e_flights_pdt:

No entanto, se o projeto contivesse e_FLIGHTS_pdt e e_flights_pdt, o ambiente de desenvolvimento integrado do Looker não conseguirá corrigir você, portanto, será necessário ter certeza de qual versão você quer. Geralmente, é uma boa ideia usar letras minúsculas ao nomear objetos LookML.

Os nomes das pastas do ambiente de desenvolvimento integrado também diferenciam maiúsculas de minúsculas. Use letras maiúsculas nos nomes de pastas sempre que especificar caminhos de arquivos. Por exemplo, se você tiver uma pasta chamada Views, use a mesma letra maiúscula no parâmetro include. Novamente, o ambiente de desenvolvimento integrado do Looker vai indicar um erro se a capitalização não corresponder a uma pasta do seu projeto:

O ambiente de desenvolvimento integrado do Looker mostra um aviso informando que a inclusão não corresponde a nenhum arquivo.