Saltar al contenido principal

Primeros pasos

Este recorrido lleva desde la cuenta recién creada hasta la primera consulta ejecutada en tu base de datos.

1. Entra al panel​

Abre app.datafala.com.br/login con el correo y la contraseña que te envió el equipo de Datafala.

2. Configura el LLM​

En Configuración, en la sección Proveedor de LLM, elige el proveedor y el modelo, pega la clave de tu cuenta en el proveedor y haz clic en Probar antes de guardar. La clave se guarda cifrada y solo se descifra en el momento de la llamada.

Proveedores aceptados: OpenAI, Anthropic, Gemini, Mistral, Groq, DeepSeek, xAI, OpenRouter y Cohere.

3. Registra el schema​

En la pantalla Schema, elige el dialecto (PostgreSQL, MySQL o Firebird) y pega el DDL de las tablas que la API puede usar. Basta el CREATE TABLE con columnas y claves foráneas; los datos nunca se envían.

Cómo generar el DDL sin datos:

# 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

En Firebird (2.5 o más reciente), usa el isql que viene con el servidor. La opción -x extrae solo los metadatos de todas las tablas, sin datos:

# 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

isql pedirá la contraseña en la terminal. No la incluyas en el comando ni en el archivo de metadatos.

¿Prefieres una herramienta gráfica? En FlameRobin, haz clic derecho en la base de datos y usa Extract metadata. En IBExpert, usa Tools → Extract Metadata y marca solo los metadatos, sin datos.

La base de datos debe usar SQL dialect 3, incluso en Firebird 2.5 (verifícalo con SHOW SQL DIALECT; en isql). El DDL con SQL dialect 1 se rechaza. isql no filtra tablas: pega el archivo completo y oculta en el panel lo que la API no debe usar. Las tablas del sistema y los procedimientos, triggers, índices, generadores y permisos que vengan en el archivo se ignoran.

Después de importar, describe tablas y columnas con nombres poco obvios y oculta lo que la API no debe usar (por ejemplo columnas de CPF o de contraseña). Las tablas y columnas ocultas no entran en el prompt y son rechazadas por el SQL Guard.

4. Escribe el contexto y algunos ejemplos​

  • Contexto: reglas de negocio y glosario en texto libre ("una venta cancelada tiene status = 'C'", "facturación = suma de valor_total de las ventas no canceladas").
  • Ejemplos: pares pregunta → SQL que muestran la forma correcta de consultar tu base de datos. Cada ejemplo pasa por el SQL Guard al guardarse.

Usa el Playground del panel para probar preguntas antes de integrar.

5. Crea una API key​

En Credenciales, crea una clave para la integración. Tiene el formato tsk_<prefijo>_<secreto> y se muestra una sola vez. Guárdala en el almacén de secretos de tu servidor. Consulta Autenticación.

6. Haz la primera pregunta​

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": "¿Cuántos pedidos se hicieron ayer?",
    "end_user": "5f0c3a9e7b1d4e2f8a6c0b9d3e7f1a2c4b5d6e7f8091a2b3c4d5e6f708192a3b"
  }'

Respuesta:

{
  "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": "Cuenta los pedidos creados ayer.",
  "locale": "es",
  "request_id": "req_0f3c9a7d2b6e4f1a8c5d0e9b7a6f3c21"
}

El campo end_user identifica de forma opaca a la persona que hizo la pregunta. Consulta Identificador del usuario final para generarlo correctamente.

7. Ejecuta en tu base de datos​

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

Lee Ejecutar el SQL antes de pasar a producción: explica el usuario de solo lectura, el tiempo máximo por consulta y cómo convertir los placeholders para drivers de otros lenguajes.