A conexão com o BigQuery tem três jeitos, no mesmo card. O principal é Entrar com o Google: você vai à tela do Google, autoriza o acesso ao BigQuery e volta à Toca, sem digitar chave nenhuma, e escolhe o projeto do Google Cloud que vai rodar e pagar as consultas. Os outros dois usam uma conta de serviço do seu projeto, para quem prefere não ligar a conexão a uma pessoa: a conexão sem chave, que é a que o Google recomenda, e a chave JSON. Em todos, a Toca vê e altera exatamente o que a conta conectada vê e altera no BigQuery.
No BigQuery, consulta custa dinheiro: o Google cobra pelos bytes que cada consulta lê, do projeto que a executa. Por isso a Toca põe um teto de cobrança em toda consulta, mostra o custo estimado antes das grandes e pede a sua aprovação para elas.
Esta integração está em homologação: a conexão funciona normalmente, mas as consultas no chat ainda estão em validação.
Sobre a chave JSON: O Google desaconselha chaves de conta de serviço: na documentação dele, "Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible". Quem tem o arquivo age como a conta, de qualquer lugar, até a chave ser apagada. Por isso ela fica por último no card. Prefira Entrar com o Google ou a conexão sem chave, em que nenhuma chave sai do seu projeto.
Antes de começar
- O projeto que vai pagar as consultas precisa ter faturamento ativo no Google Cloud e a API do BigQuery ativada. Sem faturamento, o BigQuery recusa as consultas.
- Papéis que a conta conectada (a sua, no login Google, ou a conta de serviço) precisa: para a Toca só consultar, Usuário de jobs do BigQuery (
roles/bigquery.jobUser) no projeto que paga e Leitor de dados do BigQuery (roles/bigquery.dataViewer) nos datasets que ela vai ler (ou no projeto). Para criar e alterar tabelas e views, Editor de dados do BigQuery (roles/bigquery.dataEditor) no lugar do Leitor. Para apagar datasets inteiros, Proprietário de dados do BigQuery (roles/bigquery.dataOwner) no dataset. O que a conta não abre no console, a Toca também não abre. - As tabelas podem estar em outros projetos: a Toca as lê pelo nome completo, e quem paga a consulta continua sendo o projeto escolhido.
- Para as duas formas com conta de serviço, você precisa poder criar contas de serviço e dar papéis no projeto, como os papéis Criar contas de serviço (
roles/iam.serviceAccountCreator) e Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).
Passo a passo
- Acesse
Configurações → Integraçõesna Toca. - Localize o card BigQuery e clique em Conectar. O painel abre com as três formas, nesta ordem.
- Com o login Google (a forma principal):
- Clique em Entrar com o Google.
- Na tela do Google, escolha a conta e deixe marcada a permissão de ver e gerenciar seus dados no Google BigQuery. Se você desmarcar, a conexão não funciona.
- De volta ao card, clique em Escolha o projeto e selecione o projeto que vai rodar e pagar as consultas. A integração fica ativa depois dessa escolha.
- Sem chave, com uma conta de serviço sua (a que o Google recomenda):
- No painel, em ou use uma conta de serviço sem chave, copie o ID que a Toca mostra para a sua conta (começa com
toca-) com Copiar ID. Esse ID é só da sua conta da Toca: é ele que prova à Toca que o projeto é seu, e nenhuma outra empresa consegue usar a conta que você criar com ele. - No console do Google Cloud, em IAM e administrador → Contas de serviço → Criar conta de serviço, crie a conta com exatamente esse ID. O ID não muda depois de criado.
- Em IAM e administrador → IAM, dê à nova conta Usuário de jobs do BigQuery (
roles/bigquery.jobUser) no projeto que paga e Leitor de dados do BigQuery (roles/bigquery.dataViewer) nos dados (ou Editor de dados do BigQuery (roles/bigquery.dataEditor), para a Toca criar e alterar com a sua aprovação). - Abra a conta de serviço nova, vá à aba Permissões, clique em Conceder acesso, cole o e-mail da conta de serviço da Toca (botão Copiar e-mail no painel) e escolha o papel Criador de token de conta de serviço (
roles/iam.serviceAccountTokenCreator). Dê esse papel só nessa conta, e não no projeto inteiro. - Na Toca, preencha E-mail da conta de serviço e Projeto que paga as consultas (o ID do projeto, não o nome) e clique em Conectar sem chave. A Toca confere tudo no Google antes de salvar.
- No painel, em ou use uma conta de serviço sem chave, copie o ID que a Toca mostra para a sua conta (começa com
- Com a chave JSON (desaconselhada pelo Google):
- Use uma conta de serviço com os mesmos papéis do BigQuery do item anterior.
- No console, em IAM e administrador → Contas de serviço, abra a conta, vá à aba Chaves → Adicionar chave → Criar nova chave → JSON → Criar. O arquivo .json é baixado uma vez só.
- No painel, em ou cole uma chave JSON, cole o conteúdo do arquivo em Chave JSON da conta de serviço ou clique em Escolher o arquivo .json. Em Projeto que paga as consultas (opcional), informe o projeto se não for o da própria conta.
- Clique em Salvar chave. A Toca confere a chave no Google, guarda cifrada e nunca a mostra de volta. Depois de conectar, apague o arquivo do seu computador.
- Pronto. Para trocar o projeto que paga, use Gerenciar no card. Para mudar de forma de conexão, clique em Trocar a forma de conexão no mesmo painel.
O que a Toca acessa
Com a conexão ativa, a Toca lê os datasets, as tabelas, as views e as colunas do projeto, uma amostra das linhas de cada tabela (sem custo), e os dados de qualquer tabela por consulta SQL, como pedidos, o export do GA4 ou a base do CRM. Ela também lê o histórico de consultas com quanto cada uma cobrou, as rotinas (funções e procedimentos), os modelos do BigQuery ML e quem tem acesso a cada tabela.
Custo: consultas de até 10 GB lidos rodam direto, sempre com esse teto de cobrança, que pelo preço sob demanda do Google dá cerca de US$ 0,06 por consulta. Acima disso, a Toca mostra os bytes e o custo estimados e só roda com a sua aprovação, até o máximo de 1 TB por consulta. Estimar o custo de uma consulta, ver a lista de tabelas e uma amostra das linhas não cobra nada.
A Toca também altera: insere, atualiza, mescla e apaga linhas, cria, substitui e apaga tabelas, views e datasets, carrega arquivos que já estão no Cloud Storage, copia tabelas, e cria ou altera funções e procedimentos. Toda alteração só acontece mediante sua aprovação explícita, pedido a pedido, dentro do chat, e o pedido de aprovação mostra o SQL, o custo estimado e se a operação pode ser desfeita.
Ficam de fora: exportar dados para fora do BigQuery (Cloud Storage e outros serviços), consultas contínuas e agendadas, funções remotas, dar ou tirar acesso (IAM, compartilhamento de dataset e políticas por linha), reservas de capacidade e configurações do projeto. Isso continua no console do Google Cloud.
Na conexão sem chave, a conta de serviço da Toca não recebe papel nenhum do BigQuery: ela só pode gerar tokens da conta de serviço que você criou, e tudo o que a Toca faz no BigQuery é com os papéis dessa conta sua.
Manutenção da conexão
Login Google: a Toca renova a autorização automaticamente. Ela deixa de valer quando o acesso é revogado do lado do Google (por exemplo, em Conta do Google → Segurança → Apps de terceiros) ou a senha é trocada. Nesse caso, clique em Reconectar no card em Configurações → Integrações.
Sem chave: não há segredo para vencer. Para cortar o acesso da Toca, tire o papel Criador de token de conta de serviço da conta da Toca, na aba Permissões da sua conta de serviço, ou desative a conta.
Chave JSON: a chave vale até ser apagada ou desativada no Google Cloud. O Google recomenda trocar as chaves de tempos em tempos: crie uma nova, cole no card com Trocar a forma de conexão e apague a antiga no console.
Toda consulta da Toca leva o rótulo toca: agente no BigQuery, para você achar no histórico de jobs e na fatura o que a Toca rodou.
Problemas comuns
- O projeto não aparece na lista — a lista mostra só os projetos com a API do BigQuery ativa em que a conta conectada tem algum papel. Ative a API no console do Google Cloud ou dê um papel à conta nesse projeto.
- A consulta é recusada por faturamento — o projeto escolhido está sem faturamento ativo. Ative o faturamento no Google Cloud ou escolha outro projeto no card.
- A consulta passou do teto de cobrança — a consulta leria mais do que o teto permite. Peça à Toca para filtrar por data ou partição e escolher só as colunas necessárias, ou aprove a consulta grande com o custo estimado.
- "A conta de serviço precisa ter o ID toca-…" — a conta foi criada com outro ID, e o ID não pode ser trocado depois. Crie uma conta nova com o ID exato do painel.
- "A Toca não tem permissão para usar a conta" — falta o papel Criador de token de conta de serviço para a conta da Toca, na aba Permissões da sua conta de serviço, ou ele ainda não valeu: o Google pode levar alguns minutos para aplicar uma mudança de papel. Confira e tente de novo.
- "A conta de serviço não pode rodar consultas no projeto" — falta o papel Usuário de jobs do BigQuery no projeto que paga. Dê o papel e tente de novo em alguns minutos.
- O Google não deixa dar papel à conta da Toca — a sua organização restringe o compartilhamento a contas do próprio domínio (política
iam.allowedPolicyMemberDomains, ligada por padrão em organizações criadas a partir de maio de 2024). Peça ao administrador da organização para liberar ou use o login Google. - Não consigo criar a chave JSON — a criação de chaves está desligada pela política da organização (
iam.managed.disableServiceAccountKeyCreation, também padrão em organizações novas). É o Google empurrando para formas mais seguras: use a conexão sem chave ou o login Google. - A chave foi recusada — o arquivo não é a chave de uma conta de serviço (precisa ter
"type": "service_account"), ou a chave foi apagada ou desativada no console. Crie uma chave nova e cole de novo. - A opção sem chave aparece desligada — ela depende de uma configuração do lado da Toca que ainda não chegou à sua conta. Use o login Google ou a chave JSON por enquanto.
- Uma tabela ligada a uma planilha do Google Sheets dá erro de permissão — ler tabela externa do Google Drive exige uma permissão do Drive que a Toca não pede. Copie os dados para uma tabela comum do BigQuery.
- Uma tabela ou dataset não aparece — a Toca enxerga só o que a conta conectada enxerga. Dê acesso a essa conta no console do BigQuery.
- Conectou a conta errada — use Excluir integração no menu ⋯ do card e conecte de novo, ou use Trocar a forma de conexão no painel.