# Text-to-SurrealQL: da pergunta à consulta no banco

> **Resposta Direta:** A Aula 7 de 11 ("Text-to-SurrealQL: da pergunta à consulta no banco"), parte do módulo "Agentes e contexto" do curso gratuito "SurrealDB para engenheiros de IA: RAG e agentes" na Escola de Aplicativos (ministrado por Mauro Mequelussi), ensina na prática: Veja como implementar Text-to-SurrealQL sem depender de schemas estáticos que envelhecem no prompt. O banco de dados gera dinamicamente seu schema, fornece valores reais para evitar alucinações e seleciona exemplos relevantes via busca vetorial. Aprenda também a diagnosticar falhas silenciosas e a proteger o banco com roles de leitura, EXPLAIN e limites de TIMEOUT.

## Ficha Técnica da Aula

- **Curso:** [SurrealDB para engenheiros de IA: RAG e agentes](https://www.escoladeaplicativos.com.br/cursos/surrealdb-para-engenheiros-de-ia)
- **Escola:** Escola de Aplicativos (https://www.escoladeaplicativos.com.br)
- **Instrutor:** Mauro Mequelussi
- **Módulo 3 de 4:** Agentes e contexto
- **Posição na trilha:** Aula 7 de 11
- **Duração da videoaula:** 8 min
- **Nível:** Intermediário
- **Idioma:** Português (PT-BR)
- **Custo:** 100% Gratuito (R$ 0)
- **Certificado:** Certificado gratuito verificável incluso ao concluir o curso
- **Acesso ao vídeo:** Resumo técnico aberto; videoaula em HD liberada mediante cadastro gratuito
- **URL canônica:** https://www.escoladeaplicativos.com.br/cursos/surrealdb-para-engenheiros-de-ia/text-to-surrealql-da-pergunta-a-consulta-no-banco

## O que você vai aprender

- Como usar comandos de introspecção como INFO FOR DB e INFO FOR TABLE para montar prompts dinâmicos.
- Por que o uso de grafos e setas no SurrealDB evita erros comuns de JOIN cometidos por LLMs.
- Como injetar valores reais de baixa cardinalidade para evitar que o modelo invente filtros errados.
- A seleção de exemplos dinâmicos (few-shot) por significado usando busca vetorial.
- Como blindar o banco de dados contra operações destrutivas usando papéis somente leitura, EXPLAIN e TIMEOUT.

## Pontos-chave da Aula

- Schemas estáticos colados em prompts inevitavelmente ficam desatualizados e quebram a IA.
- Falhas silenciosas retornam listas vazias sem erro e são as mais difíceis de detectar.
- Regras no prompt são sugestões; permissões e travas no banco de dados são garantias reais.
- Feedbacks humanos aprovados podem alimentar a tabela de exemplos automaticamente.

## Capítulos e Tópicos da Videoaula

- **[00:00] O perigo das consultas silenciosas geradas por IA** — Uma consulta gerada por IA pode rodar perfeitamente sem erros e ainda assim retornar resultados errados ou vazios.
- **[00:26] A necessidade de consultas ad hoc pelo agente** — Quando o usuário faz perguntas não previstas, o agente precisa criar a consulta por conta própria.
- **[00:46] Por que o banco de dados deve gerar o próprio prompt** — Manter schemas manuais em prompts gera desatualização; o banco deve inspecionar sua estrutura em tempo real.
- **[01:40] Escrevendo schema com comentários para orientar o modelo** — Usar comentários de tabela e campo serve como documentação de regras de negócio para a IA entender o modelo de dados.
- **[03:08] Extraindo metadados e valores reais do banco** — Comandos de introspecção e listas de valores reais fecham o contexto para a IA não alucinar termos de filtro.
- **[04:10] Few-shot dinâmico com busca vetorial e regras de prompt** — Recuperar exemplos semanticamente próximos por similaridade vetorial otimiza o contexto e o custo do prompt.
- **[05:33] As três formas de falha do Text-to-SurrealQL** — Entenda a diferença entre erros ruidosos de sintaxe e falhas silenciosas de campos inexistentes ou valores errados.
- **[06:26] Blindagem de segurança: permissões, explain e timeout** — Restrinja o agente com papéis somente-leitura, análise de custo antes da execução e limites rígidos de tempo.
- **[07:08] Feedback loop com exemplos verificados e produção** — Consultas validadas viram novos exemplos na base vetorial, fechando um ciclo contínuo de aprendizado com segurança.

## Destaques Práticos

- **[00:46] Por que o banco deve montar o prompt do seu agente**: Schemas manuais no prompt sempre quebram; descubra como deixar o banco gerar o contexto exato da consulta.
- **[05:33] Os 3 erros clássicos ao deixar a IA consultar o banco**: Apenas um erro avisa quando quebra; veja como se proteger dos dois erros que falham em silêncio.
- **[06:26] 3 travas de segurança que a IA não consegue burlar**: Nunca confie em regras de texto: use papéis de leitura, explain e timeout para blindar seu banco.

## Conceitos e Tecnologias Abordados

- **Tópicos:** Text-to-SQL / Text-to-SurrealQL, Geração dinâmica de schema, Few-shot dinâmico com embeddings, Prevenção de falhas silenciosas, Segurança e permissões de agentes, Otimização de prompts
- **Ferramentas e Entidades:** SurrealDB, SurrealQL, PostgreSQL, Supabase

## Documentação e Referências Oficiais

- [Documentação oficial: comando INFO no SurrealDB](https://surrealdb.com/docs/surrealql/statements/info)
- [Documentação oficial: instrução DEFINE TABLE e comentários](https://surrealdb.com/docs/surrealql/statements/define/table)
- [Documentação oficial: autenticação e papéis de acesso](https://surrealdb.com/docs/surrealql/statements/define/access)

## Perguntas Frequentes (FAQ)

### O que é ensinado na Aula 7 (Text-to-SurrealQL: da pergunta à consulta no banco) do curso SurrealDB para engenheiros de IA: RAG e agentes?

Nesta aula do módulo "Agentes e contexto" na Escola de Aplicativos, você aprende de forma prática: Como usar comandos de introspecção como INFO FOR DB e INFO FOR TABLE para montar prompts dinâmicos.; Por que o uso de grafos e setas no SurrealDB evita erros comuns de JOIN cometidos por LLMs.; Como injetar valores reais de baixa cardinalidade para evitar que o modelo invente filtros errados.; A seleção de exemplos dinâmicos (few-shot) por significado usando busca vetorial..

### Como assistir ao vídeo completo da aula "Text-to-SurrealQL: da pergunta à consulta no banco" gratuitamente?

O resumo técnico estruturado desta aula é público e gratuito. Para assistir à videoaula completa em HD, basta entrar ou criar sua conta 100% gratuita na Escola de Aplicativos — o cadastro leva segundos e libera todas as 11 aulas do curso "SurrealDB para engenheiros de IA: RAG e agentes", controle de progresso, Tutor IA e emissão de certificado gratuito.

### Quais tecnologias e conceitos são abordados em "Text-to-SurrealQL: da pergunta à consulta no banco"?

A aula cobre diretamente os seguintes tópicos técnicos aplicados em produção: Text-to-SQL / Text-to-SurrealQL, Geração dinâmica de schema, Few-shot dinâmico com embeddings, Prevenção de falhas silenciosas, Segurança e permissões de agentes, Otimização de prompts.

### O curso "SurrealDB para engenheiros de IA: RAG e agentes" oferece certificado gratuito?

Sim. Ao assistir às 11 aulas do curso gratuito "SurrealDB para engenheiros de IA: RAG e agentes" na Área de Membros da Escola de Aplicativos, você emite gratuitamente um certificado digital em português com código de verificação pública.

## Como assistir à videoaula completa gratuitamente

Crie sua conta gratuita em segundos em https://www.escoladeaplicativos.com.br/login?redirect=%2Fm%2Fcursos%2Fsurrealdb-para-engenheiros-de-ia%2Faula%2Ftext-to-surrealql-da-pergunta-a-consulta-no-banco para assistir ao vídeo completo desta aula em HD na Área de Membros da Escola de Aplicativos, com progresso salvo, Tutor IA e certificado gratuito verificável.

## Navegação do Curso

- **Aula anterior:** [Aula 6: Memória persistente para agentes de IA no SurrealDB](https://www.escoladeaplicativos.com.br/cursos/surrealdb-para-engenheiros-de-ia/memoria-persistente-para-agentes-de-ia-no-surrealdb)
- **Próxima aula:** [Aula 8: Múltiplas fontes e contexto para agentes de IA](https://www.escoladeaplicativos.com.br/cursos/surrealdb-para-engenheiros-de-ia/multiplas-fontes-e-contexto-para-agentes-de-ia)