Pergunte aos dados: SQL + proveniência

Selo de estado: Preview (teto atual do produto) · Curso ACD-100 — Fundamentos Ingestia · Aula 9 de 10 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai formular pergunta com período/recorte/medida e ler proveniência — e tratar uma recusa da IA como resposta correta, não como falha.

Vídeo#

Identificador no manifesto: acd-100-09-primeira-pergunta-ia · duração-alvo 6 min · tela do produto: /query.

Roteiro de gravação (5 capítulos):

Conteúdo#

O que a IA faz — e o que não faz

A IA da ingestia.io traduz linguagem natural em SQL sobre o seu datamart, responde com citações e proveniência e sabe recusar quando não tem base. Ela descreve o que os dados mostram; não afirma causa ("X causou Y") e recusa quando tentam forçar. Trate-a como um assistente que propõe — você revisa e confirma.

Quem pode, e o que custa

• Usar a IA exige papel admin/owner (ação recursos de IA) e roda atrás das chaves de desligamento de consulta em linguagem natural / insights de IA. Se a chave estiver ativa, o produto responde "Recurso de IA indisponível".
• É uma ação cara: bloqueada em inadimplência (402). Não é preciso habilitar IA para consultar BI.
• Cada pergunta consome orçamento de IA (egress para o provedor) e, quando você executa a consulta, BigQuery. O orçamento usa um ledger atômico (reserva → liquidação): você nunca estoura em silêncio; ao atingir o teto, o recurso recusa (fail-closed). O teto é um valor em reais por mês por workspace (padrão R$ 50) e há rate limit. BRL faturado = projeção.
• A IA respeita RLS/ABAC e a permissão Ver dados PII (viewPII): não devolve linha que a pessoa não poderia ver.

Como aparece no produto

Em IA → Consultas com IA (/query):

1. Escolha o escopo: uma tabela Gold ou o modelo semântico (recomendado — a IA fica "aterrada" no modelo certificado, e é daí que vêm respostas confiáveis).
2. Escreva a pergunta em português.
3. A IA propõe o SQL (com parâmetros nomeados, anti-injeção), estima o custo e mostra as citações das fontes usadas. Gerar não executa nada: executar é uma ação separada, que depende da sua permissão e de você revisar o SQL.

A resposta vem em três partes: SQL somente-leitura (visível para auditoria — revise nomes de coluna e tabela antes de confiar; há auto-correção com um retry usando o erro real do BigQuery, mas não é garantia), explicação com custo estimado e proveniência (quais tabelas, colunas e medidas sustentam o número).

Como perguntar bem

Os cinco princípios:

1. Seja específico sobre métrica e recorte: qual número, por qual dimensão, em qual período.
2. Use os nomes do seu modelo: "receita", "categoria", "filial".
3. Uma pergunta por vez. Perguntas compostas confundem; quebre em passos.
4. Peça o período explicitamente: "último trimestre", "2026", "últimos 30 dias".
5. Não peça causa.

Se a pergunta for ambígua e houver modelo semântico publicado, a IA recusa antes de gastar token e lista as opções ("você quis dizer Receita bruta ou Receita líquida?"). Escolha e refaça — é mais barato e mais preciso.

Quando a IA recusa (e por que é bom)

Recusa não é falha — é honestidade. As três recusas comuns:

• Ambiguidade → escolha entre as opções e refaça.
• Fora do contexto (fora_do_contexto) → a pergunta não toca nenhum termo do modelo ou do painel; reformule com os nomes certos.
• Sem evidência (sem_evidencia) → os dados não sustentam a afirmação; agregue no SQL ou mude a pergunta.

O Q&A do dashboard (a pergunta feita de dentro de um painel) responde só com base no snapshot já materializado, cada frase com citação verificável. Por isso ele não responde "agora" nem previsão, e sobre uma amostra a IA é proibida de afirmar total, soma, "maior" ou "todos" — para o total exato, use o text-to-SQL.

Segurança

• Anti-injeção de prompt e de SQL (parâmetros nomeados).
• Egress controlado: o que sai para o provedor de IA é mapeado; onde exige opt-in, egress fica desligado por padrão.
• Não cole segredos nem PII na pergunta. O texto vai para o provedor — pergunte sobre estrutura e números, não sobre pessoas.

Exemplo: a Comércio Aurora

Ana pergunta: "Qual filial mais vendeu em julho?". A IA propõe o SQL sobre aurora_gold.vendas_por_filial, mostra o custo estimado e cita a tabela e o período — e a tela avisa que nada foi executado no datalake. Ana revisa o SQL e clica em executar; aí sim a consulta roda, com maximumBytesBilled como teto, e responde "Campinas, R$ 128 mil". Se ela tivesse perguntado "quais os melhores?", teria recebido um pedido de precisão — "melhor em quê?" — antes de qualquer custo.

Erros comuns

Faça você mesmo#

No workspace de treino Aurora Varejo, como admin ou dona:

1. Confirme o seu papel (admin/owner) e abra IA → Consultas com IA (/query).
2. Escolha o escopo: o modelo semântico (recomendado) ou a tabela aurora_gold.vendas.
3. Pergunte de propósito mal: "me mostra tudo". Anote o que a IA fez (recusa ou pedido de precisão) e quanto custou (nada, se recusou antes de gerar).
4. Agora pergunte bem: "receita por categoria no último mês".
5. Leia a resposta em três partes: o SQL (somente leitura, parâmetros nomeados), a explicação com custo estimado e a proveniência. Confira se a coluna de receita e a de categoria são as que você esperava.
6. Refaça com um recorte: "receita por categoria no último mês só na filial Campinas". Compare o SQL: o filtro apareceu?
7. Escreva uma pergunta que a IA deve recusar ("por que as vendas caíram?") e confirme a recusa.

Você terminou quando obteve uma resposta com SQL visível e proveniência para a pergunta boa, uma recusa ou pedido de precisão para as perguntas ruins, e consegue apontar na proveniência a tabela e a medida usadas.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• primeiros-passos/primeira-pergunta-ia
• ai/boas-praticas-de-prompt

Capacidades ensinadas#

C13.1 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".