Exportação do GSC para o BigQuery

Como usar a exportação do Google Search Console para o BigQuery para consultar dados diários não amostrados de cliques e impressões sem limite de linhas na interface (as consultas anonimizadas continuam excluídas), a diferença entre a interface e a exportação bruta, a configuração, a mecânica de custos e a armadilha de não haver preenchimento retroativo.

Para propriedades de sites, a exportação em massa do GSC para o BigQuery agenda um despejo diário e não amostrado dos dados de desempenho — sem consultas anonimizadas — no BigQuery, contornando o limite de linhas da interface e a janela de retenção de 16 meses. Ela cria tabelas em nível de site, URL e registro de exportação, não faz backfill, exige faturamento e pode gerar custos de consulta. O Google agora oferece suporte a propriedades de plataforma do Instagram, TikTok, X e YouTube, mas a documentação atual não promete suporte ao BigQuery; não presuma que este pipeline se aplica a contas sociais.

TL;DR — A exportação de dados em massa é um despejo diário e não amostrado agendado dos dados de desempenho do Search Console em um conjunto de dados do BigQuery no Google Cloud — sem o limite de exportação de ~1 000 linhas e sem a barreira de retenção de ~16 meses. Ela cria três tabelas (searchdata_site_impression, searchdata_url_impression, ExportLog). A configuração exige um projeto do Google Cloud com faturamento habilitado, as APIs BigQuery e BigQuery Storage ativadas, duas funções do IAM concedidas à conta de serviço de exportação do Google e, depois, Settings → Bulk data export no GSC. Ela não faz preenchimento retroativo, ainda informa consultas anonimizadas como strings vazias e a primeira exportação chega em até ~48 horas. Há uma camada gratuita real, além de cobranças por consulta; a cobrança clássica vem de painéis que consultam tabelas brutas ao vivo. Pense nela como o terceiro degrau: interface → API → exportação em massa.

A escada abaixo é para propriedades de sites. Ela não é evidência de que propriedades de plataforma social ou de vídeo oferecem suporte à API do Search Console ou à exportação para o BigQuery.

O que ela realmente é

A exportação em massa é um pipeline agendado de dados do Search Console para um projeto do Google Cloud, não uma fonte independente de dados de classificação. Evidência desta afirmação Search Console bulk data export sends daily performance data to BigQuery in a configured Google Cloud project. Escopo: Search Console bulk export; setup, permissions, quotas, and supported properties follow Google's current documentation. Confiança: alta · Verificado: Google: Bulk data export As consultas devem respeitar as tabelas, chaves e regras documentadas de privacidade e agregação. Evidência desta afirmação Bulk export uses site-impression, URL-impression, and export-log tables with documented schemas. Escopo: Google's published Search Console export schema; aggregation and privacy handling still affect analysis. Confiança: alta · Verificado: Google: Bulk export tables

Daniel Waisberg, Search Advocate do Google, descreve isso de forma direta: “A bulk data export is a scheduled daily export of your Search Console performance data. It includes all the data used by Search Console to generate performance reports. Data is exported to Google BigQuery, where you can run SQL queries for advanced data analysis or even export it to another system.” (tradução) «Uma exportação de dados em massa é uma exportação diária agendada dos dados de desempenho do Search Console. Ela inclui todos os dados usados pelo Search Console para gerar relatórios de desempenho. Os dados são exportados para o Google BigQuery, onde você pode executar consultas SQL para análise avançada ou até exportá-los para outro sistema.» (citado no Search Engine Journal).

A questão é escala. A interface do Search Console limita a maioria das exportações a cerca de 1 000 linhas e mostra uma janela móvel de ~16 meses. A API do Search Console oferece mais, mas continua limitada e sujeita a limites de taxa. A exportação em massa remove totalmente o teto de linhas e permite que você decida por quanto tempo conservar os dados. A própria frase do Google no anúncio, reproduzida pelo Search Engine Land: “The daily data row limit does not impact this data, so you can extract more data using this method,” (tradução) «O limite diário de linhas de dados não afeta esses dados, então você pode extrair mais dados usando este método» e o recurso “could be particularly helpful for large websites with tens of thousands of pages.” (tradução) «poderia ser particularmente útil para sites grandes com dezenas de milhares de páginas.»

Quais dados você obtém: as três tabelas

Tudo chega a um conjunto de dados cujo nome sempre começa com searchconsole. Três objetos aparecem (diretrizes e referência das tabelas):

  1. searchdata_site_impression — “Contains performance data for your property aggregated by property.” (tradução) «Contém dados de desempenho da sua propriedade agregados por propriedade».) Campos principais: data_date (“The day on which the data in this row was generated (Pacific Time)”; (tradução) «O dia em que os dados desta linha foram gerados (Horário do Pacífico)»), site_url (as propriedades de domínio usam o prefixo sc-domain:), query, is_anonymized_query, country (ISO-3166-1 Alpha-3), search_type (web/image/video/news/discover/googleNews), device, impressions, clicks e sum_top_position.
  2. searchdata_url_impression — “Contains performance data for your property aggregated by URL.” (tradução) «Contém dados de desempenho da sua propriedade agregados por URL». Tudo acima, além de url (“The fully-qualified URL where the user eventually lands when they click the search result”; (tradução) «A URL totalmente qualificada onde o usuário finalmente chega ao clicar no resultado da pesquisa»), is_anonymized_discover, uma família de flags booleanas is_[search_appearance_type] (por exemplo, is_amp_top_stories, is_job_listing, is_tpf_faq) para segmentar por tipo de resultado avançado, e sum_position. Esta é a tabela granular usada na maior parte das análises.
  3. ExportLog — “A record of what data was saved for that day. Failed exports are not recorded here.” (tradução) «Um registro dos dados salvos naquele dia. Exportações com falha não são registradas aqui».) Os campos incluem agenda (atualmente apenas SEARCHDATA), namespace (qual tabela foi gravada), data_date, epoch_version (“An integer, where 0 is the first time data was saved to this table”; (tradução) «Um inteiro em que 0 é a primeira vez que os dados foram salvos nesta tabela» — ele aumenta quando o Google revisa posteriormente os dados de um dia) e publish_time.

A ressalva das consultas anonimizadas é a mais importante. Mesmo aqui, no nível bruto, as consultas anonimizadas não são reveladas. Como diz a descrição de campo do Google, quando is_anonymized_query é true, o campo query “will be a zero-length string.” (tradução) «será uma string de comprimento zero». As métricas ainda são agregadas aos seus totais, mas nunca são atribuídas a um termo específico — exatamente a mesma limitação da interface e da API. Isso importa muito em escala: no meu estudo da Ahrefs sobre termos ocultos do GSC, em 146 741 sites e aproximadamente 9 bilhões de cliques, 46,08 % de todos os cliques foram para consultas que o Google não divulga — e o estudo usou a API do Search Console, que “allows us to get all of the data—and there’s still a lot missing.” (tradução) «permite obter todos os dados — e ainda falta muita coisa». A exportação do BigQuery não recupera nada disso. Se alguém disser que a exportação em massa “finally shows you the hidden queries,” (tradução) «finalmente mostra as consultas ocultas», está errado.

Como configurar

O fluxo (iniciar uma nova exportação de dados em massa):

  1. Crie ou escolha um projeto do Google Cloud com faturamento habilitado. Segundo o Google: “Data is subject to Google Cloud storage and query costs, but there is a free usage level.” (tradução) «Os dados estão sujeitos a custos de armazenamento e consulta do Google Cloud, mas existe um nível de uso gratuito».) Você precisa manter o faturamento ativado mesmo para ficar dentro da camada gratuita.
  2. Ative a BigQuery API e a BigQuery Storage API nesse projeto.
  3. Conceda acesso à conta de serviço de exportação do Google. Adicione search-console-data-export@system.gserviceaccount.com como principal com duas funções do IAM: BigQuery Job User (bigquery.jobUser) e BigQuery Data Editor (bigquery.dataEditor).
  4. No Search Console, acesse Settings → Bulk data export. Cole o ID do projeto do Cloud (o ID, não o número do projeto), escolha um nome de conjunto de dados e uma localização do conjunto de dados. Observe a regra de nome: “The dataset name always starts with the string searchconsole, even when you customize it.” (tradução) «O nome do conjunto de dados sempre começa com a string searchconsole, mesmo quando você o personaliza».) Se definir uma política de expiração de partição no próprio conjunto de dados da exportação, mantenha-a em 14 dias ou mais — o Google documenta um mínimo de 14 dias, e um valor menor é uma causa documentada de falha. Deixe o esquema das tabelas geradas intacto; alterá-lo é outra forma documentada de quebrar a exportação (mais detalhes em Solução de problemas abaixo).
  5. Espere. O Google diz que o processo de exportação deve começar em cerca de um dia após a ativação. “The first export will happen up to 48 hours after your successful configuration in Search Console,” (tradução) «A primeira exportação ocorrerá até 48 horas após a configuração bem-sucedida no Search Console») e a primeira entrega contém apenas os dados do dia da exportação — nada anterior à configuração (veja a próxima seção sobre não haver preenchimento retroativo). Depois disso, ela funciona diariamente até você interrompê-la.
Evidência desta afirmação Setup requires a billed Google Cloud project, BigQuery API and BigQuery Storage API, plus BigQuery Job User and BigQuery Data Editor roles for search-console-data-export@system.gserviceaccount.com. Escopo: verified property and public web as applicable Confiança: alta · Verificado: Start a new bulk data export

Uma expectativa prática: os dados do Search Console chegam com um atraso de dois dias, portanto o dia mais recente disponível será sempre o de dois dias atrás. Se você solicitar um intervalo de 30 dias, na prática obterá cerca de 28 dias de dados utilizáveis.

A armadilha de não haver preenchimento retroativo

Diga isso em voz alta, porque muita gente se dá mal: ativar a exportação não traz seus dados históricos. Ela começa no dia da ativação e só acumula dados dali em diante. Isso é tão comum que o fórum da comunidade do Google tem vários tópicos sobre o assunto — “How to backfill with historical data when Bulk data export is activated” (tradução) «Como fazer backfill de dados históricos quando a exportação de dados em massa é ativada») (tópico 300051568), tópico 255704574 e tópico 429248330. Antoine Eripret é direto em seu aprofundamento prático: “You can’t get historical data: if you activate it today, you’ll have data from today.” (tradução) «Você não pode obter dados históricos: se ativar hoje, terá dados a partir de hoje». A conclusão é simples: ative-a no dia em que ouvir falar dela, mesmo que ainda não esteja pronto para analisar nada, para começar a contar o tempo.

Quanto custa e como não ser surpreendido

A publicação do Google Cloud Blog de Daniel Waisberg e Gaal Yahas destaca os benefícios — “If you have a large website, this solution will provide more queries and pages than the other data exporting solutions” (tradução) «Se você tem um site grande, esta solução fornecerá mais consultas e páginas do que as outras soluções de exportação») e “Search Console stores up to sixteen months of data; using BigQuery you can store as much data as it makes sense to your organization” (tradução) «O Search Console armazena até dezesseis meses de dados; usando o BigQuery, você pode armazenar tantos dados quanto fizer sentido para sua organização») — mas a mecânica dos custos fica por sua conta.

Até o momento desta redação, a camada gratuita do BigQuery é de aproximadamente 10 GiB de armazenamento gratuito, mais 1 TiB (~1 TB) de processamento de consultas sob demanda gratuito por mês; além disso, custa cerca de 6,25 USD por TiB processado e aproximadamente 0,02 USD por GB armazenado por mês (varia conforme a região e a classe de armazenamento). Os preços mudam, então verifique os números atuais antes de citá-los para alguém. A maioria dos sites pequenos e médios permanece gratuita ou quase gratuita.

As cobranças vêm de como você consulta, não de quanto tráfego tem. Duas coisas importam:

  • O custo aumenta com a diversidade de consultas/palavras-chave, não com o tráfego bruto. Como Trevor Fox explica em seu guia completo: “The volume of data that is more a factor of keyword variety than it is search volume. A site with a low search volume for lots of keywords will generate more data than a site with lots of search volume for a single keyword.” (tradução) «O volume de dados depende mais da variedade de palavras-chave do que do volume de pesquisa. Um site com pouco volume de pesquisa para muitas palavras-chave gerará mais dados do que um site com muito volume de pesquisa para uma única palavra-chave».)
  • Não aponte um painel ativo para as tabelas brutas. Esta é a história clássica de terror. Antoine Eripret documentou o Looker Studio examinando 23 TB em um único dia, cerca de €115, quando conectado diretamente às tabelas brutas com bilhões de linhas. A própria publicação do Google sobre eficiência do BigQuery diz o mesmo em princípio: pré-agregue em tabelas de resumo, filtre a partição de data em uma cláusula WHERE, evite SELECT *, configure alertas de orçamento e use expiração de partições para excluir partições antigas automaticamente.

A solução é sem graça, mas eficaz: materialize os resultados das consultas em pequenas tabelas de resumo permanentes segundo um cronograma e aponte seus painéis para elas, não para a exportação bruta.

Consultas: as regras para manter a sanidade (e o custo baixo)

Das diretrizes de consulta do Google:

  • Sempre agregue. “Data in the tables is not guaranteed to be consolidated by date, URL, site, or any combination of keys.” (tradução) «Não há garantia de que os dados nas tabelas estejam consolidados por data, URL, site ou qualquer combinação de chaves».) Isso significa que você receberá várias linhas para o mesmo dia/URL/consulta; portanto, sempre use SUM() nas métricas e GROUP BY nas dimensões. Nunca trate uma única linha como um número final.
  • Filtre a partição de data. “A good way to minimize query costs is to use a WHERE clause to limit the date range in the date partitioned table.” (tradução) «Uma boa forma de minimizar os custos de consulta é usar uma cláusula WHERE para limitar o intervalo de datas na tabela particionada por data».)
  • Descarte linhas anonimizadas quando quiser consultas reais. “An anonymized query is reported as a zero-length string in the table” (tradução) «Uma consulta anonimizada é informada como uma string de comprimento zero na tabela») — portanto, acrescente WHERE query != ''.
  • A posição começa em zero. As duas tabelas armazenam a posição começando em 0, então a posição média é SUM(sum_top_position) / SUM(impressions) + 1 (some 1).

O Google fornece consultas de exemplo para estatísticas diárias da pesquisa na web, principais consultas em dispositivos móveis por país, URLs do Discover por cliques, desempenho de resultados avançados de FAQ (is_tpf_faq = true) e acompanhamento de consultas de marca via REGEXP_CONTAINS. Comece por elas.

Gerenciar e solucionar problemas da exportação

De gerenciar e monitorar exportações de dados em massa:

  • Interromper não é instantâneo. Settings → Bulk data export → Deactivate export. “Bulk exports will stop in the next 24 hours,” (tradução) «As exportações em massa serão interrompidas nas próximas 24 horas»), então mais um dia de dados pode chegar depois que você desativá-la.
  • São dois limites de falha, não um. “Search Console retains data from failed exports for about a week.” (tradução) «O Search Console mantém os dados de exportações com falha por cerca de uma semana».) E depois: “Search Console will stop trying to export data for a given date after about a week of failed attempts, and after about a month of failed export attempts, Search Console will stop the bulk export entirely.” (tradução) «O Search Console deixará de tentar exportar dados de uma determinada data após cerca de uma semana de tentativas malsucedidas e, após cerca de um mês de tentativas malsucedidas, interromperá totalmente a exportação em massa».) Portanto, um problema prolongado não apenas pula dias — depois de ~um mês ele desliga toda a exportação, e você terá de configurá-la novamente.
  • A armadilha de mudar o esquema (e o limite de expiração da partição). Se você alterar o esquema de uma tabela exportada, quebrará a exportação. O Google também exige pelo menos 14 dias de expiração de partição no conjunto de dados da exportação — definir um período menor pode causar falha. Deixe essas tabelas intactas e crie suas próprias tabelas derivadas. (Outras causas comuns incluem exceder a cota do projeto do Cloud e revogar o acesso da conta de serviço.)
  • Use o Test report. Há um recurso “Test report” que permite verificar alguns problemas corrigíveis — ID/credenciais do projeto e permissões — sem esperar a próxima execução agendada. Ele não força uma nova exportação imediata; verifique novamente cerca de 24 horas depois para confirmar a correção.
  • O Search Console envia e-mails aos proprietários quando começam e quando resolvem erros de exportação, e Settings mostra o status da tentativa de exportação mais recente.

Onde isso se encaixa: interface → API → exportação em massa

Pense em três degraus de uma escada, cada um removendo um limite atingido pelo degrau abaixo:

  • Exportação pela interface — ~1 000 linhas, ~16 meses, sem consultas anonimizadas. Suficiente para a maioria.
  • API do Search Console — mais linhas, ainda limitada e sujeita a limites de taxa, e ainda sem consultas anonimizadas. Boa para extrações pontuais e programáticas.
  • Exportação de dados em massa — sem limite de linhas, retenção sob seu controle, dados diários granulares, feita para armazenamento e combinações. Ainda sem consultas anonimizadas. Não faz backfill.

E há uma nuance que os guias antigos erram: você não está limitado a uma propriedade por projeto do Cloud. Mais tarde, o Google permitiu várias propriedades em um único projeto usando nomes de conjuntos de dados distintos com o prefixo searchconsole_.

E o Bing?

Até o momento desta redação, não existe equivalente nativo. O Bing Webmaster Tools não oferece uma exportação própria para BigQuery/em massa — exatamente por isso existe um mercado de conectores ETL de terceiros (Supermetrics, Improvado, Catchr e outros) para mover dados do Bing Webmaster Tools para o BigQuery. Se o Bing tivesse um pipeline nativo, esse mercado não existiria. Ainda assim, não há garantia de que um conector reproduza campo a campo o esquema ou o comportamento de partição diária da exportação do GSC — verifique o escopo documentado de qualquer conector antes de presumir equivalência. Se quiser dados do Bing no BigQuery ao lado da exportação do GSC, reserve verba para um conector e verifique o que ele realmente entrega. (Confirme se isso continua atual antes de citar: os recursos do Bing podem mudar.)

Para o contexto mais amplo de onde isso se encaixa, consulte o hub de Ferramentas de mecanismos de busca e seus guias sobre o Google Search Console e o Bing Webmaster Tools.

Adicionar uma nota de especialista

Fixar uma citação de especialista

É uma pessoa nova? Crie o perfil não reivindicado dela em /admin/experts/ → Fixar uma citação de especialista primeiro.