Resolver problemas de erros e limitações do conector do BigQuery

Ao conectar o Data Studio ao BigQuery, você pode encontrar tempos limite, limites de sintaxe SQL, limites de cota ou erros do VPC Service Controls. Este guia descreve problemas comuns no conector do BigQuery. Expanda Etapas de resolução para investigar e corrigir o problema.

Erros de sintaxe de consulta e SQL

As consultas SQL personalizadas no Data Studio têm limitações específicas. Se a consulta violar esses limites, poderão ocorrer erros.

Erro de junção Field is ambiguous

Se a consulta personalizada contiver nomes de coluna duplicados, os gráficos vão mostrar este erro:

User Configuration Error: Field is ambiguous

Texto da mensagem de erro: Erro de configuração do usuário

Causa:as tabelas unidas (JOIN) não podem compartilhar nomes de coluna duplicados. Por exemplo, se você unir duas tabelas com esquemas idênticos em um campo Criteria_ID, a tabela virtual resultante terá colunas duplicadas (Criteria_ID, Parent_ID, Name), o que aciona um erro de ambiguidade.

Etapas de resolução

Para tornar todos os nomes de coluna exclusivos, use a palavra-chave AS ou a cláusula EXCEPT:

Opção 1: renomear explicitamente os campos duplicados usando aliases

SELECT *
FROM (
  SELECT
    Criteria_ID AS Criteria_ID_1,
    Parent_ID AS Parent_ID_1,
    Name AS NAME_1
  FROM
    `project.dataset.table_1` ) AS table_1
LEFT JOIN (
  SELECT
    Criteria_ID AS Criteria_ID_2,
    Parent_ID AS Parent_ID_2,
    Name AS NAME_2
  FROM
    `project.dataset.table_2` ) AS table_2
ON
  table_1.Criteria_ID_1 = table_2.Criteria_ID_2;

Opção 2: excluir e renomear campos específicos usando EXCEPT

Se você só precisar renomear um pequeno número de campos, mantendo o restante, use EXCEPT:

SELECT * EXCEPT (city), city AS city_1 FROM `project.dataset.table_1`

Erro de sintaxe de consulta SQL personalizada (várias instruções)

A consulta SQL personalizada falha se contiver variáveis ou várias instruções (DECLARE, SET).

Causa: o Data Studio executa o SQL dentro de uma consulta SELECT externa (SELECT * FROM (<your_custom_sql>)). Portanto, a consulta precisa ser uma única instrução SELECT.

Por exemplo, a consulta a seguir falha porque declara uma variável antes de selecionar:

DECLARE cost_per_tb_in_dollar FLOAT64 DEFAULT 4.2;
SELECT total_bytes_billed / (1024 * 1024) * cost_per_tb_in_dollar / (1024 * 1024) FROM `billing_table`;

Etapas de resolução

Combine os cálculos em uma instrução SELECT usando expressões de tabela comuns (CTEs ou cláusulas WITH):

WITH constants AS (
  SELECT 4.2 AS cost_per_tb_in_dollar
)
SELECT
  total_bytes_billed / (1024 * 1024) * c.cost_per_tb_in_dollar / (1024 * 1024) AS cost
FROM `billing_table`, constants AS c;

Tempos limite de desempenho e consulta

Quando as consultas levam mais de três a cinco minutos para serem executadas, o Data Studio atinge o tempo limite antes de receber os resultados, retornando: HTTP 504 Gateway timeout.

HTTP 504 Gateway timeout ou erros de consulta de longa duração

As consultas personalizadas ou agregações de gráficos complexas no Data Studio podem atingir o tempo limite após três a cinco minutos, o que retorna um erro HTTP 504 Gateway timeout.

Etapas de resolução

Se as consultas atingirem o tempo limite de forma consistente, use estas otimizações:

  • Ative a API BigQuery Storage Read: ative a API BigQuery Storage Read para aumentar a capacidade de processamento de dados.
  • Simplifique a consulta:remova comandos `JOIN` desnecessários, agrupe dados por períodos mais amplos e selecione apenas as colunas necessárias.
  • Use o BigQuery BI Engine: reserve capacidade com o BigQuery BI Engine para desempenho em menos de um segundo.
  • Use visualizações de banco de dados: salve seu SQL personalizado como uma visualização do BigQuery ou uma visualização materializada e conecte o Data Studio diretamente a essa visualização.
  • Pré-agregue em uma tabela de relatórios:use consultas programadas no BigQuery para gravar registros de resumo em uma tabela separada e consultar a tabela de resumo.

Cotas e limitações de tabela

Quando o conjunto de dados contém milhares de tabelas ou retorna milhões de registros, podem ocorrer erros de limite:

Congelamento da capacidade de resposta da interface do usuário do conjunto de dados com mais de 5.000 tabelas

Ao tentar se conectar a um conjunto de dados do BigQuery usando a lista de seleção de tabelas no Data Studio, a interface do usuário congela ou deixa de responder.

Causa:o conector oferece suporte a até 5.000 tabelas por conjunto de dados. Se um conjunto de dados exceder 5.000 tabelas ou visualizações, a lista de seleção de tabelas vai atingir o tempo limite e congelar.

Etapas de resolução

Use uma destas alternativas para se conectar sem carregar a lista de tabelas:

  • Conecte-se usando uma consulta personalizada:selecione CONSULTA PERSONALIZADA e escreva uma instrução `SELECT` menos complexa: 
    SELECT * FROM `your_project.your_dataset.your_table`
  • Conecte-se diretamente do BigQuery: no console do BigQuery, localize a tabela, clique em Exportar ou Explorar dados e selecione Abrir com o Looker Studio.
  • Divida ou reorganize o conjunto de dados:mova as tabelas de relatórios para conjuntos de dados de relatórios menores e dedicados que contenham menos de 5.000 tabelas.

Limite máximo de retorno de 2 milhões de linhas

Ao visualizar conjuntos de dados grandes, o gráfico pode mostrar um aviso de truncamento de dados ou omitir linhas que estejam além de 2 milhões de registros.

Causa:o conector retorna um máximo de 2 milhões de linhas por consulta de gráfico. Se uma consulta exceder 2 milhões de registros, os gráficos vão truncar os dados e mostrar um aviso.

Etapas de resolução

Para evitar o truncamento de dados:

  • Aplique filtros de data no nível do relatório para restringir o volume de consultas.
  • Consulte tabelas particionadas por data (`DATE`, `DATETIME`, `TIMESTAMP`) que exigem filtros de partição (saiba mais).
  • Agrupe dimensões de alta cardinalidade no BigQuery antes de visualizar no Data Studio.

Variância MEDIAN e PERCENTILE

Ao calcular medianas exatas (MEDIAN) ou percentis (PERCENTILE) em gráficos conectados ao BigQuery, a saída pode ser ligeiramente diferente de cálculos idênticos realizados em outros bancos de dados SQL ou exportações CSV.

Causa: nas consultas do BigQuery, MEDIAN e PERCENTILE usam a função de agregação aproximadaAPPROX_QUANTILES. Isso processa conjuntos de dados de petabytes rapidamente, mas os resultados aproximados podem ser ligeiramente diferentes dos cálculos exatos realizados em exportações CSV ou outros bancos de dados SQL.

Erros de tipo de dados e criptografia

Saiba como lidar com tipos de coluna não compatíveis e políticas de criptografia de chaves impostas pela organização.

Erro de criptografia CONDITION_NOT_MET (CMEK)

Ao consultar um conjunto de dados, o gráfico falha e retorna o seguinte erro:

User Configuration Error: CONDITION_NOT_MET

Causa:o conector não oferece suporte a chaves de criptografia gerenciadas pelo cliente (CMEK). Se uma política da organização exigir criptografia CMEK para consultas ou armazenamento temporário (serviço de política da organização), os gráficos vão mostrar User Configuration Error: CONDITION_NOT_MET.

Etapas de resolução

Trabalhe com o administrador da organização para isentar o projeto de relatórios da política de CMEK ou exportar dados do relatório para um conjunto de dados regido pelo padrão Google-owned and Google-managed encryption keys.

Tipo de dados TIME não compatível

Ao se conectar a uma tabela do BigQuery que contém colunas do tipo de dados TIME (por exemplo, 23:59:59), o Data Studio converte o campo em TEXT, o que impede a classificação ou agregações com base no tempo.

Causa:o Data Studio não oferece suporte nativo ao tipo de dados TIME do BigQuery (por exemplo, 23:59:59). O conector converte colunas TIME em strings TEXT após a ingestão, impedindo a classificação com base no tempo.

Etapas de resolução

Converta colunas `TIME` em objetos DATETIME usando uma destas soluções alternativas:

Solução alternativa 1: usar uma consulta SQL personalizada

Combine o campo `TIME` com uma data base (`1970-01-01`) diretamente no SQL:

SELECT
  *,
  -- Combine a dummy date (1970-01-01) with your TIME field
  DATETIME(DATE "1970-01-01", your_time_field) AS time_as_datetime
FROM
  `your_project.your_dataset.your_table`
  • Resultado: o Data Studio ingere `time_as_datetime` como um campo **Data e hora**.
  • Formatação:nas propriedades do gráfico do relatório, mude o **formato de exibição** do campo para **Hora**, **Minuto** ou um formato de hora personalizado (`h:mm:ss`) para mostrar apenas a parte de hora (saiba mais).

Solução alternativa 2: criar um campo calculado no Data Studio

Se você não modificar a consulta SQL, crie um campo calculado na fonte de dados:

PARSE_DATETIME("%H:%M:%S", CAST(your_time_field AS TEXT))
  • Resultado: a função `PARSE_DATETIME` analisa a string de texto em um objeto **Data e hora** , definindo a data do calendário como 1º de janeiro de 1970 (saiba mais).

Erros do VPC Service Controls

Resolva erros de acesso negado e restrições de processos em segundo plano ao trabalhar em perímetros de serviço.

Service Control Failure ao visualizar relatórios fora da VPN

Ao visualizar um relatório fora da VPN ou da rede corporativa da sua organização, alguns ou todos os gráficos falham com o seguinte erro:

Service Control Failure

Causa: o conector transmite o endereço IP do visualizador de relatórios para o BigQuery para verificar os níveis de acesso com base no IP do VPC Service Controls. Ao copiar um relatório, as fontes de dados SQL personalizadas legadas ou "fantasma" dentro da cópia podem fazer referência a um projeto de faturamento protegido dentro de um perímetro de serviço, mesmo que o conjunto de dados principal resida fora.

Etapas de resolução

Identifique e remova ou reatribua todos os projetos de faturamento vinculados ao perímetro oculto no relatório:

  1. Faça uma cópia do relatório afetado para solucionar problemas com segurança.
  2. No editor de relatórios da cópia, acesse Recurso > Gerenciar fontes de dados adicionadas.
  3. Revise todas as fontes de dados **BigQuery** ou **SQL personalizadas** incorporadas anexadas ao relatório.
  4. Edite cada conexão SQL personalizada para verificar o **projeto de faturamento** configurado. Se alguma fonte de dados apontar para um projeto de faturamento protegido por um perímetro do VPC Service Controls, atualize-o para usar um projeto de faturamento não protegido ou exclua a fonte de dados se ela não for mais usada.

Falhas na entrega de e-mails programados ou alertas de gráficos por trás do VPC Service Controls

Quando os recursos automatizados em segundo plano (como entrega de e-mails programada ou alertas de gráficos) são executados em um gráfico conectado a um conjunto de dados do BigQuery protegido pelo VPC Service Controls, o e-mail programado é entregue sem conteúdo ou anexos de relatório, ou o alerta não é acionado (VPC Service Controls unexpected field in error map).

Causa:como os recursos automatizados em segundo plano (como entrega de e-mails programada ou alertas de gráficos) são executados como tarefas em segundo plano sem um endereço IP do usuário final, o VPC Service Controls (VPC-SC) os bloqueia ao avaliar os níveis de acesso com base no IP (VPC Service Controls unexpected field in error map).

Etapas de resolução

Para usar recursos automatizados em segundo plano por trás de um perímetro do VPC Service Controls, configure a fonte de dados para usar credenciais de conta de serviço ou crie um nível de acesso baseado em identidade: