Tipos de arquivos em um projeto do LookML

Um projeto do LookML é uma coleção de arquivos LookML que informam ao Looker como se conectar ao banco de dados, consultar os dados e controlar o comportamento da interface do usuário. Você pode acessar os arquivos de projeto do LookML na seção Desenvolver do Looker ou na UI, conforme descrito na página de documentação Acessar arquivos de projeto do LookML.

Os arquivos de projeto são organizados pelos desenvolvedores do Looker usando pastas no IDE.

Um projeto do LookML consiste em pelo menos um arquivo de modelo e um arquivo de visualização, além de possivelmente alguns dos outros tipos de arquivos descritos nesta página. Todos os arquivos de projeto têm extensões, embora elas fiquem ocultas na lista do ambiente de desenvolvimento integrado se o projeto não estiver ativado para pastas no ambiente de desenvolvimento integrado.

Selecione os links a seguir para mais informações sobre cada um dos tipos de arquivos que podem ser usados em um projeto do LookML:

• Arquivos de modelo com a extensão .model.lkml
• Ver arquivos com extensão .view.lkml
• Arquivos de painel com a extensão .dashboard.lookml
• Arquivos de dados com extensão .topojson, .geojson ou .json
• Arquivos de documentos com a extensão .md
• Arquivos de manifesto do projeto, que sempre são chamados de manifest.lkml
• Arquivos de bloqueio de manifesto com a extensão .lkml
• Arquivos de strings de localidade com a extensão .strings.json
• Explorar arquivos com a extensão .explore.lkml
• Arquivos de teste de dados com a extensão .lkml
• Arquivos de refinamentos com a extensão .lkml
• Outros arquivos com qualquer extensão que não tenha sido listada antes

Observação: se você não for um desenvolvedor avançado do LookML, recomendamos que siga os tipos de arquivo padrão do LookML no início. Alguns elementos do LookML precisam estar em tipos de arquivos específicos, como os parâmetros do manifesto do projeto em LookML, que precisam estar no arquivo manifest.lkml de um projeto, e o parâmetro connection, que precisa estar em um arquivo .model.lkml. No entanto, a LookML é bastante flexível, e muitos elementos podem ser armazenados em qualquer arquivo .lkml. Os desenvolvedores de LookML muito avançados podem usar a criatividade com arquivos LookML, usando o parâmetro include para referenciar elementos de um arquivo LookML em outro, como usando refinamentos para adicionar camadas de análise, criando arquivos dedicados para testes de dados etc.

Depois de criar um projeto do LookML, você pode acessar os arquivos do projeto e adicionar novos arquivos e pastas ao projeto usando o Looker IDE.

Arquivos de modelo

Um arquivo de modelo especifica uma conexão de banco de dados e o conjunto de Explorars que usam essa conexão. Um arquivo de modelo também define as próprias análises detalhadas e as relações delas com outras visualizações. Uma Análise é um ponto de partida para consultar seus dados. Em termos de SQL, uma análise detalhada é a cláusula FROM de uma consulta. As análises detalhadas definidas no modelo são mostradas aos usuários quando eles acessam o menu Análise do Looker.

Em outras palavras, o arquivo de modelo é onde você define quais tabelas de dados devem ser usadas (como visualizações incluídas) e como elas devem ser unidas, se necessário.

Observação: as Análises geralmente são definidas em um arquivo de modelo. No entanto, às vezes, você precisa de um arquivo de análise separado para uma tabela derivada ou para estender ou refinar uma análise em vários modelos.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de modelo.

Estrutura e sintaxe geral

Dentro das chaves de uma análise detalhada, { }, você define parâmetros para a análise. É possível usar parâmetros join para unir outras visualizações a uma análise detalhada em um arquivo de modelo.

No exemplo a seguir, a LookML em um arquivo de modelo de exemplo define uma análise detalhada chamada inventory_items, com as visualizações unidas:

connection: "thelook_events"

explore: inventory_items {
  join: products {
    type: left_outer
    sql_on: ${inventory_items.product_id} = ${products.id} ;;
    relationship: many_to_one
  }

  join: distribution_centers {
    type: left_outer
    sql_on: ${products.distribution_center_id} = ${distribution_center.id} ;;
    relationship: many_to_one
  }
}

Essa definição da LookML faz com que Itens de inventário apareça na seção Explorar da navegação do Looker e une dados das visualizações products e distribution_centers à visualização inventory_items.

Para mais informações específicas sobre as estruturas do LookML em um arquivo de modelo, consulte a página de documentação Termos e conceitos do LookML.

Leia as páginas de documentação Parâmetros do modelo, Parâmetros de análise detalhada e Parâmetros de junção para saber mais sobre os parâmetros da LookML no arquivo de modelo.

Mostrar arquivos

Um arquivo de visualização geralmente define uma única "visualização" no Looker. Uma visualização corresponde a uma única tabela no seu banco de dados ou a uma única tabela derivada. O arquivo de visualização especifica uma tabela para consultar e os campos (dimensões e medidas) a serem incluídos dessa tabela para que os usuários possam criar consultas com esses campos na interface do Looker.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de visualização.

Estrutura e sintaxe geral

Dentro das chaves de cada visualização, { }, estão as definições de campo, que geralmente correspondem a uma coluna na tabela subjacente ou a um cálculo no Looker. O Looker categoriza a maioria dessas definições como dimensões ou medidas.

No exemplo a seguir de um arquivo de visualização, o arquivo orders.view inclui definições para as dimensões id, status e user_id, o grupo de dimensões created e a métrica count:

view: orders {
  sql_table_name: demo_db.orders ;;
  drill_fields: [id]

  dimension: id {
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }

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

  dimension: user_id {
    type: number
    # hidden: yes
    sql: ${TABLE}.user_id ;;
  }

    dimension_group: created {
    type: time
    timeframes: [
      raw,
      time,
      date,
      week,
      month,
      quarter,
      year
    ]
    sql: ${TABLE}.created_at ;;
  }

  measure: count {
    type: count
    drill_fields: [id, users.id, users.first_name, users.last_name, order_items.count]
  }
}

A definição desses campos na visualização orders expõe os campos Data de criação, ID, Status, User-ID e Contagem no seletor de campos da Análise Pedidos.

Os usuários que têm acesso à análise detalhada Pedidos podem consultar essa análise selecionando e filtrando esses campos.

Além de dimensões e medidas, você também pode criar várias dimensões com base em tempo de uma só vez usando grupos de dimensões ou especificar um filtro para seus usuários com campos de filtro. Acesse a página de documentação Parâmetros de visualização para saber mais sobre os parâmetros da LookML em arquivos de visualização e a página de documentação Parâmetros de campo para informações sobre os parâmetros da LookML usados para definir dimensões, métricas, grupos de dimensões e campos de filtro na LookML.

Arquivos do painel

O Looker é compatível com dois tipos de painéis:

• Painéis definidos pelo usuário, que podem ser criados por usuários não desenvolvedores sem usar o LookML. Para mais detalhes, consulte a página de documentação Criar painéis definidos pelo usuário.
• Dashboards do LookML, que são armazenados como arquivos com controle de versões associados ao projeto.

Se o projeto tiver painéis do LookML, eles serão definidos em arquivos dedicados no IDE, com a extensão .dashboard.lookml.

Para mais informações sobre painéis do LookML, consulte a página de documentação Como criar painéis do LookML.

Arquivos de documentos

Com os arquivos de documentos do Looker, é possível escrever documentação ou outras observações sobre seu modelo de dados do Looker usando o Markdown com sabor do GitHub. Isso pode ser útil para que os usuários conheçam a forma como sua organização usa o Looker.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de documentos.

Visualizar o documento fora do ambiente de desenvolvimento integrado

Para ver um documento fora do IDE, o que é necessário para aproveitar os recursos de navegação descritos nesta página, escolha a opção Ver documento no menu Ver ações do arquivo do arquivo de documento:

Você pode distribuir o URL da página resultante para outros usuários para que eles possam acessar o documento diretamente sem precisar navegar pelo menu Desenvolvimento do Looker.

Adicionar uma estrutura de navegação ao documento

Você pode adicionar uma barra lateral aos arquivos de documentos para que os usuários vejam a estrutura das informações e naveguem entre os documentos.

Para adicionar a navegação na barra lateral a um documento, crie uma seção de navegação começando na primeira linha do documento. Marque o início e o fim da seção de navegação com três traços (---).

É possível usar os seguintes parâmetros na seção de navegação:

• navigation
• title
• section
• label

navigation

É possível usar navigation: true em um arquivo de documento para adicionar a barra lateral de navegação a ele. Por exemplo, você pode adicionar o seguinte código à parte de cima de um arquivo Markdown:

---
navigation: true
---

Esse código adiciona ao documento uma barra lateral de navegação com links para todos os documentos do projeto. Se você incluir apenas navigation: true em um documento, a barra lateral dele vai listar todos os documentos do projeto em ordem alfabética por nome de arquivo.

Além disso, talvez você descubra que organizar por nome de arquivo em ordem alfabética não é o ideal ou tenha alguns documentos que não quer que apareçam na navegação:

Neste exemplo, talvez você queira listar os documentos Document One, Document Two, Document Three e Document Four em ordem numérica em vez de alfabética, além de ocultar o documento Do Not Display da barra lateral de navegação.

Para mudar a ordem dos documentos na barra lateral de navegação ou mostrar apenas um subconjunto deles, use este formato:

---
navigation:
  - document_one
  - document_two
  - document_three
  - document_four
---

Agora a navegação vai mostrar apenas os arquivos de documentos que você quer que apareçam, e eles vão aparecer em uma ordem mais lógica:

title

Por padrão, a barra lateral mostra o título do documento (se ele começar com um título) ou o nome do arquivo, se não houver um título. Você pode adicionar um parâmetro title na parte de cima de um documento para mudar a forma como ele é mostrado nas barras laterais de navegação:

---
title: New Title for Users
---

Esse título será usado como o texto do link nas barras laterais de navegação de todos os documentos, a menos que você especifique um label diferente na seção de navegação de um documento.

label

Se você quiser mudar a forma como um documento é listado na barra lateral de navegação, use os parâmetros document e label desta forma:

---
navigation:
  - document_one
  - document: document_two
    label: Customized Label for Document Two
  - document_three
  - document_four
---

Observação: para usar o parâmetro label, adicione document: antes do nome do arquivo do documento, como mostrado no exemplo anterior. Se você não estiver usando um label para um documento, não inclua document: antes do nome do arquivo.

O valor label define como um documento é mostrado na navegação da barra lateral, mesmo que o documento a que ele se refere tenha o próprio parâmetro title.

O exemplo anterior aparece assim na barra lateral do documento:

section

Se quiser dividir a barra lateral de navegação em seções, use o parâmetro section assim:

---
navigation:
  - document_one
  - document_two
  - section: My Section Name
  - document_three
  - document_four
---

Neste exemplo, o parâmetro section adiciona uma quebra de seção e o título do texto Nome da minha seção à barra lateral.

O título do texto não é um link e não se refere a nenhum dos seus arquivos de documento.

Arquivos de dados

Os arquivos de dados são JSON com extensão .json, .topojson ou .geojson.

O parâmetro map_layer permite usar um arquivo JSON como um mapa personalizado que pode ser usado para representar seus dados no Looker.

Em seguida, use o parâmetro map_layer_name com uma dimensão para associar um valor de dados (como "Paris") a uma região geográfica no mapa personalizado.

É possível editar um arquivo JSON no IDE do LookML e selecionar Salvar.

Para depurar, escolha Ver sem formatação selecionando o menu Ver ações do arquivo ao lado do nome do arquivo para conferir o arquivo sem formatação. Se você tiver a extensão adequada para ver JSON no navegador, também terá a opção de conferir o arquivo em um formato Analisado.

Consulte a página de documentação Como gerenciar arquivos e pastas do LookML para instruções sobre como fazer upload de um arquivo JSON para um projeto do LookML.

Arquivos de manifesto do projeto

Seu projeto pode conter um arquivo de manifesto, que é usado para as seguintes tarefas:

• Especificar outros projetos para importar para o projeto atual
• Especificar configurações de localização do modelo
• Como definir constantes do LookML
• Adicionar uma extensão ao projeto
• Adicionar uma visualização personalizada ao projeto

Observação: a localização do modelo não é compatível com a importação de projetos.

Consulte a página de documentação Parâmetros do manifesto do projeto para ver um exemplo de arquivo de manifesto e os possíveis parâmetros para arquivos de manifesto. Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de manifesto do projeto.

Observações sobre arquivos de manifesto do projeto:

• Cada projeto pode ter apenas um arquivo de manifesto, que precisa ser chamado manifest.lkml e estar localizado no nível raiz da estrutura de diretórios do projeto e no repositório Git.
• O Looker não aceita um arquivo de manifesto de projeto vazio. Se o arquivo de manifesto estiver vazio, exclua-o.
• Cada projeto pode ter apenas um arquivo de manifesto.
• O arquivo de manifesto do projeto precisa ser chamado manifest.lkml e estar localizado no nível raiz da estrutura de diretórios do projeto.

Arquivos de bloqueio de manifesto

Os arquivos de bloqueio de manifesto são criados automaticamente quando uma dependência remota é adicionada ao arquivo de manifesto do projeto. O Looker usa o arquivo de bloqueio de manifesto para rastrear a versão dos projetos remotos especificados no arquivo de manifesto. O arquivo de bloqueio de manifesto está listado no painel do navegador de arquivos do Looker IDE e tem o nome manifest_lock.lkml.

Os desenvolvedores do Looker não precisam criar nem editar um arquivo de bloqueio de manifesto, já que eles são gerenciados automaticamente pelo Looker.

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

Arquivos de strings de localidade

Se você estiver localizando seu modelo de dados, será necessário criar arquivos de strings de localidade para cada localidade que você quer localizar, incluindo a localidade padrão (por exemplo, geralmente inglês nos EUA).

Os arquivos de strings de localidade listam pares de chave-valor para cada rótulo e descrição que você está localizando no seu modelo. O arquivo de strings de cada localidade precisa fornecer a tradução dela para cada rótulo ou descrição. Mais informações sobre como criar arquivos de strings de localidade estão na página de documentação Localizar seu modelo do LookML.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de strings de localidade.

Analisar arquivos

Uma Análise é uma visualização que os usuários podem consultar. Uma análise detalhada é o ponto de partida de uma consulta ou, em termos de SQL, a FROM em uma instrução SQL. Consulte a página de documentação Acessar e interagir com as Análises no Looker para saber como os usuários interagem com as Análises para consultar seus dados.

As análises geralmente são definidas em um arquivo de modelo. No entanto, às vezes, você precisa de um arquivo de análise detalhada separado para uma tabela derivada ou para estender ou refinar uma análise detalhada em vários modelos.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de análise detalhada.

Arquivos de teste de dados

Seu projeto pode ter arquivos de teste de dados usados para verificar a lógica do seu modelo do LookML. Os testes de dados podem estar em arquivos de modelo ou de visualização, mas se os desenvolvedores quiserem usar os mesmos testes em vários modelos diferentes, é útil manter os testes de dados em um arquivo dedicado.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de teste de dados.

Arquivos de refinamentos

Seu projeto pode ter arquivos usados para refinamentos do LookML. Com os refinamentos do LookML, é possível adaptar uma visualização ou um Explorar sem editar o arquivo do LookML que o contém. Os refinamentos da LookML podem estar contidos em arquivos de modelo, visualização ou do recurso "Explorar" ou em um arquivo dedicado.

Consulte a página de documentação Gerenciar arquivos e pastas do LookML para instruções sobre como criar arquivos de projeto do LookML, incluindo arquivos de refinamentos.

Outros arquivos

Muitos elementos do LookML podem ser armazenados em arquivos diferentes no projeto ou em arquivos dedicados. Por exemplo, os testes de dados podem ser armazenados em arquivos de modelo, arquivos de visualização ou em arquivos .lkml dedicados.