Pular para o conteúdo principal

Primeiros passos

Este roteiro leva da conta recém-criada até a primeira consulta executada no seu banco.

1. Entre no painel​

Acesse app.datafala.com.br/login com o e-mail e a senha que o time do Datafala enviou.

2. Configure a LLM​

Em Configurações, na seção Provedor de LLM, escolha o provedor e o modelo, cole a chave da sua conta no provedor e clique em Testar antes de salvar. A chave é guardada cifrada e só é decifrada no momento da chamada.

Provedores aceitos: OpenAI, Anthropic, Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter e Cohere.

3. Cadastre o schema​

Na tela Schema, escolha o dialeto (PostgreSQL, MySQL ou Firebird) e cole o DDL das tabelas que a API pode usar. Basta o CREATE TABLE com colunas e chaves estrangeiras; dados nunca são enviados.

Como gerar o DDL sem dados:

# PostgreSQL
pg_dump --schema-only --no-owner --no-privileges \
  -t public.pedidos -t public.clientes -t public.produtos \
  "postgresql://usuario@host/banco" > schema.sql

# MySQL
mysqldump --no-data --skip-comments banco pedidos clientes produtos > schema.sql

No Firebird (2.5 ou mais novo), use o isql que vem com o servidor. O -x extrai só os metadados de todas as tabelas, sem dados:

# Linux / macOS
isql -x -user SYSDBA -ch UTF8 \
  localhost:/dados/banco.fdb -o schema.sql

# Windows
isql.exe -x -user SYSDBA -ch UTF8 ^
  localhost:C:\Dados\BANCO.FDB -o schema.sql

O isql pedirá a senha no terminal. Não a inclua no comando nem no arquivo de metadados.

Prefere uma ferramenta gráfica? No FlameRobin, clique com o botão direito no banco e use Extract metadata. No IBExpert, use Tools → Extract Metadata e marque só os metadados, sem dados.

O banco precisa usar SQL dialect 3, inclusive no Firebird 2.5 (confira com SHOW SQL DIALECT; no isql). DDL com SQL dialect 1 é recusado. O isql não filtra tabelas: cole o arquivo inteiro e oculte no painel o que a API não deve usar. Tabelas de sistema e procedures, triggers, índices, generators e permissões que vierem no arquivo são ignorados.

Depois de importar, descreva tabelas e colunas com nomes pouco óbvios e oculte o que a API não deve usar (por exemplo colunas de CPF ou senha). Tabelas e colunas ocultas não entram no prompt e são recusadas pelo SQL Guard.

4. Escreva o contexto e alguns exemplos​

  • Contexto: regras de negócio e glossário em texto livre ("venda cancelada tem status = 'C'", "faturamento = soma de valor_total das vendas não canceladas").
  • Exemplos: pares pergunta → SQL que mostram o jeito certo de consultar o seu banco. Cada exemplo passa pelo SQL Guard ao ser salvo.

Use o Playground do painel para testar perguntas antes de integrar.

5. Crie uma API key​

Em Credenciais, crie uma chave para a integração. Ela tem o formato tsk_<prefixo>_<segredo> e aparece uma única vez. Guarde-a no cofre de segredos do seu servidor. Veja Autenticação.

6. Faça a primeira pergunta​

export DATAFALA_API_KEY="tsk_1a2b3c4d_..."

curl -sS -X POST "https://app.datafala.com.br/v1/ask" \
  -H "Authorization: Bearer $DATAFALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quantos pedidos foram feitos ontem?",
    "end_user": "5f0c3a9e7b1d4e2f8a6c0b9d3e7f1a2c4b5d6e7f8091a2b3c4d5e6f708192a3b"
  }'

Resposta:

{
  "sql": "SELECT count(*) AS total FROM public.pedidos WHERE criado_em >= %(start)s AND criado_em < %(end)s",
  "params": { "start": "2026-10-22", "end": "2026-10-23" },
  "dialect": "postgres",
  "tables": ["public.pedidos"],
  "explanation": "Conta os pedidos criados ontem.",
  "locale": "pt-BR",
  "request_id": "req_0f3c9a7d2b6e4f1a8c5d0e9b7a6f3c21"
}

O campo end_user identifica, de forma opaca, a pessoa que fez a pergunta. Veja Identificador do usuário final para gerá-lo corretamente.

7. Execute no seu banco​

rows = readonly_conn.execute(answer["sql"], answer["params"]).fetchall()

Leia Executar o SQL antes de ir para produção: ele explica o usuário somente leitura, o tempo máximo por consulta e como converter os placeholders para drivers de outras linguagens.