Google BigQuery

Visão geral

Nesta página, explicamos como configurar uma conexão no Looker com o SQL padrão do Google BigQuery ou o SQL legado do Google BigQuery.

As etapas gerais para configurar uma conexão do SQL padrão do Google BigQuery ou do SQL legado do Google BigQuery são as seguintes:

  1. No banco de dados do BigQuery, configure o método de autenticação que o Looker vai usar para acessar o banco de dados do BigQuery. O Looker é compatível com as seguintes opções de autenticação para o BigQuery:

    • Application Default Credentials: selecione essa opção para usar o Application Default Credentials (ADC) para autenticar no banco de dados.

      Para ativar o ADC, você também precisa definir as seguintes variáveis de ambiente ao iniciar a instância do Looker:

      • FF_SELF_HOSTED_DIALECT_ADC=true

      • GOOGLE_CLOUD_UNIVERSE_DOMAIN="<google_cloud_universe_domain>"

        em que <google_cloud_universe_domain> é o domínio do universo da sua instância do Google Cloud , como apis-berlin-build0.goog ou s3nsapis.fr.

      Defina essa variável usando os seguintes comandos:

      echo 'export FF_SELF_HOSTED_DIALECT_ADC=true' >> lookerstart.cfg

      echo 'export GOOGLE_CLOUD_UNIVERSE_DOMAIN="<google_cloud_universe_domain>"' >> lookerstart.cfg

    • Conta de serviço: consulte a seção Autenticação com contas de serviço do BigQuery nesta página para mais informações.

    • OAuth: consulte a seção Autenticação com OAuth nesta página para mais informações.

  2. No banco de dados do BigQuery, se você quiser usar tabelas derivadas persistentes (PDTs) na conexão, crie um conjunto de dados temporário que o Looker possa usar para criar PDTs no banco de dados. Consulte a seção Como criar um conjunto de dados temporário para tabelas derivadas persistentes nesta página para ver o procedimento.

  3. No Looker, configure a conexão do Looker com seu banco de dados do BigQuery. Consulte a seção Como conectar o Looker ao BigQuery nesta página para ver o procedimento.

  4. No Looker, teste a conexão entre o Looker e o banco de dados do BigQuery. Consulte a seção Como testar a conexão nesta página para ver o procedimento.

Criptografar o tráfego de rede

É uma prática recomendada criptografar o tráfego de rede entre o aplicativo do Looker e seu banco de dados. Considere uma das opções descritas na página de documentação Ativar o acesso seguro ao banco de dados.

Autenticação com contas de serviço do BigQuery

Uma maneira de o Looker autenticar no banco de dados do BigQuery é com uma conta de serviço do BigQuery. Crie a conta de serviço no banco de dados do BigQuery usando o Gerenciador de APIs no console do Google Cloud . Você precisa ter permissões de administrador do Google Cloud para criar a conta de serviço. Consulte a documentação sobre como criar uma conta de serviço.

Criar uma conta de serviço e fazer o download do certificado de credenciais JSON

Para criar uma conta de serviço do BigQuery, siga estas etapas:

  1. Abra a página de credenciais no Gerenciador de APIs no console do Google Cloud e selecione seu projeto.

  2. Selecione CRIAR CREDENCIAIS e escolha Conta de serviço.

  3. Insira um nome para a nova conta de serviço, adicione uma descrição (opcional) e selecione CRIAR E CONTINUAR.

  4. Sua conta de serviço requer dois papéis predefinidos do Google BigQuery:

    • BigQuery > Editor de dados do BigQuery
    • BigQuery > Usuário de jobs do BigQuery

    Selecione o primeiro papel no campo Selecionar um papel, selecione ADICIONAR OUTRO PAPEL e, em seguida, selecione o segundo papel.

    Depois de selecionar os dois papéis, clique em CONTINUAR e em CONCLUÍDO.

  5. Na página Credenciais, selecione sua nova conta de serviço:

  6. Selecione CHAVES, ADICIONAR CHAVE e, no menu suspenso, Criar nova chave:

  7. Selecione JSON em Tipo de chave e clique em CRIAR:

  8. A chave JSON será salva no seu computador.

    Depois de anotar o local do download, selecione FECHAR:

  9. Selecione CONCLUÍDO.

  10. Encontre o endereço de e-mail que corresponde à conta de serviço. Você vai precisar desse endereço para configurar a conexão do Looker com o BigQuery:

  11. Depois de criar a conta de serviço no banco de dados do BigQuery, insira as informações dessa conta e os detalhes do arquivo de certificado nos campos E-mail da conta de serviço, Arquivo JSON/P12 da conta de serviço e Senha da janela Conexões do Looker ao configurar a conexão do Looker com o BigQuery.

Autenticação com OAuth

O Looker é compatível com o OAuth para conexões do Google BigQuery. Isso significa que cada usuário do Looker se autentica no Google com as próprias credenciais do OAuth do Google e autoriza o Looker a acessar o banco de dados.

O OAuth permite que os administradores de banco de dados realizem as seguintes funções:

  • Auditar quais usuários do Looker estão executando consultas no banco de dados.
  • Impor controles de acesso baseados em papéis usando as permissões do Google.
  • Use tokens OAuth para todos os processos e ações que acessam o Google BigQuery, em vez de incorporar IDs e senhas do BigQuery em vários lugares.

Observe o seguinte para conexões do BigQuery com OAuth:

  • Se um administrador de banco de dados alterar as credenciais do cliente OAuth do BigQuery, todas as programações ou alertas de um usuário serão afetados. Os usuários precisam fazer login novamente se o administrador mudar as credenciais do OAuth do BigQuery. Os usuários também podem acessar a página Conta do Looker na página da conta do perfil de usuário para fazer login no Google.
  • Como as conexões do BigQuery que usam OAuth são "por usuário", as políticas de armazenamento em cache também são por usuário, não apenas por consulta. Isso significa que, em vez de usar resultados em cache sempre que a mesma consulta for executada no período de armazenamento em cache, o Looker vai usar resultados em cache somente se o mesmo usuário tiver executado a mesma consulta no período de armazenamento em cache. Para mais informações sobre armazenamento em cache, consulte a página de documentação Como armazenar consultas em cache.
  • Se você quiser usar tabelas derivadas persistentes (TDPs) em uma conexão do BigQuery com OAuth, crie uma conta de serviço adicional para que o Looker acesse seu banco de dados para processos de TDP. Consulte a seção Tabelas derivadas persistentes em uma conexão do BigQuery nesta página para mais informações.
  • Quando um administrador do Looker usa o comando sudo como outro usuário, ele usa o token de acesso OAuth desse usuário. Quando os usuários autorizam uma conexão OAuth no Looker, uma caixa de diálogo Autorizar conexão OAuth notifica que usuários privilegiados do Looker, como administradores ou desenvolvedores, podem ter visibilidade dos dados deles. Consulte a página de documentação Usuários para saber como usar o comando sudo.
  • As conexões do Google BigQuery configuradas para autenticação OAuth não são compatíveis com o encerramento de consultas.

Configurar um projeto de banco de dados do BigQuery para OAuth

As seções a seguir descrevem como gerar credenciais OAuth e como configurar uma tela de permissão OAuth.

Nos casos a seguir, não é necessário realizar esses procedimentos:

As credenciais e a tela de permissão OAuth precisam ser configuradas no console doGoogle Cloud . A descrição genérica do Google está no site de suporte Google Cloud e no site do Google Dev Console.

Dependendo do tipo de usuário que acessa os dados do BigQuery no Looker e se os dados do BigQuery são públicos ou privados, o OAuth pode não ser o método de autenticação mais adequado. Da mesma forma, o tipo de dados solicitados do usuário e o nível de acesso necessário aos dados dele quando ele se autentica no Google para usar o Looker podem exigir a verificação do Google. Saiba mais sobre a verificação na seção Como gerar credenciais do OAuth do Google nesta página.

Como gerar credenciais do OAuth do Google

  1. Acesse o console doGoogle Cloud .

  2. No menu suspenso Selecionar um projeto, acesse seu projeto do BigQuery. Isso vai levar você ao painel do projeto.

  3. No menu à esquerda, selecione a página APIs e serviços. Em seguida, selecione Credenciais. Na página Credenciais, selecione a seta para baixo no botão Criar credenciais e selecione ID do cliente OAuth no menu suspenso:

  4. O Google exige que você configure uma tela de permissão OAuth, que permite que os usuários escolham como conceder acesso aos dados particulares, antes de gerar as credenciais OAuth. Para configurar a tela de permissão OAuth, consulte a seção Como configurar uma tela de permissão OAuth nesta página.

  5. Se você já tiver configurado uma tela de permissão OAuth, o Google vai exibir a página Criar ID do cliente OAuth, que permite criar um ID do cliente OAuth e uma chave secreta para usar na conexão do BigQuery com o Looker. No menu suspenso Tipo de aplicativo, selecione Aplicativo da Web. A página será expandida e mostrará outras opções:

  6. No campo Nome, insira um nome para o app, como Looker.

  7. Na seção Origens JavaScript autorizadas, selecione + ADICIONAR URI para exibir o campo URIs 1. No campo URIs 1, insira o URL da sua instância do Looker, incluindo https://. Exemplo:

    • Se o Looker hospedar sua instância: https://<instancename>.looker.com
    • Se você tiver uma instância do Looker hospedada pelo cliente: https://looker.<mycompany>.com
    • Se a instância do Looker exigir um número de porta: https://looker.<mycompany>.com:9999

  8. Na seção URIs de redirecionamento autorizados, selecione + ADICIONAR URI para exibir o campo URIs 1. No campo URIs 1, insira o URL da sua instância do Looker, seguido por /external_oauth/redirect. Por exemplo, https://<instancename>.looker.com/external_oauth/redirect ou https://looker.<mycompany>.com:9999/external_oauth/redirect.

  9. Selecione Criar. O Google vai mostrar o ID do cliente e a chave secreta do cliente.

  10. Copie o ID do cliente e os valores da chave secreta do cliente. Você vai precisar deles para configurar o OAuth para a conexão do BigQuery no Looker.

O Google exige que você configure uma tela de permissão OAuth, que permite que os usuários escolham como conceder acesso aos dados particulares deles e fornece um link para os Termos de Serviço e a Política de Privacidade da sua organização.

No menu à esquerda, selecione a página Tela de permissão OAuth. Antes de configurar a tela de permissão OAuth, escolha o tipo de usuário para quem o app será disponibilizado. Dependendo da sua seleção, o app pode exigir a verificação do Google.

Escolha uma opção e selecione Criar. O Google exibe a página Tela de permissão OAuth. É possível configurar essa tela para todos os aplicativos do seu projeto, incluindo os internos e públicos.

O Google vai realizar uma verificação para aplicativos públicos se alguma destas condições for verdadeira:

  • O aplicativo usa APIs do Google que usam escopos restritos ou sensíveis.
  • A tela de permissão OAuth inclui um logotipo do aplicativo.
  • O projeto excedeu o limite do domínio.

Para configurar a tela de permissão OAuth, faça o seguinte:

  1. No campo Nome do app, insira o nome do aplicativo ao qual o usuário está concedendo acesso. Neste caso, Looker.

  2. No campo E-mail para suporte ao usuário, insira o e-mail de suporte que os usuários devem usar para entrar em contato em caso de problemas de login ou consentimento.

  3. Selecione ADICIONAR DOMÍNIO para revelar o campo Domínio autorizado 1. Nesse campo, insira o domínio do URL da sua instância do Looker. Por exemplo, se o Looker hospedar sua instância em https://<instance_name>.cloud.looker.com, o domínio será looker.com. Para implantações do Looker hospedadas pelo cliente, insira o domínio em que você hospeda o Looker.

  4. Na seção Informações de contato do desenvolvedor, insira um ou mais endereços de e-mail que o Google pode usar para entrar em contato com você sobre seu projeto.

    Os campos restantes são opcionais, mas podem ser usados para personalizar ainda mais a tela de permissão.

  5. Selecione SALVAR E CONTINUAR.

  6. O Google exibe a página Escopos, em que é possível configurar escopos. O Looker requer apenas os escopos padrão, portanto, nenhuma configuração de escopo adicional é necessária. Selecione SALVAR E CONTINUAR.

  7. Na página Resumo, selecione VOLTAR AO PAINEL.

Agora você pode continuar o procedimento para gerar suas credenciais OAuth.

Para mais informações sobre como configurar a tela de permissão OAuth do Google, consulte a documentação de suporte do Google.

Como configurar a conexão do Looker para o BigQuery com OAuth

Para ativar o OAuth na sua conexão do BigQuery, selecione a opção OAuth na página Conexão do Looker ao configurar a conexão do Looker com o BigQuery. Ao selecionar a opção OAuth, o Looker vai mostrar os campos ID do cliente OAuth e Chave secreta do cliente OAuth. Cole os valores de ID do cliente e Chave secreta do cliente que você recebeu como uma etapa no procedimento Como gerar credenciais do OAuth do Google nesta página.

Algumas configurações de administrador do Google Workspace podem interromper o OAuth do BigQuery:

  • Duração da sessão: se você tiver definido uma duração de sessão para o OAuth do BigQuery, para evitar tempos limite de sessão do Looker, use o recurso Isentar apps confiáveis para adicionar o Looker aos seus apps confiáveis. Consulte o artigo de ajuda Definir a duração da sessão para os serviços do Google Cloud para conferir as etapas desse procedimento.
  • Configurações do acesso baseado no contexto: verifique se há algo nas configurações do acesso baseado no contexto do Google Workspace que possa impedir usuários específicos de concluir o fluxo do OAuth. Consulte o artigo de ajuda Proteger sua empresa com o acesso baseado no contexto para mais informações sobre o acesso baseado no contexto.

Como os usuários do Looker se autenticam no BigQuery com o OAuth

Depois que a conexão do Looker com o BigQuery estiver configurada para o OAuth, os usuários com os papéis do Identity and Access Management de Usuário de jobs do BigQuery e Leitor de dados do BigQuery poderão usar o Looker para realizar a autenticação inicial no banco de dados do BigQuery de uma das seguintes maneiras:

Como autenticar no Google usando uma consulta

Depois que a conexão do Looker com o BigQuery for configurada para o OAuth, o Looker vai solicitar que os usuários façam login com a Conta do Google antes de executar consultas que usam a conexão do BigQuery. O Looker mostra essa solicitação em Análises, painéis, Looks e no SQL Runner.

O usuário precisa seguir estas etapas:

  1. Selecione Fazer login.
  2. Na caixa de diálogo Autorizar conexão OAuth, selecione Autorizar. Essa caixa de diálogo notifica o usuário de que a instância do Looker vai acessar dados em nome dele e que usuários privilegiados do Looker, como administradores ou desenvolvedores, podem ter visibilidade dos dados.
  3. Use o OAuth para autenticar no BigQuery.
  4. Selecione o botão Executar na Análise para carregar os dados nela.

Como fazer login no Google pela página da conta de usuário

Depois que a conexão do Looker com o BigQuery for configurada para o OAuth, o usuário poderá autenticar a Conta do Google na página da conta de usuário do Looker:

  1. No Looker, selecione o ícone de perfil e escolha Conta no menu do usuário.
  2. Acesse a seção Credenciais de conexão do OAuth e selecione o botão Fazer login para a conexão de banco de dados do BigQuery apropriada.
  3. Na caixa de diálogo Autorizar conexão OAuth, leia o aviso e selecione Autorizar para continuar. O Looker armazena esse consentimento no armazenamento local do navegador. Se você limpar o armazenamento local, a caixa de diálogo vai aparecer novamente na próxima vez que você iniciar um fluxo de autorização do OAuth.
  4. Selecione a conta apropriada na página Fazer login com o Google.
  5. Selecione Permitir na tela de permissão do OAuth para que o Looker visualize e gerencie seus dados no Google BigQuery.

Depois de se autenticar no Google pelo Looker, você pode sair ou autorizar novamente suas credenciais a qualquer momento na página Conta, conforme descrito na página de documentação Como personalizar sua conta de usuário. Embora os tokens do Google BigQuery não expirem, um usuário pode selecionar Reautorizar para fazer login com outra Conta do Google.

Revogar tokens OAuth

Os usuários podem revogar o acesso de aplicativos como o Looker à Conta do Google acessando as configurações da Conta do Google.

Os tokens do Google BigQuery não expiram. No entanto, se um administrador de banco de dados alterar as credenciais do OAuth da conexão de banco de dados de uma forma que invalide as credenciais atuais, os usuários precisarão fazer login com a Conta do Google novamente antes de executar qualquer consulta que use essa conexão.

Tabelas derivadas persistentes em uma conexão do BigQuery

Se você quiser usar tabelas derivadas persistentes (PDTs) na sua conexão do BigQuery, talvez seja necessário fazer o seguinte, dependendo da configuração da conexão:

  • Use o console do Google Cloud para criar um conjunto de dados temporário no banco de dados do BigQuery que o Looker pode usar para gravar TDPs. Consulte a seção Como criar um conjunto de dados temporário para tabelas derivadas persistentes nesta página para ver o procedimento. Essa etapa é obrigatória para TDPs, independentemente das outras opções de configuração na conexão.
  • Use o Gerenciador de APIs no console do Google Cloud para criar uma conta de serviço separada para os processos de TDP do Looker. Consulte a seção Como criar uma conta de serviço e fazer o download do certificado de credenciais JSON nesta página para saber como fazer isso. O tipo de autenticação na sua conexão afeta se uma conta de serviço de TDP é necessária e também onde você insere as informações da conta de serviço de TDP na janela Conexões do Looker ao configurar a conexão do Looker com o BigQuery:
    • Se a conexão usar o OAuth para autenticação de usuários, você precisará criar uma conta de serviço separada para os processos de TDP. Insira as informações da conta de serviço e os detalhes do arquivo de certificado na seção Substituições de TDP da janela Conexões do Looker. A janela Conexões do Looker exibe a seção Substituições de TDP automaticamente quando você ativa a opção Ativar TDPs para uma conexão que também está configurada com a opção OAuth no campo Autenticação. Consulte a seção Como ativar TDPs para conexões do Looker com o BigQuery usando o OAuth para mais informações.
    • Se a conexão usar contas de serviço para autenticação de usuários, você poderá criar uma conta de serviço separada para processos de TDP. Se você optar por ter uma conta de serviço de TDP separada, insira as informações da conta de serviço na seção Substituições de TDP para os campos E-mail da conta de serviço, Arquivo JSON/P12 da conta de serviço e Senha da janela Conexões do Looker. A seção Substituições de TDP aparece quando você ativa a opção Ativar TDPs para uma conexão do Looker com o BigQuery usando a autenticação da conta de serviço.

Como criar um conjunto de dados temporário para tabelas derivadas persistentes

Para ativar as tabelas derivadas persistentes (TDPs) na sua conexão do BigQuery, ative a opção Ativar TDPs na página Conexão do Looker ao configurar a conexão do Looker com o BigQuery. Quando você ativa as TDPs, o Looker mostra os campos Projeto temporário e Banco de dados temporário. Nesses campos, você vai inserir o ID do projeto e o nome do conjunto de dados que o Looker pode usar para criar TDPs. Configure o banco de dados ou o esquema com antecedência com as permissões de gravação apropriadas.

É possível configurar um conjunto de dados temporário usando o console do Google Cloud :

  1. Abra o console doGoogle Cloud e selecione o projeto.

  2. Selecione o menu de três pontos e, em seguida, Criar conjunto de dados.

  3. Insira um ID do conjunto de dados (normalmente looker_scratch) e selecione o Local de dados (opcional), a Validade da tabela padrão e a solução de gerenciamento de chaves de criptografia. Selecione CRIAR CONJUNTO DE DADOS para concluir.

Agora que você criou o conjunto de dados, pode especificar o projeto e o conjunto de dados nos campos Projeto temporário e Banco de dados temporário da janela Conexões do Looker ao configurar a conexão do Looker com o BigQuery.

Como ativar TDPs para conexões do Looker com o BigQuery usando OAuth

Para conexões do BigQuery que usam OAuth, os usuários se autenticam no Looker com as credenciais do OAuth. O Looker é compatível com TDPs para conexões do BigQuery com OAuth, mas o Looker em si não pode usar o OAuth. Portanto, é necessário configurar uma conta de serviço do BigQuery especificamente para permitir que o Looker acesse seu banco de dados para processos de TDP.

É possível configurar uma conta de serviço de TDP no banco de dados do BigQuery usando o Gerenciador de APIs do Google Cloud . Consulte a seção Como criar uma conta de serviço e fazer o download do certificado de credenciais JSON nesta página.

Depois de criar a conta de serviço no banco de dados do BigQuery, insira as informações da conta de serviço e os detalhes do arquivo de certificado na seção Substituições de TDP da janela Conexões do Looker ao configurar a conexão do Looker com o BigQuery. Consulte a seção Substituições de TDP para mais informações sobre os campos Substituições de TDP.

Substituições de TDP

Para conexões do BigQuery que usam OAuth e para conexões em que você quer usar credenciais, conjuntos de dados ou projetos de faturamento diferentes para suas TDPs, ative a opção Substituições de TDP para inserir informações diferentes específicas para TDPs na sua conexão. Consulte a seção Substituições de TDP da página de documentação Como conectar o Looker ao seu banco de dados para mais informações sobre por que as substituições de TDP podem ser úteis.

Se você tiver ativado a opção Ativar TDPs para uma conexão, a janela Conexões do Looker vai mostrar a opção Ativar substituições de TDP. Ative a opção Ativar substituições de TDP e use os seguintes campos na seção Substituições de TDP para inserir as informações da conta de serviço que o Looker pode usar para processos de TDP no seu banco de dados:

  • ID do projeto de faturamento de substituição da TDP: especifique o projeto que será usado para faturar as consultas de criação e manutenção da TDP (consultas de verificação de gatilho). As consultas na TDP ainda vão usar o projeto de faturamento especificado no campo ID do projeto de faturamento das configurações gerais. O projeto de faturamento de substituição da TDP nunca é usado para armazenamento, apenas para faturamento. Se você for usar esse campo, a conta de serviço precisará ter, no mínimo, o papel bigquery.jobUser.

  • Conjunto de dados de substituição da TDP: o nome do conjunto de dados que você quer que o Looker use para TDPs na conexão.

  • Arquivo da conta de serviço de substituição da TDP: use o botão Fazer upload do arquivo para fazer upload do arquivo de certificado da conta de serviço do BigQuery que você quer usar para processos de TDP na conexão. Você pode acessar esse arquivo no Google Cloud Gerenciador de APIs como uma etapa do procedimento Criar uma conta de serviço e fazer o download do certificado de credenciais JSON. A conta de serviço usada para o conjunto de dados de TDP precisa ter acesso de leitura e gravação.

  • Nome de usuário: esse campo só se aplica se você fizer upload de um arquivo P12 no campo Arquivo da conta de serviço de substituição da TDP da seção Substituições da TDP. Insira o endereço de e-mail da conta de serviço do BigQuery que você quer usar para os processos de TDP na conexão. Você pode encontrar esse endereço de e-mail no Google Cloud Gerenciador de APIs como uma etapa do procedimento Criar uma conta de serviço e fazer o download do certificado de credenciais JSON.

  • Senha: esse campo só se aplica se você fizer upload de um arquivo P12 no campo Arquivo da conta de serviço de substituição da TDP da seção Substituições da TDP. Insira a senha do arquivo de credenciais .p12 da conta de serviço do BigQuery que você quer usar para os processos de TDP na conexão.

  • Parâmetros JDBC adicionais de substituição da TDP: adicione outros parâmetros JDBC que devem ser usados para as TDPs na conexão, como rótulos do BigQuery. Consulte a seção Rótulos de jobs e comentários de contexto para conexões do BigQuery nesta página para mais informações. Confira a seguir alguns dos outros parâmetros compatíveis:

    • connectTimeout: número de milissegundos para aguardar uma conexão. O padrão é 240000.
    • readTimeout: número de milissegundos de espera por uma leitura. O padrão é 240000.
    • RootURL: se você tiver uma instância do BigQuery em uma rede privada, especifique um endpoint alternativo para se conectar ao BigQuery que não seja o endpoint público padrão.

Como conectar o Looker ao BigQuery

Você cria uma conexão de banco de dados no Looker na página Conectar seu banco de dados ao Looker. Há duas opções para abrir a página Conectar seu banco de dados ao Looker:

  • Selecione Conexões na seção Banco de dados do painel Administrador. Na página Conexões, clique no botão Adicionar conexão.
  • Clique no botão Criar no painel de navegação principal e selecione o item de menu Conexão.

Preencher os detalhes de conexão. A maioria dessas configurações é comum para a maioria dos dialetos de banco de dados e está descrita na página de documentação Como conectar o Looker ao seu banco de dados. As configurações a seguir são mencionadas para destacá-las ou esclarecer como elas se aplicam especificamente às conexões do BigQuery:

  • Dialeto SQL: selecione SQL padrão do Google BigQuery ou SQL legado do Google BigQuery.

  • Escopo do projeto: selecione se a conexão pode ser usada com todos os projetos ou apenas com um. Para mais informações, consulte a página Como conectar o Looker ao seu banco de dados.

  • Ativar servidor SSH: para instâncias implantadas na infraestrutura do Kubernetes e que podem adicionar informações de configuração do servidor SSH, ative a opção Ativar servidor SSH para configurar os campos Servidor SSH e Túnel SSH. Para mais informações, consulte a página Como conectar o Looker ao seu banco de dados.

  • ID do projeto de faturamento: o ID do projeto (identificador exclusivo) do projeto de faturamento do Google Cloud . O projeto de faturamento é o projeto do Google Cloud que é faturado, mas ainda é possível consultar conjuntos de dados em um projeto diferente do Google Cloud se os desenvolvedores do LookML especificarem nomes de tabela com escopo completo no parâmetro sql_table_name das visualizações, Análises ou mesclagens do LookML. No BigQuery, um nome de tabela com escopo completo usa o formato <project_name>.<dataset_name>.<table_name>. Sem uma referência totalmente definida, o BigQuery procura a tabela no projeto de faturamento e no conjunto de dados que você especificou na página Conexões do Looker para a conexão do BigQuery com o Looker. Consulte a documentação do BigQuery para uma explicação da hierarquia de recursos no BigQuery.

  • ID do projeto de armazenamento: o ID do projeto de armazenamento, se você separar computação e armazenamento em projetos diferentes. É possível consultar conjuntos de dados em um projeto do Google Cloud diferente se os desenvolvedores do LookML especificarem nomes de tabela com escopo completo no parâmetro sql_table_name das visualizações, Análises ou mesclagens do LookML. No BigQuery, um nome de tabela com escopo completo usa o formato <project_name>.<dataset_name>.<table_name>. Sem uma referência totalmente definida, o BigQuery procura a tabela no projeto de faturamento e no conjunto de dados que você especificou na página Conexões do Looker para a conexão do BigQuery com o Looker. Consulte a documentação do BigQuery para uma explicação da hierarquia de recursos no BigQuery.

  • Conjunto de dados principal: o nome do conjunto de dados que o Looker vai usar como padrão ao consultar seu banco de dados. O conjunto de dados padrão precisa estar localizado no projeto de faturamento especificado para a conexão. Não é possível inserir um valor como project_name.dataset_name no campo Banco de dados para especificar um conjunto de dados em um projeto diferente.

    Seu projeto do LookML poderá acessar tabelas em outros conjuntos de dados (incluindo tabelas em conjuntos de dados públicos) se os desenvolvedores do LookML especificarem nomes de tabela com escopo completo no parâmetro sql_table_name das visualizações, Análises ou combinações do LookML. No BigQuery, um nome de tabela com escopo completo usa o formato <project_name>.<dataset_name>.<table_name>. Para consultar uma tabela em outro conjunto de dados, ela precisa ser acessível pela conta de serviço (para conexões que usam a autenticação da conta de serviço) ou pelo usuário que executa a consulta (para conexões que usam a autenticação OAuth). Se o código LookML não especificar nomes de tabela com escopo completo, o BigQuery vai procurar a tabela no conjunto de dados especificado no campo Conjunto de dados da conexão do BiqQuery.

    Se o projeto não tiver conjuntos de dados (o que pode acontecer se você separar a computação e o armazenamento em projetos diferentes), forneça um valor arbitrário para Conjunto de dados, mas use sempre nomes de tabela com escopo completo no LookML.

  • Autenticação: o tipo de autenticação que o Looker vai usar para acessar seu banco de dados. Algumas dessas opções são compatíveis apenas com instâncias do Looker (Google Cloud Core):

    • Application Default Credentials: (somente Looker (Google Cloud Core)) selecione essa opção para usar o Application Default Credentials (ADC) para autenticar no banco de dados (consulte a documentação do Looker (Google Cloud Core) para mais informações).
    • Conta de serviço: selecione essa opção para usar uma conta de serviço do BigQuery para que o Looker se autentique no banco de dados (consulte Autenticação com contas de serviço do BigQuery para mais informações). Quando a opção Conta de serviço estiver selecionada, você verá os seguintes campos:

    • OAuth: selecione essa opção para permitir que cada usuário do Looker se autentique no Google BigQuery e autorize o Looker a acessar o banco de dados com a conta do BigQuery do usuário. Consulte a seção Autenticação com OAuth nesta página para mais informações sobre como implementar o OAuth na sua conexão do BigQuery. Quando a opção OAuth estiver selecionada, os seguintes campos vão aparecer:

  • Máximo de conexões por nó: o número máximo de conexões que o Looker pode estabelecer com seu banco de dados. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Tempo limite do pool de conexões: se os usuários solicitarem mais conexões do que o configurado em Máximo de conexões por nó, as solicitações vão aguardar a conclusão de outras antes de serem executadas. O Tempo limite do pool de conexões é o tempo máximo que uma solicitação vai esperar. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Número máximo de consultas simultâneas para esta conexão: o número máximo de consultas simultâneas que o Looker pode enviar para a conexão do banco de dados de uma vez. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Número máximo de consultas simultâneas por usuário para esta conexão: o número máximo de consultas simultâneas que o Looker vai enviar para essa conexão de banco de dados de uma vez para cada usuário. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Gigabytes máximos de faturamento: nas conexões do BigQuery, você recebe cobranças por cada consulta com base no tamanho dela. Para evitar que os usuários executem acidentalmente uma consulta muito cara, defina um número máximo de gigabytes que um usuário pode extrair em uma única consulta. Deixe o campo Máximo de gigabytes de faturamento em branco se não estiver limitando o tamanho da consulta. Consulte a página de preços do BigQuery para mais informações.
  • Parâmetros JDBC adicionais: adicione outros parâmetros JDBC, como rótulos do BigQuery. Para mais informações, consulte a seção Rótulos de jobs e comentários de contexto para conexões do BigQuery nesta página. Consulte a seção Parâmetros JDBC compatíveis nesta página para ver a lista de parâmetros compatíveis com o Looker. Estes são alguns dos parâmetros aceitos:
    • connectTimeout: número de milissegundos para aguardar uma conexão. O padrão é 240000.
    • readTimeout: número de milissegundos de espera por uma leitura. O padrão é 240000.
    • RootURL: se você tiver uma instância do BigQuery em uma rede privada, especifique um endpoint alternativo para se conectar ao BigQuery que não seja o endpoint público padrão.
  • Programação de manutenção: o intervalo de cron para o regenerador do Looker. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Desativar contexto: essa opção desativa os comentários de contexto em uma conexão do BigQuery. Os comentários de contexto nas conexões do Google BigQuery estão desativados por padrão porque invalidam a capacidade de armazenamento em cache do Google BigQuery e podem afetar negativamente o desempenho do cache. Para ativar os comentários de contexto em uma conexão do BigQuery, desative a opção Desativar contexto. Consulte a seção Rótulos de jobs e comentários de contexto para conexões do BigQuery para mais informações.
  • SSL: ative o botão para usar a criptografia SSL e proteger os dados transmitidos entre o Looker e seu banco de dados. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.
  • Pré-cache de tabelas e colunas: se você não quiser que o SQL Runner pré-carregue as informações da tabela, mas sim que as carregue apenas quando uma tabela for selecionada, desmarque essa opção. Consulte a seção Pré-armazenar tabelas e colunas em cache da página Como conectar o Looker ao seu banco de dados para mais informações.

  • Buscar e armazenar em cache o esquema: se você souber que o esquema de informações é lento, desative a opção Buscar e armazenar em cache o esquema para sua conexão. Desativar esse recurso impede parte da otimização de SQL do Looker para determinados recursos. Portanto, ative a opção Buscar e armazenar esquema em cache, a menos que você saiba que o esquema de informações da sua conexão é particularmente lento. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.

  • Ativar TDPs: ative essa opção para permitir tabelas derivadas persistentes (TDPs) na conexão. Para mais informações, consulte a seção Tabelas derivadas persistentes em uma conexão do BigQuery nesta página. Você precisa especificar o conjunto de dados temporário no banco de dados que o Looker vai usar para gravar TDPs. Consulte a seção Como criar um conjunto de dados temporário para tabelas derivadas persistentes nesta página para ver o procedimento. Observação: se a conexão estiver configurada para OAuth, use a seção Substituições de TDP para especificar uma conta de serviço que o Looker possa usar para processos de TDP na conexão do BigQuery. Consulte a seção Como ativar TDPs para conexões do Looker com o BigQuery usando o OAuth para mais detalhes.

  • Projeto temporário: o ID do projeto que contém o conjunto de dados que você quer usar para gravar TDPs. Se um Projeto temporário não for especificado, o Looker vai gravar as TDPs no projeto especificado no campo ID do projeto de armazenamento da seção Configurações do banco de dados das configurações de conexão. Se um ID do projeto de armazenamento não for especificado, o Looker vai gravar as TDPs no projeto especificado no campo ID do projeto de faturamento da seção Configurações do banco de dados das configurações de conexão.

  • Banco de dados temporário: o conjunto de dados do BigQuery que você criou no console do Google Cloud para permitir que o Looker grave tabelas derivadas persistentes no seu banco de dados. Consulte a seção Como criar um conjunto de dados temporário para tabelas derivadas persistentes para ver o procedimento.

  • Número máximo de conexões do builder da TDP: o número máximo de versões simultâneas de tabelas que o regenerador do Looker pode iniciar em uma conexão de banco de dados. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.

  • Repetir builds de TDP com falha: quando o botão Repetir builds de TDP com falha está ativado, o regenerador do Looker tenta recriar uma TDP que falhou no ciclo anterior, mesmo que a condição de acionamento da TDP não seja atendida. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.

  • Controle da API de TDPs: essa opção determina se as chamadas de API start_pdt_build, check_pdt_build e stop_pdt_build podem ser usadas para essa conexão. Para mais informações, consulte a página de documentação Como conectar o Looker ao seu banco de dados.

  • Ativar substituições de TDP: ative essa opção para definir configurações de conexão separadas que o Looker deve usar para gravar TDPs no banco de dados. Consulte a seção Substituições de TDP nesta página para mais informações sobre os campos de substituições de TDP.

  • Fuso horário do banco de dados: o fuso horário padrão do BigQuery é UTC. A configuração de fuso horário especificada aqui precisa corresponder à configuração de fuso horário do BigQuery. Consulte a seção Fuso horário do banco de dados da página Como conectar o Looker ao banco de dados para mais informações.

  • Fuso horário de consultas: consulte a seção Fuso horário de consultas da página Como conectar o Looker ao banco de dados para mais informações.

Depois de preencher todos os campos aplicáveis, você pode testar a conexão conforme necessário.

Para salvar essas configurações, clique em Conectar.

Testando a conexão

É possível testar as configurações de conexão em alguns lugares na interface do Looker:

  • Clique no botão Testar na parte de baixo da página Configurações de conexões, conforme descrito na página de documentação Como conectar o Looker ao seu banco de dados.
  • Clique no botão Testar ao lado da listagem da conexão na página Administrador Conexões, conforme descrito na página de documentação Conexões.

Para novas conexões, se o Looker exibir Pode se conectar, selecione Adicionar conexão. O Looker vai executar o restante dos testes de conexão para verificar se a conta de serviço foi configurada corretamente e com os papéis adequados.

Como testar uma conexão que usa o OAuth

  1. No Looker, acesse o Modo de Desenvolvimento.
  2. Para uma conexão do BigQuery que usa OAuth, acesse os arquivos do projeto do Looker que usa sua conexão do BigQuery. Para novas conexões do BigQuery que usam OAuth, abra um arquivo de modelo e substitua o valor connection do modelo pelo nome da nova conexão do BigQuery. Em seguida, salve o arquivo de modelo.
  3. Abra uma das Análises ou um dos painéis do modelo e execute uma consulta. Quando você tentar executar uma consulta, o Looker vai pedir para você fazer login com sua Conta do Google. Siga as instruções de login do OAuth do Google.

Rótulos de jobs e comentários de contexto para conexões do BigQuery

Para conexões do BigQuery, o Looker envia o contexto da consulta na forma de rótulos de job do BigQuery. Por padrão, o Looker envia as seguintes chaves de rótulo de contexto para conexões do BigQuery:

  • looker-context-user_id: o identificador exclusivo de cada usuário na instância do Looker. É possível associar esse ID aos IDs de usuário na página Usuários no menu Administrador.

  • looker-context-history_slug: o identificador exclusivo de cada consulta executada no banco de dados pela instância do Looker.

  • looker-context-instance_slug: o número de ID da instância do Looker que emitiu a consulta. O suporte do Looker pode usar essas informações para ajudar você a resolver problemas, se necessário.

É possível configurar outros rótulos de job para o Looker enviar com cada consulta na conexão do BigQuery usando o campo de texto Outros parâmetros JDBC da página Conexões. No campo Parâmetros JDBC adicionais, adicione um parâmetro JDBC extra, labels, e forneça uma lista separada por vírgulas de pares key=value codificados por URL. Por exemplo, se você incluir isto no campo Parâmetros JDBC adicionais:

labels=this%3Dconnection-label,that%3Danother-connection-label

%3D é a codificação de URL para =. Portanto, isso adicionaria os dois rótulos a seguir a cada consulta que o Looker envia ao banco de dados do BigQuery, além dos rótulos de contexto padrão do Looker:

  • this: connection-label
  • that: another-connection-label

O BigQuery tem restrições para rótulos de jobs:

  • Qualquer rótulo de conexão que tenha a mesma chave de um rótulo de contexto será ignorado.
  • Se a união de rótulos de conexão e de contexto exceder o máximo de 64 rótulos, os rótulos de contexto serão os primeiros a serem descartados, seguidos pelos rótulos de conexão, até que o número total de rótulos seja de no máximo 64.

O Looker garante que os rótulos de contexto estejam em conformidade com todos os requisitos de validade de rótulos do BigQuery, mas não verifica a validade dos rótulos de conexão. A configuração de rótulos de conexão inválidos pode causar falhas nas consultas.

Os rótulos de jobs do BigQuery que o Looker envia por padrão (looker-context-user_id, looker-context-history_id e looker-context-instance_slug) correspondem aos comentários de contexto SQL que o Looker anexa às consultas SQL para dialetos de banco de dados que não sejam o BigQuery. Para conexões do BigQuery, os comentários de contexto são desativados por padrão porque invalidam a capacidade de armazenamento em cache do BigQuery e podem afetar negativamente o desempenho do cache. Para ativar os comentários de contexto em uma conexão do BigQuery, desative a opção Desativar contexto. Recomendamos manter a configuração padrão de Desativar comentário de contexto para que você possa usar o cache do BigQuery. No entanto, se você desmarcar a opção Desativar comentário de contexto para uma conexão do BigQuery, o Looker vai enviar comentários de contexto SQL e rótulos de jobs do BigQuery para seu banco de dados.

Os comentários de contexto do SQL e os rótulos de jobs do BigQuery transmitem as mesmas informações. Por exemplo, o Looker pode gerar os seguintes comentários de contexto SQL para uma consulta:

-- Looker Query Context

'{"user_id":1,"history_id":4757,"instance_slug":"ec2804ddef74c466f2a43e0afaa3ff6b"}'

Em seguida, o Looker geraria os seguintes rótulos de job do BigQuery para a mesma consulta:

[{"value":"1","key":"looker-context-user_id"},

 {"value":"4757","key":"looker-context-history_id"},

 {"value":"ec2804ddef74c466f2a43e0afaa3ff6b","key":"looker-context-instance_slug"}]

Parâmetros JDBC compatíveis

Para o Google BigQuery, o Looker é compatível com os seguintes parâmetros JDBC no campo Parâmetros JDBC adicionais da conexão. Consulte a documentação do seu banco de dados para mais informações sobre esses parâmetros.

  • AdditionalProjects
  • connectTimeout
  • DefaultDataset
  • EnableHighThroughputAPI
  • EnableSession
  • EndpointOverrides: para instâncias públicas do Looker, o valor do parâmetro EndpointOverrides precisa ser o endereço IP público da instância.
  • HighThroughputActivationRatio
  • HighThroughputMinTableSize
  • HttpConnectTimeout
  • HttpReadTimeout
  • JobCreationMode
  • JobTimeout
  • KMSKeyName
  • labels
  • LargeResultsDatasetExpirationTime
  • Location
  • MaxResults
  • oauthaccesstoken
  • ProjectId
  • QueryProperties
  • readTimeout
  • RequestGoogleDriveScope
  • RetryInitialDelay
  • RetryMaxDelay
  • RootURL: para instâncias públicas do Looker, o valor do parâmetro RootURL precisa ser o endereço IP público da instância.
  • Timeout
  • UnsupportedHTAPIFallback
  • UseQueryCache

Suporte a recursos

Para que o Looker seja compatível com alguns recursos, o dialeto do banco de dados também precisa ser compatível com eles.

SQL padrão do Google BigQuery

O SQL padrão do Google BigQuery é compatível com os seguintes recursos a partir do Looker 26.20:

Recurso Compatível?
Looker (Google Cloud Core)
Conjuntos simétricos
Tabelas derivadas
Tabelas derivadas persistentes em SQL
Tabelas derivadas nativas persistentes
Visualizações estáveis
Encerramento de consultas
Tabelas dinâmicas baseadas em SQL
Fusos horários
SSL
Subtotais
Parâmetros adicionais da JDBC
Diferencia maiúsculas de minúsculas
Tipo de local
Tipo de lista
Percentil
Percentil distinto
Mostrar processos do SQL Runner
Tabela de descrição do SQL Runner
Mostrar índices do SQL Runner
SQL Runner Select 10
Contagem do SQL Runner
Explicação do SQL
Credenciais do OAuth 2.0
Comentários de contexto
Pooling de conexão
Esboços HLL
Reconhecimento agregado
TDPs incrementais
Milissegundos
Microssegundos
Visualizações materializadas
Medidas de comparação de períodos
Contagem aproximada aproximada
Modelos analíticos no banco de dados
Agendas personalizadas

SQL legado do Google BigQuery

O SQL legado do Google BigQuery é compatível com os seguintes recursos a partir do Looker 26.20:

Recurso Compatível?
Looker (Google Cloud Core)
Conjuntos simétricos
Tabelas derivadas
Tabelas derivadas persistentes em SQL
Tabelas derivadas nativas persistentes
Visualizações estáveis
Encerramento de consultas
Tabelas dinâmicas baseadas em SQL
Fusos horários
SSL
Subtotais
Parâmetros adicionais da JDBC
Diferencia maiúsculas de minúsculas
Tipo de local
Tipo de lista
Percentil
Percentil distinto
Mostrar processos do SQL Runner
Tabela de descrição do SQL Runner
Mostrar índices do SQL Runner
SQL Runner Select 10
Contagem do SQL Runner
Explicação do SQL
Credenciais do OAuth 2.0
Comentários de contexto
Pooling de conexão
Esboços HLL
Reconhecimento agregado
TDPs incrementais
Milissegundos
Microssegundos
Visualizações materializadas
Medidas de comparação de períodos
Contagem aproximada aproximada
Modelos analíticos no banco de dados
Agendas personalizadas

Solução de problemas

Dataset not found in location US erro

As consultas programadas ou os testes de conexão no Looker (original) podem falhar de forma intermitente com um erro como este:

SQL Error Query execution failed: - Not found: Dataset [dataset_name] was not found in location US

Esse erro pode ocorrer mesmo que o conjunto de dados esteja em um local fora dos EUA. Nas instâncias do Looker (original) configuradas para usar o Application Default Credentials (ADC) pela UI de conexão legada, falhas temporárias de validação de credenciais ou de pesquisa de metadados podem impedir que o Google BigQuery detecte automaticamente o local do conjunto de dados. Quando essa detecção automática falha, o Google BigQuery usa como padrão a multirregião US, informando incorretamente a permissão temporária ou a falha de pesquisa de metadados como um problema de local.

Para resolver ou contornar esse problema, use um dos seguintes métodos:

  • Especifique o local do conjunto de dados: defina explicitamente a região de processamento do conjunto de dados nas configurações de conexão. No campo Parâmetros JDBC adicionais, adicione o parâmetro Location definido como o código da região real em que seus dados estão (por exemplo, ;Location=northamerica-northeast1).
  • Transição para a autenticação padrão: mude do ADC ou da identidade temporária de conta de serviço no Looker (original) para uma conexão padrão de conta de serviço que usa uma chave privada JSON ou configure o OAuth. O ADC não é mais compatível com o Looker (original), e a UI de configuração dele está sendo descontinuada.
  • Migrar para o Looker (Google Cloud Core): migre para uma instância do Looker (Google Cloud Core), que oferece suporte nativo à autenticação do ADC sem exigir chaves de conta de serviço exportadas.

Próximas etapas

Depois de conectar o banco de dados ao Looker, configure as opções de login para os usuários.