Tablas de datos

Objetivo

Guarda tus datos de negocio estructurados (clientes, pedidos, inventario, citas y más) en tablas que tus agentes de IA pueden leer y sobre las que pueden responder preguntas. Puedes crear una tabla a mano, partir de una plantilla predefinida o describirla y dejar que la IA la diseñe. Una vez asignada a un agente, este puede responder preguntas sobre ella en conversaciones de chat, email o voz.

Acceso

Menú lateral -> Data Tables

Ruta(s): /app/\{tenant\}/sql-tables (lista de tablas) y /app/\{tenant\}/sql-tables/\{id\} (detalle de la tabla).

La lista también muestra cuatro tarjetas de estadísticas (Total Tables, Total Rows, Agents Using y un medidor Tables usage de tu plan), un acceso directo Docs a esta página y un panel Recent Activity con las últimas inserciones y actualizaciones de tus tablas.

Roles

• owner, admin — acceso completo: crear, editar, duplicar y eliminar tablas; agregar, editar, importar y eliminar filas; ejecutar consultas en lenguaje natural; gestionar webhooks.
• El resto de miembros del espacio de trabajo pueden ver las filas de una tabla y descargar su exportación CSV (solo lectura).

Crear y editar tablas, modificar filas, importar datos, ejecutar consultas en lenguaje natural y gestionar webhooks están restringidos a owners y admins.

Requisitos previos

• Crear una tabla (por cualquiera de los tres caminos) requiere un email verificado y una suscripción activa.
• Para responder preguntas en una conversación, un agente de IA debe tener el acceso a datos habilitado y esta tabla asignada (ver Asignar tablas a agentes).
• Las funciones Create with AI y Natural Language Query usan tu proveedor de IA configurado.
• Una tabla debe estar Active e incluir la operación SELECT para poder consultarse.

Límites por plan

Notas:

• El límite de filas aplica tanto por tabla como al total combinado de todas tus tablas. Las importaciones CSV también cuentan.
• "Consultas por minuto" es el límite de frecuencia de las consultas en lenguaje natural.
• El medidor de plan en la lista solo cuenta las tablas activas. Una tabla suspendida conserva sus datos pero no cuenta para tu límite de tablas.

---

Crear una tabla

El encabezado de la lista ofrece tres formas de crear una tabla.

Create Table (manual)

1. Pulsa Create Table.
2. Completa el formulario.
3. Pulsa Create Table.

Campos del formulario

Cada campo del esquema tiene un field name, una label amigable opcional, un type y una casilla Optional. Marca un campo como Optional para permitir que quede vacío; de lo contrario será obligatorio al agregar una fila. En Allowed Operations, SELECT viene preseleccionado.

Tipos de campo disponibles

Use a template

Pulsa Use a template, elige una tarjeta de plantilla, revisa sus campos y ajusta el nombre visible, el nombre de tabla y la descripción (vienen prellenados; el nombre interno se sugiere a partir del nombre visible hasta que lo edites tú), y pulsa Create table. Plantillas disponibles:

Notas:

• Properties es de solo lectura (SELECT) a propósito: los agentes pueden buscar propiedades pero nunca modificarlas. Los listados se cargan y editan desde las pantallas de la tabla y la importación CSV.
• La lista de campos del selector es una vista previa de solo lectura. Para cambiar los campos de una plantilla, crea la tabla primero y usa Edit Table.
• Una tabla creada desde plantilla cuenta para el límite de tablas de tu plan igual que los otros dos caminos.

Create with AI

1. Pulsa Create with AI.
2. Describe los datos que quieres guardar, por ejemplo: "Necesito una tabla para tarifas de envío con origen, destino, rangos de peso y precios."
3. Revisa las tarjetas de esquema sugeridas. Puedes editar campos y tipos, o enviar un mensaje de seguimiento para refinarlas.
4. Pulsa Create en una tarjeta, o Create All cuando se sugiera más de una tabla.

---

Ver y gestionar datos

Ruta: /app/\{tenant\}/sql-tables/\{id\}

Abre una tabla desde la lista (View Data) para ver sus filas y las acciones disponibles en el encabezado.

Acciones del encabezado

El encabezado también muestra el número de filas, las operaciones permitidas de la tabla y una vista Schema desplegable con cada campo y su tipo.

Explorador de filas

Agregar o editar una fila

El formulario genera un campo por cada columna del esquema. Comportamiento por tipo:

• NUMBER: acepta decimales (ej: 99.99).
• BOOLEAN: selector Yes / No.
• DATE: selector de fecha.
• TIMESTAMP: selector de fecha y hora.

Los campos marcados como Optional pueden quedar vacíos. Editar una fila guarda tus cambios; eliminar una fila es permanente.

---

Import CSV

Importa filas desde una exportación de hoja de cálculo en cuatro pasos: Upload, Map columns, Preview, Import complete.

1. Upload — elige un archivo .csv. Se requiere una fila de encabezado. Tamaño máximo 5 MB; hasta 50,000 filas por archivo.
2. Map columns — el asistente empareja automáticamente las columnas de tu archivo con los campos de la tabla. Ajusta cualquier emparejamiento o marca un campo como Don't import. Las columnas que no asignes se ignoran. Un campo obligatorio sin emparejar hace que todas las filas se omitan, así que asigna todos los campos obligatorios.
3. Preview — muestra las primeras filas con estado válido / omitido. Las filas con valores inválidos (por ejemplo, texto no numérico en un campo NUMBER) se omiten.
4. Import complete — un resumen de filas importadas y omitidas.

Tratamiento de valores durante la importación:

Las importaciones respetan el límite de filas de tu plan: si importar el archivo lo superaría, la importación se rechaza antes de insertar fila alguna.

Export CSV

Pulsa Export CSV para descargar todas las filas de la tabla como archivo CSV en UTF-8, listo para abrir en Excel o Google Sheets. Los encabezados de columna son los nombres de campo internos (no las labels amigables), de modo que un archivo exportado puede reimportarse y emparejarse 1:1.

---

Webhooks de filas

Los owners y admins pueden notificar a un sistema externo cada vez que cambia una fila. Pulsa Webhooks en el detalle de la tabla.

Al crear un webhook se muestra una clave de firma (signing secret) una sola vez y nunca más: guárdala de inmediato. Cada solicitud incluye un encabezado X-Helios-Signature (sha256= más un HMAC-SHA256 en hexadecimal del cuerpo sin procesar) y un encabezado X-Helios-Timestamp, para que tu endpoint pueda verificar la autenticidad.

Notas de entrega:

• Las entregas son de mejor esfuerzo: las solicitudes expiran a los 5 segundos y no se reintentan automáticamente. Un webhook nunca bloquea ni ralentiza los cambios de filas.
• La lista de webhooks muestra solo el esquema y el host de cada URL; la URL completa es visible mientras la creas.

---

Consultas en lenguaje natural

En el detalle de la tabla, escribe una pregunta en español o inglés y Data Tables la responde. Cada consulta se ejecuta sobre una sola tabla.

Preguntas que funcionan bien

Notas

• Los resultados se limitan a 100 filas por consulta.
• Los conteos, sumas, promedios y agrupaciones se calculan en la base de datos sobre todas las filas de la tabla para las preguntas habituales; algunas formas complejas (por ejemplo, agrupar por un período calculado como el mes) se calculan sobre hasta 5,000 filas.
• Las fechas deben usar formato ISO (YYYY-MM-DD).
• Cada consulta se ejecuta sobre una tabla a la vez; las tablas no se pueden relacionar entre sí.
• El cuadro de consulta recuerda tus últimas preguntas y respuestas durante la sesión del navegador, así que las preguntas de seguimiento ("¿y solo los pendientes?") funcionan.
• Las consultas tienen un límite por minuto según tu plan (ver Límites por plan).

---

Gestionar tablas desde la lista

Cada tarjeta de tabla ofrece acciones rápidas:

La tarjeta también lista qué agentes están asignados a la tabla.

Editar el esquema

Cuando cambias el esquema en Edit Table, un diálogo de confirmación resume primero el impacto ("N filas se migrarán para coincidir") y después las filas existentes se migran automáticamente:

• Renombrar un campo — los valores se mueven al nuevo nombre de campo.
• Cambiar el tipo de un campo — los valores que no se pueden convertir se conservan tal cual, y se te avisa cuántos no pudieron convertirse.
• Eliminar un campo — sus datos se pierden.

Cambiar solo la label amigable de un campo o su casilla Optional nunca toca los datos de las filas y no requiere confirmación.

Eliminar una tabla (desde la Danger Zone en Edit Table) borra todas las filas y no se puede deshacer.

---

Asignar tablas a agentes

Para que un agente responda preguntas sobre una tabla:

1. Ve a Agents y selecciona el agente.
2. Habilita el acceso a datos en las herramientas del agente.
3. Selecciona las tablas que el agente puede usar.
4. Guarda los cambios.

El agente podrá entonces responder preguntas sobre esas tablas en conversaciones de chat, email o voz.

---

Buenas prácticas

1. Nombres descriptivos: usa nombres visibles y de campo claros para que los agentes entiendan los datos.
2. Nombres de campo en inglés: mantén los nombres internos de campo en inglés para mejor compatibilidad (usa la label amigable para mostrar).
3. Limitar operaciones: habilita INSERT / UPDATE / DELETE solo cuando un agente realmente deba escribir; deja las tablas de solo lectura en SELECT.
4. Descripciones útiles: agrega una descripción que explique para qué sirve la tabla.
5. Tipos correctos: usa NUMBER para valores numéricos y DATE / TIMESTAMP para fechas, para que los agregados y filtros funcionen.
6. Suspender en vez de eliminar: apaga el Active switch para pausar una tabla sin perder sus datos.
7. Empareja todos los campos obligatorios al importar: las filas sin un valor obligatorio se omiten.

---

Errores comunes

"No se encontraron resultados"

• Verifica que la tabla tenga datos.
• Revisa la ortografía de los valores que buscaste.
• Intenta primero una pregunta más simple.

"No pudimos ejecutar esa consulta"

• Reformula la pregunta y asegúrate de que los campos que mencionas existen en el esquema.
• Si ejecutaste muchas consultas seguidas, espera un minuto: las consultas en lenguaje natural tienen un límite por minuto según el plan.

El agente no responde sobre la tabla

• Verifica que la tabla esté asignada al agente.
• Verifica que el agente tenga el acceso a datos habilitado.
• Verifica que la tabla esté Active y que sus Allowed Operations incluyan SELECT.

Se omitieron filas del CSV

• Se requiere una fila de encabezado, y los archivos están limitados a 5 MB y 50,000 filas.
• Revisa que los emparejamientos de columnas sean correctos, que todos los campos obligatorios estén emparejados y que las columnas NUMBER / BOOLEAN contengan valores válidos.

"Límite del plan alcanzado" al importar

• La importación superaría el límite de filas de tu plan. Elimina filas que ya no necesites o mejora tu plan; no se importa nada hasta que el archivo completo quepa.

---

Captura

Relacionados

• Agentes de IA - Configuración de agentes
• Webhooks - Herramientas disponibles

---