Conectar um data warehouse BigQuery

Este guia mostra como conectar um dataset do Google BigQuery ao Saiku Cloud. Quinze minutos se você já tem uma service account; trinta se também precisar criar uma no IAM.

Impacto no tier: todos os tiers do Saiku Cloud suportam BYOC do BigQuery.

Driver: o Saiku Cloud traz o driver JDBC oficial do BigQuery do Google (Apache 2.0, ~56 MB shaded). A autenticação é via chave JSON de service account — não há caminho de autenticação por senha.

O que você vai precisar

• Um projeto do Google Cloud com BigQuery habilitado.
• Um dataset dentro desse projeto onde ficam seus dados analíticos.
• Permissão IAM Owner ou equivalente para criar uma service account.

Passo 1 — Acesso à rede (boa notícia)

A API do BigQuery é um serviço gerenciado pelo Google, alcançável de qualquer host conectado à internet. Não é necessária allowlist de firewall. O IP de egress do Saiku Cloud (87.99.153.244) é um dos muitos que vão bater na API do BigQuery; a edge do Google cuida do roteamento de forma transparente.

Pule para o passo 2.

Passo 2 — Crie uma service account somente leitura

O Saiku Cloud precisa de BigQuery Data Viewer (para SELECT) + BigQuery Job User (para execução de queries).

No console do Google Cloud:

1. IAM & Admin → Service Accounts → Create service account.

2. Nome: saiku-read. Descrição: Saiku Cloud read-only access.

3. Conceda papéis:

   • BigQuery Data Viewer — restrinja a datasets específicos se quiser acesso mais estrito (Data Viewer no escopo do projeto lê todos os datasets; no escopo do dataset lê só aquele).
   • BigQuery Job User — precisa estar no escopo do projeto (BigQuery não suporta Job User com escopo de dataset).

4. Clique na service account criada → Keys → Add Key → Create new key → JSON. O navegador baixa um arquivo <project>-<id>.json.

5. Esta é a credencial — salve no seu gerenciador de senhas. Ela contém a chave privada.

Passo 3 — Monte a URL JDBC

O formato (separado por ponto e vírgula, NÃO querystring):

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=<PROJECT>;OAuthType=0;OAuthServiceAcctEmail=<SA_EMAIL>;OAuthPvtKey=<INLINE_PEM>;DefaultDataset=<DATASET>

Exemplo concreto com PEM inline:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=saiku-read@my-analytics-prod.iam.gserviceaccount.com;OAuthPvtKey=-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEF...-----END PRIVATE KEY-----;DefaultDataset=analytics

Mapa de parâmetros:

• https://www.googleapis.com/bigquery/v2:443 — o endpoint da API. Sempre este para o serviço público do BigQuery. Endpoints de Private Service Connect têm um formato diferente (veja Enterprise: rede privada).
• ProjectId= — o id do seu projeto no Google Cloud (o alfanumérico da URL do console, não o nome do projeto).
• OAuthType=0 — auth por chave de service account. Outros valores: 1 (OAuth de usuário — não suportado no Saiku), 3 (Application Default Credentials — só funciona se o engine tiver acesso ao ADC, o que geralmente não é o caso na implantação hospedada do Saiku Cloud).
• OAuthServiceAcctEmail= — o e-mail da service account, copiado do passo 2 item 4. Formato: <saname>@<project>.iam.gserviceaccount.com.
• OAuthPvtKeyPath= OU OAuthPvtKey= — um ou outro.
  • OAuthPvtKeyPath=/path/to/key.json — o driver lê o arquivo em tempo de execução. Não funciona no Saiku Cloud hospedado porque você não pode soltar arquivos no filesystem do container do engine.
  • OAuthPvtKey=<PEM inline> — o conteúdo literal -----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY----- do campo private_key da chave JSON, com \n literais entre as linhas. Use isso para o cloud-hospedado.
• DefaultDataset= — o dataset do BigQuery (o segundo segmento de project.dataset.table). Permite que schemas referenciem nomes de tabela não qualificados como <Table name='sales'/> em vez de qualificar totalmente cada referência. Obrigatório para schemas BYOC carregarem pelo Mondrian do Saiku Cloud (a API de metadados do driver só resolve tabelas não qualificadas quando isso está definido).

Lado da autoria de cubo: propriedades schema/catalog para introspecção de metadados

Quando você sobe um XML de schema Mondrian pelo Saiku Cloud que referencia tabelas BigQuery não qualificadas (ex.: <Table name='salary'/> e não <Table name='salary' schema='analytics'/>), o Saiku Cloud também precisa saber o dataset e o projeto para introspecção de metadados via JDBC. Esses são passados como propriedades da connect-string no nível do wrapper Mondrian, além da URL acima:

• JdbcSchema=<dataset> — mesmo valor de DefaultDataset= na URL.
• JdbcCatalog=<project> — mesmo valor de ProjectId= na URL.

O wizard de conexão do Saiku Cloud deriva automaticamente esses valores dos parâmetros ProjectId= + DefaultDataset= da URL quando você salva a conexão, então a maioria dos clientes nunca os vê. Mencionados aqui porque o formato .sds do engine em disco os inclui, e eles aparecem nos audit logs:

jdbc:mondrian:Jdbc='jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-analytics-prod;OAuthType=0;OAuthServiceAcctEmail=...;OAuthPvtKey=...;DefaultDataset=analytics';Catalog=file:/var/lib/saiku/data/<your-schema>.xml;JdbcDrivers=com.google.cloud.bigquery.jdbc.BigQueryDriver;JdbcSchema=analytics;JdbcCatalog=my-analytics-prod

Cuidado

Dois detalhes importantes de formato se você precisar autorar esse .sds à mão (ex.: para testar no engine OSS):

1. Coloque a URL JDBC interna entre aspas simples. O parser de connect-string do Mondrian usa ; como separador de propriedades de topo — o mesmo separador que o driver do BigQuery usa DENTRO da URL dele. As aspas simples dizem ao Mondrian para preservar os ; internos em vez de dividi-los. Sem elas você recebe IllegalStateException: Invalid Auth type specified: -1 porque o Mondrian remove os parâmetros do BigQuery antes de passar a URL ao driver.
2. JdbcSchema= e JdbcCatalog= ficam FORA da URL com aspas, no nível de propriedade do Mondrian (ao lado de Catalog=, JdbcDrivers=). Dentro da URL eles seriam parseados pelo driver do BigQuery e ignorados — eles só importam para a camada de introspecção de metadados do Mondrian.

Esses dois requisitos estão documentados em detalhe nas notas BigQuery-Mondrian com o catálogo de modos de falha.

Extraindo a chave privada do JSON

O JSON baixado no passo 2 parece com:

{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n",
  "client_email": "...",
  ...
}

Pegue o valor de private_key, remova as aspas externas, e isso é o que vai em OAuthPvtKey= (os escapes \n são literais — mantenha como strings com barra-invertida-n, NÃO quebras de linha de verdade).

Passo 4 — Conecte pelo wizard do Saiku Cloud

1. Faça login em https://cloud.saiku.bi/.

2. Vá em Conexões na barra lateral esquerda.

3. Em 1. Escolha o tipo de data warehouse, clique no tile BigQuery.

4. Preencha:

   • URL JDBC — a URL do passo 3.
   • Usuário — qualquer coisa (ex.: bigquery). O driver ignora esse campo; a autenticação está na URL.
   • Senha — qualquer coisa não vazia (ex.: unused-key-in-url). Também ignorado.

5. Clique em Testar conexão.

Espere um banner verde de resultado: ✓ Connection successful mais a versão detectada do BigQuery (algo como BigQuery 2.0). A primeira conexão do BigQuery leva 5–10 segundos (troca de token + listagem de dataset).

Passo 5 — Salve a conexão

Mesmo formato dos outros dialetos — digite a senha placeholder de novo, dê um rótulo, salve.

Cuidado

Armazenamento da chave de service account. O Saiku Cloud armazena o PEM inline no registro criptografado da conexão junto da URL JDBC. O Vault Transit criptografa toda a credencial em repouso. A chave ainda vive na string da URL no momento da descriptografia, mas nunca em variáveis de ambiente, nunca em logs, nunca em respostas da lista de conexões. Um caminho futuro mais limpo — extrair a chave para o Vault como recurso próprio e templatar a URL JDBC com uma referência resolvida pelo Vault — está no roadmap; clientes que entrarem hoje pelo caminho inline poderão migrar de forma transparente quando isso for lançado.

Solução de problemas

✗ Connection failed (AUTH_FAILED)

• Formatação do OAuthPvtKey — a causa mais comum. O PEM precisa ter \n literal entre as linhas (NÃO quebras de linha de verdade). Confira: o valor deve começar com -----BEGIN PRIVATE KEY-----\nMIIE... (barra-invertida-n, não uma quebra de linha).
• Service account não tem BigQuery Job User no escopo do projeto — mesmo com Data Viewer no dataset, o BigQuery rejeita queries de contas sem Job User no nível de projeto.
• Service account desativada ou excluída — confira no console IAM.

✗ Connection failed (DATABASE_NOT_FOUND)

ProjectId= está errado, ou a service account não tem nenhum dataset visível nesse projeto. Verifique se o id do projeto bate com o que aparece na URL do console do Google Cloud.

✗ Connection failed (HOST_UNREACHABLE) ou (TIMEOUT)

A API do BigQuery raramente fica inalcançável; confira a página de status do GCP. Se o GCP está saudável, provavelmente o segmento https://www.googleapis.com/bigquery/v2:443 da URL está com erro de digitação — precisa ser exato.

✗ Connection failed with "OAuthType=1 requires interactive OAuth"

Você definiu OAuthType=1 (OAuth de usuário) em vez de OAuthType=0 (service account). Mude para OAuthType=0 e forneça uma chave de service account.

O cubo renderiza mas sem dados

A service account tem BigQuery Job User (então as queries sobem) mas não tem BigQuery Data Viewer no dataset (então as queries retornam vazio). Adicione Data Viewer no escopo do dataset.

Qualquer outra coisa

Tire um screenshot do wizard com o banner vermelho de resultado visível (especificamente a linha Kind: ...) e mande para support@saiku.bi.

Enterprise: rede privada {#enterprise-private-network}

Para clientes Enterprise, o BigQuery suporta Private Service Connect — o tráfego da API do BigQuery do seu tenant fica dentro de uma rede privada. O endpoint da URL JDBC muda de https://www.googleapis.com/bigquery/v2:443 para o seu endpoint PSC. Entre em contato com seu account team para provisionar o peering.

Teste com FoodMart

Quer testar o Saiku Cloud com esse dialeto antes de conectar seus próprios dados? Baixe o dataset de exemplo FoodMart empacotado para BigQuery:

Dataset de exemplo FoodMart para BigQuery