Como importar arquivos de outros projetos

É possível importar arquivos de outros projetos do LookML e repositórios externos para seu projeto atual. Isso permite que você use arquivos de modelo, arquivos de visualização e outros arquivos em mais de um projeto.

Há vários casos de uso para isso. Alguns exemplos:

  • Criar em um bloco do Looker instalado sem precisar fazer alterações diretas nele. Se o Looker fizer alterações no bloco, você poderá extraí-las porque todo o LookML adicionado a ele fica em um repositório separado.

  • Manter um projeto base que é gerado automaticamente com base no esquema do banco de dados. É possível colocar todas as suas dimensões, medições e similares em um projeto separado que importa todo o LookML do projeto gerado automaticamente. É possível gerar novamente o projeto base regularmente conforme o esquema do banco de dados for alterado sem substituir todo o LookML personalizado.

  • Encapsular objetos compartilhados em um único projeto e importá-los para vários outros projetos. Por exemplo, se você tiver uma tabela comum a vários bancos de dados, poderá colocar a visualização dela em um projeto e mantê-la em um só lugar. Em seguida, importe a tabela para esses projetos para que vários outros projetos a usem.

Para importar arquivos de outro projeto, execute as seguintes tarefas:

  1. Crie um arquivo de manifesto do projeto.
  2. Especifique os projetos locais ou remotos que você quer importar.
  3. Veja os arquivos de um projeto importado.
  4. Inclua arquivos de um projeto importado.

Você poderá fazer referência a campos dos arquivos importados do projeto e substituir os valores das constantes definidos no projeto importado se as constantes allow override.

Como criar um arquivo de manifesto do projeto

Qualquer projeto que importe arquivos de outros projetos precisa ter um arquivo de manifesto de projeto. Se o projeto ainda não tiver um arquivo de manifesto, crie um no ícone + na parte de cima do navegador de arquivos no ambiente de desenvolvimento integrado do Looker.

Para importar projetos, especifique-os no manifesto. É possível especificar projetos locais ou remotos, conforme descrito nas seções a seguir.

Importação de projetos locais

A importação de projetos locais só pode ser usada se o projeto importado estiver na mesma instância do Looker. Também é recomendado que os desenvolvedores tenham permissões de modelo para os modelos do projeto importado. Se os desenvolvedores tiverem permissões de modelo no projeto importado, o controle de versões será dinâmico. Isso significa que as mudanças no projeto importado vão afetar imediatamente o projeto que o importa. Isso permite que os desenvolvedores validem as mudanças nos dois projetos antes de enviar para produção. Além disso, para desenvolvedores com permissões de modelo nos dois projetos, os arquivos importados refletirão o status do Modo de Desenvolvimento. Portanto, se o desenvolvedor estiver no Modo de Desenvolvimento, o Looker IDE vai mostrar o Modo de Desenvolvimento dos arquivos importados do projeto. Se o desenvolvedor estiver no Modo de produção, o Looker IDE vai mostrar o Modo de produção do projeto importado.

No arquivo de manifesto, o parâmetro project_name especifica o nome do projeto atual. O Looker preenche esse parâmetro automaticamente quando você cria o arquivo de manifesto para o projeto. Se quiser importar um projeto local para o atual, use um ou mais parâmetros local_dependency e especifique os projetos a serem importados:

# This project
project_name: "my_project"

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

Nos cenários a seguir, use a importação de projeto remoto em vez da importação de projeto local:

  • Seus desenvolvedores não têm permissões de modelo nos modelos do projeto importado. Quando esse é o caso, o Looker clona o Modo de Produção do projeto importado e mostra essa versão estática dos arquivos no ambiente de desenvolvimento integrado. Essa versão estática nunca mostraria a versão do Modo de desenvolvimento dos arquivos e também pode estar desatualizada em relação ao Modo de Produção atual sem alertar o desenvolvedor. É melhor usar a importação remota de projetos e fornecer um ref que especifique uma ramificação ou uma versão do Git no projeto remoto. Se você fizer isso, o Looker detectará automaticamente novas confirmações no projeto remoto para que os desenvolvedores sejam alertados e possam usar a versão mais recente dos arquivos do projeto remoto.
  • Seus desenvolvedores precisam sempre trabalhar com a versão de produção de um projeto importado.
  • Seus desenvolvedores precisam trabalhar com uma versão estática dos arquivos importados do projeto.

Importação de projetos remotos

Em uma importação remota, o projeto importado não precisa estar na mesma instância. Em vez disso, o projeto é importado por meio do repositório Git remoto dele.

Para importar um repositório remoto, use o parâmetro remote_dependency e forneça as informações dele. O parâmetro remote_dependency usa as seguintes informações e subparâmetros:

  • O nome do projeto importado, que pode ser o que você quiser. No exemplo abaixo, o nome do projeto é ga_360_block. Use esse nome em instruções include para fazer referência aos arquivos importados em projetos do LookML. Ele também é usado como o nome da pasta na pasta imported_projects do ambiente de desenvolvimento integrado do Looker.
  • O subparâmetro url, em que você especifica o endereço do repositório Git externo. Use o URL principal do repositório.
  • O subparâmetro ref, em que você especifica uma ramificação do Git, uma tag de versão do Git ou o SHA de uma confirmação no repositório Git. Se quiser um controle de versões estático, especifique um SHA de confirmação para que as mudanças no projeto importado não sejam refletidas automaticamente no projeto. Essa é uma boa opção para os blocos do Looker. Você também pode especificar uma ramificação ou uma tag de versão Git se quiser que o Looker detecte automaticamente novas confirmações no projeto remoto. Consulte a seção Como detectar automaticamente novas versões de um projeto remoto nesta página para saber mais.
  • O subparâmetro override_constant, que é opcional, permite substituir o valor de uma constante definida em um projeto importado.

Confira um exemplo de parâmetro remote_dependency em um arquivo de manifesto do projeto. Este exemplo usa uma conexão HTTPS:

remote_dependency: ga360_block {
  url: "https://github.com/llooker/google_ga360"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

Também é possível usar SSH:

remote_dependency: ga360_block {
  url: "git@github.com:llooker/google_ga360.git"
  ref: "master"
  override_constant: connection {
    value: "importing_project_connection"
  }
}

Depois de adicionar a dependência remota, talvez seja necessário configurar as credenciais de importação para o projeto remoto. Consulte a seção Como configurar credenciais de autenticação para repositórios remotos privados nesta página.

Detecção automática de novas versões de um projeto remoto

O Looker poderá detectar automaticamente novas confirmações no projeto remoto se você especificar uma ramificação do Git ou uma tag de versão do Git no subparâmetro ref de remote_dependency no arquivo de manifesto.

Por exemplo, esta é uma dependência remota em que a ramificação master é especificada no subparâmetro ref:

remote_dependency: exchange_rate {
  url: "https://github.com/llooker/datablocks-exchangerate.git"
  ref: "master"
}

Depois, quando a ramificação master for atualizada com novas confirmações, o Looker detectará automaticamente as mudanças.

Veja um exemplo em que a tag de lançamento v1.0 é especificada:

remote_dependency: e_faa_original {
  url: "https://github.com/llooker/google_ga360"
  ref: "v1.0"
}

Independentemente do tipo de valor especificado para o parâmetro ref, mesmo um SHA de confirmação, o ambiente de desenvolvimento integrado vai mostrar o botão Atualizar dependências na barra de navegação superior do projeto quando você adicionar um parâmetro remote_dependency ao projeto.

Clique em Update Dependencies para trazer os arquivos de projeto remoto. Se essa for a primeira dependência remota adicionada ao projeto, a atualização das dependências também vai solicitar que o Looker crie um arquivo de bloqueio de manifesto. O Looker usa o arquivo de bloqueio de manifesto para rastrear a versão dos projetos remotos.

Se você especificar uma ramificação do Git ou uma tag de versão do Git no subparâmetro ref, o Looker vai verificar se há novas confirmações sempre que o ambiente de desenvolvimento integrado do Looker for atualizado, o que acontece quando um desenvolvedor do Looker entra no Modo de Desenvolvimento, realiza uma ação do Git no ambiente de desenvolvimento integrado ou atualiza o navegador.

Se houver novas confirmações, o Looker exibirá a opção Update Dependencies no painel de ações do Git do ambiente de desenvolvimento integrado.

Selecione a opção Update Dependencies para trazer os arquivos remotos mais recentes para o seu projeto.

Com os arquivos mais recentes, é possível validar seu LookML para verificar se todas as referências do seu projeto funcionam com os arquivos de projeto remoto atualizados. Depois disso, é possível corrigir referências corrompidas e implantar as alterações sem inatividade para os usuários.

Arquivo de bloqueio de manifesto

O Looker usa o arquivo de bloqueio de manifesto com o nome de arquivo manifest_lock.lkml para rastrear as versões de projetos importados remotos. O arquivo de bloqueio de manifesto aparece no painel do navegador de arquivos do Looker IDE.

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

O arquivo de bloqueio de manifesto mostra cada projeto remoto, representado por uma entrada remote_dependency com os subparâmetros url e ref:

  • O parâmetro remote_dependency indica o nome do projeto remoto que um desenvolvedor do Looker especificou no arquivo de manifesto.
  • O subparâmetro url indica o endereço do repositório Git externo que um desenvolvedor do Looker especificou no arquivo de manifesto.
  • O subparâmetro ref mostra a versão do projeto (indicada por um SHA de confirmação) que o Looker está usando no projeto:
    • Se o projeto remoto tiver sido definido no arquivo de manifesto com um ref de uma ramificação do Git ou uma tag de versão do Git, o parâmetro ref vai mostrar qual versão dos arquivos (o SHA de commit do projeto remoto) seu projeto está usando no momento. Se houver novas confirmações no projeto remoto, o Looker vai mostrar o botão Atualizar dependências no ambiente de desenvolvimento integrado para que você possa importar os arquivos mais recentes do projeto remoto. O valor ref no arquivo de bloqueio de manifesto será atualizado para mostrar o SHA de commit mais recente para essa ramificação ou tag de lançamento.
    • Se o projeto remoto tiver sido definido no arquivo de manifesto com um ref de um SHA de confirmação específico, o parâmetro ref no arquivo de bloqueio de manifesto será o mesmo SHA de confirmação.

Como configurar credenciais de autenticação para repositórios remotos particulares

Para configurar credenciais de autenticação para repositórios remotos particulares, acesse a página Importar credenciais selecionando Configurações no painel de navegação esquerdo do ambiente de desenvolvimento integrado.

As configurações de Importar credenciais mostram uma lista dos URLs de cada repositório remoto que foi definido no arquivo de manifesto do projeto, o tipo de autenticação usado para o repositório (https ou ssh) e se o Looker consegue se conectar ao repositório.

Como adicionar credenciais de autenticação

Para adicionar credenciais de autenticação a um repositório:

  1. Na página Importar credenciais, no título URL, mantenha o ponteiro do mouse sobre o nome de um repositório para exibir os botões Testar e Configurar e clique em Configurar.

  2. O Looker exibe a caixa de diálogo Configure Git Authentication para permitir que você configure as credenciais do repositório remoto. A caixa de diálogo vai indicar o tipo de credenciais necessárias para esse repositório específico.

    • Se o repositório exigir um nome de usuário e uma senha (ou token de acesso pessoal) para autenticação, digite o nome de usuário e a senha ou o token e clique em Salvar alterações.

    • Se o repositório exigir uma chave SSH, como no exemplo de uso do SSH para importar um projeto remoto explicado anteriormente nesta página, o Looker vai mostrar uma caixa de diálogo mostrando a chave SSH local. Clique em Copiar chave para copiar a chave SSH para a área de transferência e adicioná-la à lista de chaves do repositório.

  3. Depois de salvar as credenciais, clique em Testar para testar o acesso do Looker ao repositório.

    Depois de passar nos testes de conexão e se conectar ao repositório, a seção Importar credenciais mostrará uma marca de seleção verde ao lado do nome do repositório.

Como editar credenciais de autenticação

Para editar as credenciais de autenticação de um repositório:

  1. Para exibir os botões Testar e Editar, mantenha o ponteiro do mouse sobre um repositório que já tenha credenciais de autenticação configuradas e clique em Editar.

  2. Se o repositório exigir um nome de usuário e uma senha (ou token de acesso pessoal) para autenticação, clique em Limpar credenciais e, na caixa de diálogo de confirmação, clique em Sim, limpar credenciais.

  3. Digite as novas credenciais na caixa de diálogo Configure Git Authentication e clique em Save Changes.

Como visualizar arquivos de um projeto importado

O Looker IDE mostra arquivos de projetos importados na pasta imported_projects do painel de navegação à esquerda. Você pode selecionar um arquivo de projeto importado para ver o conteúdo dele.

Arquivos de projetos locais e projetos remotos são listados na pasta imported_projects.

Também é possível ver objetos de arquivos de projeto importados que estão incluídos no projeto ativo no navegador de objetos. Acesse o navegador de objetos na barra de navegação do Looker IDE.

Além disso, os usuários com a permissão develop podem usar o painel de metadados para ver informações sobre objetos de projetos importados, incluindo links para navegar até o arquivo importado em que o objeto está definido. Consulte a página de documentação Metadados de objetos do LookML para mais informações.

Como incluir arquivos de um projeto importado

O parâmetro include em um arquivo de modelo especifica os arquivos de projeto que estarão disponíveis para esse modelo. Depois de especificar um projeto importado local ou remoto no arquivo de manifesto, use o parâmetro include em um arquivo de modelo para especificar arquivos do projeto importado. Somente arquivos com o projeto listado no arquivo de manifesto podem ser incluídos.

Para usar o comando include em um arquivo de outro projeto, use o nome do arquivo com duas barras (//) e o nome do projeto importado. Coloque uma única barra (/) no nome do projeto importado e o caminho completo do arquivo que você quer incluir.

Por exemplo, estes comandos include indicam o arquivo de visualização users do projeto importado e_flights e a visualização orders do projeto importado e_commerce:

include: "//e_flights/views/users.view.lkml"
include: "//e_commerce/public/orders.view.lkml"

Consulte a seção Sintaxe do caminho da página de parâmetros include para informações sobre como especificar caminhos com pastas do ambiente de desenvolvimento integrado ativadas.

É possível usar caracteres curinga para incluir vários arquivos. Por exemplo, para incluir todos os arquivos de visualização no diretório /views/ do projeto importado e_flights:

include: "//e_flights/views/*.view"

Além disso, é possível usar caracteres curinga para definir níveis de diretório específicos ou diretórios recursivos no projeto importado:

include: "//e_flights/*/*.view.lkml"
include: "//e_commerce/*/*.view.lkml"

Consulte a seção Exemplos de caracteres curinga da página de parâmetros include para saber mais sobre o uso de caracteres curinga com pastas do ambiente de desenvolvimento integrado ativadas.

Como incluir arquivos de modelo

Não é possível incluir um arquivo modelo de outro projeto. Em vez disso, se você quiser reutilizar, refinar ou ampliar as Análises em vários projetos, no projeto importado, crie um arquivo separado e inclua esse arquivo em outros projetos. Consulte a seção Como incluir análises em um modelo da página de documentação do parâmetro include para saber mais.

Como incluir arquivos com outros arquivos

Quando você inclui um arquivo que inclui outros arquivos, todas as inclusões são resolvidas antes que o arquivo seja passado para o próximo projeto que o inclui.

Por exemplo, se no projeto atual você importar um arquivo (A) de outro projeto (proj_A) e o arquivo importado contiver um parâmetro include que inclui o arquivo B do projeto proj_B, o arquivo B será incluído no arquivo A antes que o A seja importado para o projeto atual.

Como importar arquivos de dados

Os arquivos armazenados na seção "Dados" de um projeto não são importados. Para referenciar um arquivo de dados de um projeto importado, como no parâmetro map_layer, use o caminho completo e o nome do arquivo. Exemplo:

map_layer: json_from_imported_project {
  file: "//path_to_imported_project/folder/filename.topojson"
  ...
}

Como referenciar arquivos de um projeto importado

Depois de importar um arquivo de visualização para o projeto, use a sintaxe ${view_name.field_name} para fazer referência aos campos da visualização importada, como se o arquivo fizesse parte do projeto. Por exemplo, digamos que você importou o projeto ga_360_block para o arquivo de manifesto do projeto e tem a seguinte instrução include no arquivo de modelo:

include: "//ga_360_block/ga_block.view"

Use a sintaxe ${ga_block.hits_total} para fazer referência ao campo hits_total da visualização ga_block incluída.

Como usar constantes em arquivos de um projeto importado

As constantes do LookML permitem definir um valor no arquivo de manifesto do projeto que pode ser reutilizado em todo o projeto. O subparâmetro export do parâmetro constant especifica se o valor de uma constante pode ser substituído quando os arquivos que fazem referência a essa constante são importados para outro projeto.

O parâmetro export tem os seguintes valores possíveis:

  • none: o valor padrão de export. Não é possível substituir o valor da constante no projeto de importação. O projeto de importação usa o valor constante especificado no arquivo de manifesto do projeto importado.
  • override_optional: o valor da constante pode ser substituído no seu projeto de importação. Se um valor não for fornecido no arquivo de manifesto do projeto de importação, o valor original do projeto importado será usado.
  • override_required: o projeto de importação precisa substituir o valor da constante especificado originalmente no arquivo de manifesto do projeto importado. Se um novo valor constante não for fornecido no projeto de importação, o Looker vai mostrar um erro.

Ao importar arquivos que fazem referência a uma constante para seu projeto, é possível usar o subparâmetro override_constant de local_dependency ou remote_dependency no arquivo de manifesto do projeto para fornecer um novo valor para essa constante, desde que essa constante tenha export definido como override_optional ou override_required no projeto original. Quando você substitui o valor de uma constante de um projeto importado, seu projeto usa o valor especificado com o parâmetro override_constant.

Por exemplo, suponha que você esteja gerenciando vários bancos de dados em uma única instância do Looker, com um projeto separado para cada banco de dados. Além disso, suponha que os esquemas de dados são idênticos para cada banco de dados e que seu objetivo é definir uma análise uma vez e aplicá-la a cada conjunto de dados.

Neste exemplo, suponha que proj_core seja o projeto base com visualizações definidas que você gostaria de importar para outros projetos. Além disso, uma das visualizações que você quer importar é a orders, definida da seguinte maneira:


view: orders {
  sql_table_name: "@{schema_name}.orders"
}

O esquema em que a visualização orders se baseia é especificado no parâmetro sql_table_name usando a constante schema_name, definida no arquivo de manifesto proj_core. No exemplo a seguir, como a constante schema_name está definida como export: override_required, qualquer projeto que importar schema_name precisará substituir o valor usando o parâmetro override_constant:


constant: schema_name {
  value: "proj_core_schema"
  export: override_required
}

Por exemplo, suponha que você queira importar a visualização orders para um projeto local chamado proj_a. Há também uma tabela chamada orders no banco de dados de proj_a com uma estrutura idêntica à tabela orders no projeto base, proj_core.

Como proj_core e proj_a estão na mesma instância, você pode importar a visualização orders para o proj_a usando local_dependency. Usando o subparâmetro override_constant de local_dependency, você pode atualizar a constante schema_name para apontar para o esquema proj_a_schema no arquivo de manifesto para proj_a:


project_name: "proj_a"

local_dependency: {
  project: "proj_core"
  override_constant: schema_name {
    value: "proj_a_schema"
  }
}

Neste exemplo, como a constante schema_name está definida como export: override_required em project_core, o Looker exibirá um erro se você não substituir o valor em proj_a (o projeto de importação).

A substituição da constante schema_name em proj_a permite usar os campos definidos na visualização orders em proj_core, em vez de criar um novo arquivo de visualização e definir seus campos do zero. Neste exemplo, a visualização orders corresponde a uma tabela diferente para cada projeto:

  • Em proj_core, a visualização orders é baseada na tabela proj_core_schema.orders no seu banco de dados.
  • Em proj_a, a visualização orders é baseada na tabela proj_a_schema.orders no seu banco de dados.