Pergunta → SQL → proveniência → custo

Selo de estado: Preview (teto atual do produto) · Curso ACD-410 — Ingestia AI: perguntar aos dados com proveniência · Aula 3 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai executar e auditar 3 perguntas — lendo a proposta em quatro partes (tabelas, SQL, explicação, custo estimado) e fechando o rastro de cada uma em /auditoria.

Vídeo#

Identificador no manifesto: acd-410-03-text-to-sql-na-pratica · duração-alvo 9 min · tela do produto: /query.

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

Conteúdo#

O ciclo de uma pergunta

Uma pergunta em linguagem natural percorre sempre o mesmo caminho: pergunta → SQL proposto → proveniência → custo. O detalhe que muda tudo é que o caminho termina numa proposta, não num número. O contrato está escrito no topo da tela: a IA propõe o SQL e explica o que ele faz; executar é uma ação separada; gerar não executa nada.

Determinístico × LLM dentro do text-to-SQL

Esta é a capacidade onde a divisão de trabalho fica mais visível:

Resumo: o LLM redige, o código delimita e a conta vem de uma execução seca real.

Como a proposta aparece em /query

Depois de "Gerar SQL", o cartão "Consulta proposta" abre com o aviso "revise o SQL e a previsão de custo antes de salvar. Nada foi executado no seu datalake" e traz, em ordem:

1. Tabelas — as tabelas que sustentam a consulta, em selos. É a sua proveniência física: se aparecer algo que você não esperava, pare aqui.
2. SQL — somente-leitura, visível para auditoria. Confira nome de coluna e de tabela antes de confiar. Há uma autocorreção (uma nova tentativa com o erro real do BigQuery), mas ela não é garantia.
3. Explicação — em português, o que a consulta faz. Ela descreve a consulta; não afirma causa nos seus dados.
4. Custo estimado por execução — valor em reais, bytes processados e o valor em dólares, com selo de estimativa.
5. "Onde este resultado está" — quatro etapas (processamento, qualidade, materialização, atualização do painel). Nenhuma é inferida da anterior: logo depois de gerar, todas aparecem como não iniciadas. Gerar SQL não mexeu em painel algum.
6. Salvar como datamart — o passo humano. A nota de rodapé repete: salvar não executa a consulta nem atualiza nenhum painel.

Antes de gerar, a tela também mostra o limite de uso de IA deste mês e quanto já foi usado — o teto padrão por workspace é de R$ 50/mês, e quando ele estoura a chamada é recusada com mensagem clara, nunca em silêncio.

Proveniência completa em /auditoria

A tela de auditoria (área do dono) é onde a pergunta deixa de ser uma tela e passa a ser um registro. Cada chamada com LLM grava:

• ai.reserva — antes da chamada, com estimativa conservadora;
• ai.usage — o custo real em reais, com o resumo de envio externo (quantas tabelas do schema saíram e zero linhas);
• ai.reserva_liquidada — fecha o par, inclusive quando a chamada falha;
• ai.blocked — quando o teto barrou a pergunta (custo zero), para o admin ver a demanda represada.

Os três primeiros compartilham um opId, e é ele que permite dizer "esta resposta custou isso". A tabela de auditoria mostra quem fez, quando, a ação, o SQL e o custo em reais.

Exemplo: a Aurora Varejo

Ana abre /query com o escopo no modelo semântico publicado e pergunta:

"receita por categoria nos últimos 30 dias"

Resposta esperada: um SQL somente-leitura agrupando por categoria sobre aurora_gold.vendas, com o período como parâmetro nomeado (não concatenado no texto); a explicação dizendo que soma a medida Receita por categoria no intervalo pedido; o selo de tabela mostrando aurora_gold.vendas; e um custo estimado na casa dos centavos, com os bytes processados. As quatro etapas de "onde este resultado está" aparecem não iniciadas.

Ana refaz com recorte: "receita por categoria nos últimos 30 dias só na filial Campinas". O SQL esperado ganha um filtro por filial — se não ganhou, o escopo ou o modelo estão errados, e é isso que a proveniência denuncia.

Por fim ela pergunta "me mostra tudo". A resposta esperada é um pedido de precisão ou uma recusa: sem métrica nem recorte não há consulta útil. Se a recusa vier antes da chamada ao modelo, o custo é zero.

Erros comuns

O que o text-to-SQL NÃO faz

Não escreve nem altera dado (só SELECT). Não executa por você. Não garante que o SQL esteja certo — por isso o SQL fica visível. Não afirma causa. E não responde o que não existe no seu catálogo: comparação com "o mercado" ou previsão de dezembro não estão nos seus dados. O estado é Preview, com a qualidade da IA em produção NOT_MEASURED e a avaliação humana pendente: a proveniência existe justamente para você conferir.

Faça você mesmo#

No workspace de treino Aurora Varejo, como admin ou dona. Atenção: este exercício consome o orçamento de IA do workspace — são três perguntas, cada uma na casa dos centavos, e o valor aparece em /auditoria. Confira o limite do mês na própria tela antes de começar.

1. Abra /query, escolha o escopo modelo semântico (recomendado) ou a tabela aurora_gold.vendas, e confira o limite de IA do mês mostrado na tela.
2. Pergunta 1: "receita por categoria nos últimos 30 dias". Leia a proposta na ordem: Tabelas → SQL → Explicação → Custo estimado. Anote os bytes e o valor em reais.
3. Confira o bloco "Onde este resultado está" e escreva com suas palavras por que nenhuma das quatro etapas está concluída.
4. Pergunta 2: a mesma, com o recorte "só na filial Campinas". Compare os dois SQL e confirme que o filtro apareece — e que o período continua como parâmetro nomeado.
5. Pergunta 3: "me mostra tudo". Registre o que aconteceu (recusa, pedido de precisão) e se houve custo.
6. Salve a pergunta 2 como datamart e confirme, na mensagem da tela, que salvar não executou nada.
7. Abra /auditoria e localize as suas três perguntas. Para cada uma, feche o par ai.reserva ↔ ai.reserva_liquidada pelo opId e anote o custo real em ai.usage.

Você terminou quando tiver três perguntas auditadas, com o custo real de cada uma, e conseguir apontar — para a pergunta 2 — a tabela e a medida que sustentam o número.

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#

• ai/text-to-sql
• primeiros-passos/primeira-pergunta-ia
• ai/privacidade-egress-orcamento

Capacidades ensinadas#

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