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. Neste guia, descrevemos problemas comuns no conector do BigQuery. Abra Etapas para resolver 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 mesclagem de Field is ambiguous

Se a consulta personalizada tiver 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 mescladas (JOIN) não podem compartilhar nomes de coluna duplicados. Por exemplo, se você mesclar 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

Dê um nome exclusivo a todas as colunas usando 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 e manter o restante, use EXCEPT:

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

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

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

Causa: o Data Studio executa o SQL em uma consulta SELECT externa (SELECT * FROM (<your_custom_sql>)). Portanto, sua 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;

Tempo limite de desempenho e consulta

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

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

As consultas personalizadas ou as agregações de gráficos complexos 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 expirarem de forma consistente, use estas otimizações:

  • Ativar a API BigQuery Storage Read: ative a API BigQuery Storage Read para aumentar a capacidade de processamento de dados.
  • Simplifique sua 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 ter um desempenho de menos de um segundo.
  • Use visualizações de banco de dados: salve o SQL personalizado como uma visualização do BigQuery ou uma visualização materializada e conecte o Data Studio diretamente a ela.
  • Pré-agregar 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 tabelas

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

Conjunto de dados com mais de 5.000 tabelas: congelamento da capacidade de resposta da UI

Quando você tenta 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 para de responder.

Causa: o conector é compatível com 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 expirar e congelar.

Etapas de resolução

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

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

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

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

Causa: o conector retorna no máximo 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.
  • Consultar tabelas particionadas por data (DATE, DATETIME, TIMESTAMP) que exigem filtros de partição (saiba mais).
  • Agrupe as dimensões de alta cardinalidade no BigQuery antes de visualizar no Data Studio.

Variância de MEDIAN e PERCENTILE

Ao calcular medianas (MEDIAN) ou percentis (PERCENTILE) exatos em gráficos conectados ao BigQuery, o resultado pode ser um pouco diferente de cálculos idênticos realizados em outros bancos de dados SQL ou exportações de CSV.

Causa: nas consultas do BigQuery, MEDIAN e PERCENTILE usam a função de agregação aproximada APPROX_QUANTILES. Isso processa conjuntos de dados em escala de petabytes rapidamente, mas os resultados aproximados podem ser um pouco diferentes dos cálculos exatos realizados em exportações de CSV ou em 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 aplicadas pela organização.

Erro de criptografia de CONDITION_NOT_MET (CMEK)

Quando você consulta um conjunto de dados, o gráfico falha e retorna o seguinte erro:

User Configuration Error: CONDITION_NOT_MET

Causa: quando o Data Studio executa um job de consulta, o BigQuery grava os resultados em uma tabela temporária no projeto de faturamento. Se a restrição da política da organização constraints/gcp.restrictNonCmekServices for aplicada ao BigQuery no projeto de faturamento, o BigQuery vai exigir uma chave de criptografia gerenciada pelo cliente (CMEK) para todas as novas tabelas, incluindo tabelas temporárias de resultados de consulta. Como o conector não transmite uma chave do Cloud Key Management Service em solicitações de job de consulta, as consultas falham com User Configuration Error: CONDITION_NOT_MET, a menos que uma chave padrão do Cloud KMS do projeto esteja configurada.

Etapas de resolução

Configure uma chave padrão do Cloud KMS para o projeto no BigQuery para que ele criptografe automaticamente as tabelas temporárias de resultados de consulta:

  1. Conceda o papel Criptografador/descriptografador de CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave do Cloud KMS à conta de serviço de criptografia do BigQuery para o projeto de faturamento.
  2. Defina uma chave padrão do Cloud KMS para o projeto (region-LOCATION.default_kms_key_name) no projeto de faturamento para o local do conjunto de dados que você está consultando. Exemplo: 
    ALTER PROJECT PROJECT_ID
SET OPTIONS (
  `region-LOCATION.default_kms_key_name` = 'projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY'
);

Como alternativa, trabalhe com o administrador da organização para isentar o projeto de faturamento da política constraints/gcp.restrictNonCmekServices.

Tipo de dados TIME não compatível

Quando você se conecta 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 classificações ou agregações com base no tempo.

Causa: o Data Studio não é compatível com o tipo de dados TIME do BigQuery (por exemplo, 23:59:59). O conector converte as 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 de 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 processa `time_as_datetime` como um campo de **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 da 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 de Data e hora, definindo a data do calendário como 1º de janeiro de 1970.

Erros do VPC Service Controls

Resolver problemas 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

Quando você visualiza 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 leitor de relatórios ao BigQuery para verificar os níveis de acesso com base em IP do VPC Service Controls. Quando você copia um relatório, as fontes de dados SQL personalizadas legadas ou "fantasmas" 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 esteja fora dele.

Etapas de resolução

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

  1. Faça uma cópia do relatório afetado para resolver o problema com segurança.
  2. No editor de relatórios da cópia, acesse Recurso > Gerenciar fontes de dados adicionadas.
  3. Analise todas as fontes de dados incorporadas do **BigQuery** ou do **SQL personalizado** 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-a para usar um projeto de faturamento não protegido ou exclua a fonte de dados se ela não for mais usada.

Falhas no envio de e-mails programados ou nos alertas de gráficos por trás do VPC Service Controls

Quando recursos automatizados em segundo plano (como envio de e-mails programados 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 é enviado sem o conteúdo ou os anexos do 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 o envio de e-mails programados ou alertas de gráficos) são executados como tarefas em segundo plano sem um endereço IP de usuário final, o VPC Service Controls (VPC-SC) os bloqueia ao avaliar os níveis de acesso baseados em IP (VPC Service Controls unexpected field in error map).

Etapas de resolução

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