Pular para o conteúdo
Saiku Cloud

Conectar MotherDuck

Este guia mostra como conectar um banco MotherDuck (DuckDB na nuvem) ao Saiku Cloud. Três minutos depois de ter uma conta MotherDuck; o onboarding mais simples de data warehouse na nuvem que suportamos, porque não há firewall para configurar.

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

Driver: o Saiku Cloud traz o driver JDBC oficial do DuckDB. O prefixo de URL jdbc:duckdb:md:... roteia para o serviço de nuvem do MotherDuck; o mesmo driver também serve arquivos DuckDB locais.

O que você vai precisar

  • Uma conta MotherDuck (tier gratuito basta — 10 GB de storage, suficiente para cubos do tamanho do FoodMart).
  • Um token de serviço do MotherDuck.
  • O nome do banco que você quer que o Saiku leia.

Passo 1 — Obtenha um token de serviço

O MotherDuck autentica via um único token de longa duração. Você não precisa configurar firewalls ou allowlists de IP — o MotherDuck cuida da acessibilidade de rede de forma transparente.

  1. Faça login em https://app.motherduck.com/.

  2. Clique no seu perfil → Settings → Service tokens (ou o equivalente na UI atual do console — o MotherDuck ocasionalmente ajusta a navegação).

  3. Create token → dê um nome como saiku-cloud → copie a string eyJh... resultante imediatamente. O MotherDuck só mostra o token uma vez.

  4. Salve no seu gerenciador de senhas (1Password, Bitwarden) sob um rótulo como saiku-motherduck-token.

Passo 2 — Identifique o nome do banco

O MotherDuck mostra seus bancos na barra lateral esquerda do app. Para trabalho de demo no estilo FoodMart, o nome default geralmente é my_db; para cubos de produção, você terá seu próprio nome como analytics ou sales.

Passo 3 — Monte a URL JDBC

O formato:

jdbc:duckdb:md:<database>?motherduck_token=<token>

Concreto:

jdbc:duckdb:md:analytics?motherduck_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ5b3UifQ.signature-here

Pontos a notar:

  • O token fica na URL, não no campo de senha do wizard. Os campos de usuário + senha no wizard são ignorados pelo driver do MotherDuck — preencha com qualquer coisa (a validação de atributo obrigatório do wizard precisa de algo, mas o valor nunca chega ao MotherDuck).
  • Sem porta; sem host. O MotherDuck cuida do roteamento.
  • Sem parâmetro SSL — o driver criptografa a sessão inteira por TLS por default.

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 MotherDuck.

  4. Preencha:

    • URL JDBC — a URL do passo 3.
    • Usuário — qualquer coisa (ex.: motherduck). Ignorado pelo driver.
    • Senha — qualquer coisa não vazia (ex.: unused-token-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 DuckDB.

Passo 5 — Salve a conexão

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

Solução de problemas

✗ Connection failed (AUTH_FAILED)

O token na URL está errado, expirado ou revogado.

  • Gere um token novo no console do MotherDuck.
  • Garanta que você copiou o token inteiro — eles são longos (300+ caracteres) e fáceis de truncar.
  • Confira a URL: NÃO deve haver espaço em branco em volta de motherduck_token=.

✗ Connection failed (HOST_UNREACHABLE) ou (TIMEOUT)

O endpoint de nuvem do MotherDuck deve ser alcançável de qualquer lugar com internet. Se você vir isso, o próprio MotherDuck provavelmente está fora — confira a página de status deles.

✗ Connection failed (INVALID_URL)

A URL não começa com jdbc:duckdb:md:. Note o segmento md: — é o que diz ao driver para rotear para o MotherDuck em vez de um arquivo local. Sem ele, o driver tenta abrir um arquivo literal chamado <database> no diretório de trabalho do engine.

A conexão sucede mas a lista de cubos está vazia

O token é válido + o banco existe, mas o banco não tem tabelas. Ou:

  • Você conectou a um banco vazio recém-criado — carregue algum dado pela UI SQL do console do MotherDuck primeiro.
  • O banco tem tabelas mas elas estão em um schema não padrão — confirme no console e ajuste seu XML de schema.

Arquivos locais para self-hosted ou fluxos de export-import {#local-files-for-self-hosted-or-export-import-workflows}

O driver DuckDB também serve arquivos locais (jdbc:duckdb:/path/to/file.duckdb). No Saiku Cloud hospedado, esse caminho resolve no filesystem do container do engine, não no seu — então o caminho de dados por upload de arquivo é a forma padrão de colocar um arquivo local no Saiku. Veja Conectar um arquivo enviado via DuckDB para esse fluxo.

Para implantações self-hosted do Saiku Cloud em que o operador pode pôr arquivos no host do engine diretamente, cole jdbc:duckdb:/var/lib/saiku/your.duckdb no wizard e conecte normalmente.

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 MotherDuck:

Dataset de exemplo FoodMart para MotherDuck