Como Conectar o Snowflake e o Google BigQuery ao Dust para Consultas SQL em Linguagem Natural

Equipes de análise de dados e operações técnicas enfrentam um desafio recorrente: áreas de negócio demandam métricas operacionais e relatórios pontuais continuamente, enquanto ferramentas tradicionais de BI self-service impõem barreiras técnicas que sobrecarregam os analistas. Por outro lado, bases de conhecimento baseadas em RAG (Geração Aumentada por Recuperação) convencional são incapazes de solucionar essa demanda. A busca semântica depende da similaridade vetorial entre textos, o que inviabiliza somas financeiras, contagens agrupadas ou agregações de taxas em milhões de registros.

O Dust supera essa limitação por meio de conectores estruturados e da funcionalidade Table queries (consultas de tabelas). Em vez de duplicar ou transferir dados confidenciais, o Dust conecta-se diretamente ao Snowflake e ao Google BigQuery, indexa apenas os metadados dos esquemas (Table Schema) e permite que agentes de IA gerem e executem consultas SQL controladas e estritamente de leitura, traduzindo os resultados em insights claros e gráficos dinâmicos.

Este guia prático detalha a arquitetura técnica, as configurações de segurança, a gestão de credenciais e as melhores práticas para conectar o Snowflake e o BigQuery ao Dust, viabilizando o autosserviço analítico empresarial.

Arquitetura: Como o Dust Consulta Data Warehouses sem Armazenar Dados Brutos

Ao integrar repositórios centrais de dados a plataformas de IA, a segurança da informação e a governança são prioridades absolutas. O Dust adota uma arquitetura baseada exclusivamente em metadados:

1. Zero Sincronização de Dados Brutos: O Dust não sincroniza, espelha ou armazena registros transacionais de clientes do Snowflake ou BigQuery. A plataforma indexa unicamente metadados estruturais: nomes de bancos de dados, identificadores de conjuntos de dados (datasets), schemas, nomes de tabelas, nomes de colunas, tipos de dados e descrições nativas dos campos.
2. Injeção de Contexto do Esquema: Quando um colaborador faz uma pergunta analítica (por exemplo: "Qual foi o ticket médio por região no último trimestre?"), o agente consulta os esquemas mapeados para identificar as entidades e métricas necessárias.
3. Geração Controlada de SQL: O modelo de linguagem gera uma instrução SQL rigorosamente adequada ao dialeto do destino (Snowflake SQL ou GoogleSQL).
4. Execução Direta Somente Leitura: A consulta é enviada ao data warehouse por conexão criptografada, utilizando credenciais com permissões estritamente restritas a operações de leitura.
5. Síntese e Auditoria Transparente: O Dust processa o retorno tabular, sintetiza uma resposta em linguagem natural ou gera gráficos e disponibiliza o botão Tools inspection (inspeção de ferramentas) para que qualquer usuário confira o comando SQL exato, a latência de execução e os dados brutos retornados.

Opção 1: Conectando o Snowflake ao Dust

O Dust oferece duas modalidades de integração com o Snowflake: a Snowflake Connection (Conexão gerenciada via Spaces > Connections) e a Snowflake Tool (Ferramenta OAuth para exploração em tempo de execução). Para agentes corporativos focados em métricas oficiais e governança, a Snowflake Connection é a abordagem indicada.

1. Provisionamento de Segurança e Infraestrutura no Snowflake

Seguindo o princípio do menor privilégio, crie um warehouse de computação, um usuário de serviço e um perfil dedicados no Snowflake:

-- Etapa 1: Criar o perfil de acesso
CREATE ROLE dust_role;

-- Etapa 2: Criar o warehouse de computação com suspensão automática
CREATE WAREHOUSE dust_warehouse
WITH WAREHOUSE_SIZE = 'XSMALL'
AUTO_SUSPEND = 300
AUTO_RESUME = TRUE;

GRANT USAGE ON WAREHOUSE dust_warehouse TO ROLE dust_role;

Escolha da Autenticação: Par de Chaves vs. Senha

Como o Snowflake está descontinuando gradualmente o uso de senhas simples para integrações programáticas, recomenda-se enfaticamente o uso de Autenticação por Par de Chaves RSA (Key Pair Authentication).

Configuração com Par de Chaves RSA (Recomendado):

1. Gere uma chave privada RSA de 2048 bits e sua respectiva chave pública:

   openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out dust_rsa_key.p8 -nocrypt
   openssl rsa -in dust_rsa_key.p8 -pubout -out dust_rsa_key.pub
   

2. Extraia o texto limpo da chave pública (removendo cabeçalho, rodapé e quebras de linha):

   cat dust_rsa_key.pub | grep -v "BEGIN PUBLIC KEY" | grep -v "END PUBLIC KEY" | tr -d '\n'
   

3. Crie o usuário no Snowflake associando a chave pública:

   CREATE USER dust_user
     DEFAULT_ROLE = dust_role
     RSA_PUBLIC_KEY = '<COLE_AQUI_A_CHAVE_PUBLICA_LIMPA>';
   
   GRANT ROLE dust_role TO USER dust_user;
   

Alternativa (Autenticação por Senha):

CREATE USER dust_user
  PASSWORD = 'SuaSenhaSeguraAqui'
  DEFAULT_ROLE = dust_role;

GRANT ROLE dust_role TO USER dust_user;

2. Políticas de Rede e Concessão de Privilégios Somente Leitura

Se sua conta Snowflake utiliza Network Policies para restringir acessos de rede, inclua na lista de permissões os IPs estáticos de saída do Dust:

• Workspaces nos EUA (https://dust.tt): 34.46.9.232
• Workspaces na UE (https://eu.dust.tt): 35.195.191.222

Em seguida, conceda permissões de leitura de esquemas e tabelas. O conector do Dust recusa qualquer perfil que possua privilégios de escrita ou modificação (INSERT, UPDATE, DELETE, MERGE):

-- Conceder USAGE no banco de dados e no schema
GRANT USAGE ON DATABASE analytics_dw TO ROLE dust_role;
GRANT USAGE ON SCHEMA analytics_dw.marts TO ROLE dust_role;

-- Conceder SELECT nas tabelas físicas
GRANT SELECT ON ALL TABLES IN SCHEMA analytics_dw.marts TO ROLE dust_role;
GRANT SELECT ON FUTURE TABLES IN SCHEMA analytics_dw.marts TO ROLE dust_role;

Aviso Importante: A conexão gerenciada do Snowflake disponibiliza apenas tabelas físicas para a ferramenta Table Queries; views e views materializadas são ignoradas nesse modo. Se a sua arquitetura analítica exigir consultas sobre views, utilize a Snowflake Tool baseada em OAuth.

3. Ativação da Conexão no Painel do Dust

1. No Dust, acesse Spaces > Connections, clique em Add Connections e selecione Snowflake.
2. Escolha Key Pair Authentication (ou Username & Password).
3. Preencha os parâmetros de conexão:
   • Account Identifier: Identificador da conta (por exemplo, xy12345.us-east-1 ou organizacao-conta).
   • Role: dust_role.
   • Warehouse: dust_warehouse.
   • Username: dust_user.
   • Private Key: Cole o conteúdo integral do arquivo PEM da chave privada, incluindo cabeçalho e rodapé.
4. Na listagem de metadados, selecione os bancos de dados, schemas e tabelas que ficarão acessíveis aos agentes.

Opção 2: Conectando o Google BigQuery ao Dust

O Google BigQuery integra-se ao Dust por meio de chaves de contas de serviço do Google Cloud Platform (GCP) IAM, oferecendo isolamento por região e importação automática de descrições de colunas.

1. Configuração da Conta de Serviço no GCP

1. No Google Cloud Console, vá para IAM e administração > Contas de serviço.
2. Clique em Criar conta de serviço e atribua o nome dust-warehouse-sa.
3. Adicione os dois papéis mínimos necessários de IAM:
   • roles/bigquery.user: Concede permissão para criar tarefas de consulta (Query Jobs), listar conjuntos de dados e consumir cota de processamento.
   • roles/bigquery.dataViewer: Permite inspecionar a estrutura dos esquemas e ler os registros das tabelas.
4. Acesse a aba Chaves da conta de serviço recém-criada.
5. Clique em Adicionar chave > Criar nova chave > JSON.
6. Salve o arquivo de credenciais baixado em local seguro.

2. Registro do BigQuery no Dust

1. No Dust, navegue até Spaces > Connections > Add Connections e escolha BigQuery.
2. Cole todo o conteúdo do arquivo JSON da conta de serviço.
3. Selecionar a Localização do BigQuery (Location): O BigQuery impede consultas cruzadas entre diferentes regiões (por exemplo, fazer join entre um dataset na EU e outro nos US). É necessário selecionar a região exata (como US, EU ou uma região específica), e todos os datasets vinculados devem residir nessa mesma localização.
4. Escolha os conjuntos de dados e tabelas a serem disponibilizados.
5. Ativar “Use BigQuery descriptions”: Ao marcar essa opção, o Dust importa automaticamente as descrições de tabelas e comentários de colunas configurados no BigQuery, enriquecendo o contexto do agente sem necessidade de documentação duplicada nos prompts.

Comparativo: Snowflake Connection vs. Snowflake Tool

Ao planejar a integração com o Snowflake, avalie as diferenças entre os dois métodos disponíveis:

Configuração e Engenharia de Prompts para Agentes Analíticos

Com as tabelas do Snowflake ou BigQuery disponíveis no Space, a equipe pode estruturar agentes especializados (como @assistente-comercial ou @analista-financeiro).

1. Adição da Ferramenta Query Tables

1. Abra o configurador do agente em Agent Builder > Instructions & Tools.
2. Em Action & Data sources, clique em Add a tool e selecione Query Tables.
3. Selecione as tabelas desejadas (por exemplo, marts.fct_daily_orders).

2. Definição de Regras de Join e Lógica de Negócio

Embora os modelos compreendam os tipos de dados do esquema, diretrizes claras nos prompts são fundamentais para evitar ambiguidades estatísticas:

Você é um agente analítico responsável por responder a dúvidas sobre métricas corporativas. Você tem acesso às seguintes tabelas do data warehouse:
- fct_orders: Registro de transações financeiras, volumes e status do pedido.
- dim_customers: Perfil cadastral, categoria do cliente e data de adesão.

Diretrizes para elaboração de consultas SQL:
1. Ao cruzar tabelas, utilize sempre dim_customers.customer_id = fct_orders.customer_id.
2. Para cálculos de faturamento realizado, filtre obrigatoriamente por order_status = 'COMPLETED', exceto quando solicitado o pipeline total.
3. Evite SELECT *; liste explicitamente as colunas necessárias para responder à pergunta.
4. Para agrupamentos temporais, converta carimbos de data/hora UTC para meses ou trimestres consolidados.
5. Ao apresentar tabelas numéricas, adicione uma conclusão executiva em linguagem natural destacando os principais fatores observados.

3. Auditoria e Rastreabilidade com Tools Inspection

Sempre que uma resposta for gerada, qualquer usuário pode clicar em Tools inspection no cartão da mensagem para verificar a sintaxe SQL real executada, o tempo de resposta e os registros brutos retornados pelo banco de dados, assegurando confiabilidade total aos números apresentados.

Recomendações Práticas para Equipes de Dados

1. Priorize Camadas Tratadas e Data Marts (Gold): Conecte o Dust a tabelas dimensionais consolidadas (modeladas via dbt, por exemplo) em vez de tabelas brutas de ingestão. Esquemas limpos elevam exponencialmente o índice de acerto do SQL.
2. Documente Colunas Diretamente no Data Warehouse: Utilize comentários DDL (COMMENT) no Snowflake e no BigQuery. A importação automática dessas descrições poupa tempo e garante que termos técnicos (como CAC, LTV, MRR) sejam interpretados corretamente.
3. Gerencie Custos de Computação:
   • No Snowflake, use o tamanho XSMALL com AUTO_SUSPEND configurado para até 300 segundos.
   • No BigQuery, configure limites de bytes processados por consulta na conta de serviço para evitar varreduras acidentais de tabelas volumosas.
4. Una Análise Quantitativa e Qualitativa: Um agente pode utilizar a ferramenta Query Tables em conjunto com a ferramenta Search Data Source (RAG sobre documentos). Dessa forma, a IA consegue cruzar os números consolidados do BigQuery com relatórios no Notion ou Google Drive para explicar as causas de variações comerciais.

Referências

• Snowflake - Multiplayer AI
• BigQuery - Multiplayer AI
• Table queries - Multiplayer AI
• Snowflake - Multiplayer AI
• AI Data Analytics Agents: Turn Data Into Business Decisions | Dust
• Integrations | Dust AI Agents