Database AI — Referencia Técnica
Esta página describe cómo se comporta Database AI por debajo de la interfaz, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Asume familiaridad con bases de datos relacionales, JSON y APIs cliente–servidor, y se centra en el comportamiento observable y los contratos de datos, no en detalles de implementación.
Modelo de arquitectura
Database AI mantiene dos aspectos separados:
- Estructura (metadatos) — espacios, bases de datos, definiciones de columnas, vistas y conectores.
- Datos de registros — las filas almacenadas en cada base de datos.
Los datos de registros viven en una base de datos relacional y están aislados por espacio de trabajo: cada consulta se limita al espacio de trabajo propietario, y los registros de cuentas distintas nunca se mezclan.
Los clientes usan dos canales:
| Canal | Para qué se usa |
|---|---|
| API REST | Operaciones de estructura y metadatos (espacios, bases de datos, columnas, vistas, conectores), consultas de IA y exportaciones |
| WebSocket | Operaciones a nivel de registro (seleccionar, insertar, actualizar, eliminar) y actualizaciones en vivo difundidas a otros clientes conectados |
Entidades y relaciones
| Entidad | Descripción |
|---|---|
| Espacio | Un espacio de nombres que agrupa bases de datos relacionadas y corresponde a un contenedor de datos aislado. |
| Base de datos | Una colección de registros regida por un esquema de columnas tipado. |
| Columna | Un campo tipado definido por un tipo amigable, un tipo de almacenamiento subyacente y restricciones. |
| Registro | Una fila de valores de columna, más un cuerpo de contenido enriquecido y un icono. |
| Vista | Una configuración guardada (tipo + filtros, orden, agrupación, columnas visibles) sobre una base de datos. |
| Conector | Una fuente de datos externa vinculada a una base de datos que incorpora registros automáticamente. |
Almacenamiento y sincronización en tiempo real
- Los cambios estructurales (bases de datos, columnas, vistas, conectores) se realizan a través de la API REST. El cliente aplica actualizaciones optimistas y revierte si una solicitud falla.
- Las operaciones sobre registros se ejecutan por una conexión WebSocket persistente. Los registros se cargan en lotes (paginación); los lotes posteriores se anexan a los anteriores.
- Cuando cualquier cliente cambia un registro, el cambio se difunde a los demás clientes conectados a la misma base de datos, que se actualizan en vivo.
- Los cambios hechos por programa — por agentes de IA, automatizaciones o conectores — emiten las mismas notificaciones de cambio, así que los clientes abiertos se actualizan automáticamente.
Sistema de tipos de columna
Cada columna tiene un tipo amigable (el tipo visible para el usuario) que se asigna a un tipo de almacenamiento subyacente más reglas de validación. Los valores se validan al escribir y se rechazan si no cumplen.
| Categoría | Tipos | Almacenamiento |
|---|---|---|
| Escalar | text, number, date, checkbox, email, url, phone, currency, rating, progress, duration, uuid | Primitivos de almacenamiento con restricciones (rangos, formatos) |
| De opción | status, select, multi_select | Validados contra un conjunto de opciones definido |
| Compuesto | file, person, relation, multi_select | Valores codificados en JSON |
Los valores compuestos se almacenan como JSON. Estas formas son el contrato de datos que la API REST y las herramientas de los agentes leen y escriben:
| Tipo | Forma del valor |
|---|---|
file | { "url", "name", "size", "type" } |
person | arreglo de entradas { "type", ... } |
relation | { "id", "title", "icon", ... } |
multi_select | [ "Option A", "Option C" ] |
Los valores de opción deben coincidir con una de las opciones configuradas de la columna; los tipos numéricos (rating, progress, duration) aplican sus rangos.
Vistas y el modelo de consulta
Una vista almacena un objeto de configuración: su tipo más filtros, orden, agrupación, columnas visibles y ajustes específicos del tipo (por ejemplo, la columna de agrupación para Kanban o la columna de fecha para Calendario).
- La configuración se aplica al momento de la consulta — el filtrado y el orden ocurren cuando se obtienen los registros.
- Los operadores de filtro cubren igualdad, comparación, subcadena, pertenencia, vacío y comprobaciones booleanas, con un manejo explícito de NULL para los operadores negativos (por ejemplo, "no es" y "no es ninguno de" incluyen valores NULL).
- Para las vistas públicas y de invitado, los filtros incrustados y las columnas ocultas de la vista se aplican del lado del servidor y el cliente no puede saltárselos. Los filtros que aporta quien la ve se agregan encima solo para esa sesión.
Conectores
Los conectores usan un modelo de sincronización por sondeo (polling) en lugar de entrega por push:
- Las entradas nuevas se obtienen de la fuente en un intervalo fijo (actualmente cada 30 minutos).
- El sondeo se elige por resiliencia — si un componente no está disponible por un momento, el siguiente ciclo se pone al día y no se pierde ninguna entrada.
- La deduplicación usa el identificador único de la fuente, así que las ventanas superpuestas nunca crean registros duplicados.
- Cada ciclo procesa solo las entradas creadas desde la última sincronización exitosa.
- Las columnas que requiere un conector se crean de forma idempotente durante la configuración y en la ingesta, manteniendo el esquema consistente.
Tareas de agentes
Una tarea de agente vincula un agente + instrucción + modo de ejecución a un único registro.
Estados de ejecución:
Modos de ejecución:
| Modo | Comportamiento |
|---|---|
| Inmediato | Se ejecuta en cuanto se despacha |
| Programado | Se ejecuta en una fecha y hora elegidas |
| Por evento | Se ejecuta cuando una columna de estado/selección elegida alcanza un valor objetivo |
- Disparadores — una tarea por evento se activa cuando su columna vigilada cambia al valor configurado, ya sea que el cambio venga de una persona o de otro agente.
- Cadenas — un agente puede actualizar otro registro, cuyo propio disparador por evento inicia al siguiente agente, formando flujos de varios agentes sin un grafo de flujo de trabajo explícito.
- Protección contra autobucles — un registro que ya está en
pending,queuedorunningno puede iniciar una nueva tarea, así que un agente no puede volver a dispararse a sí mismo. - Concurrencia y tiempo límite — cada tabla tiene un número máximo de tareas ejecutándose a la vez (las que sobran quedan en
pending) y un tiempo máximo de ejecución, tras el cual una tarea se marca comotimeout. - Cada ejecución produce un registro de ejecución que captura el contexto del registro entregado, el razonamiento del agente y sus llamadas a herramientas.
Acceso programático
Los agentes y las automatizaciones operan sobre una base de datos a través de una interfaz de herramientas: seleccionar, insertar, actualizar, eliminar, inspeccionar la estructura y consulta en lenguaje natural.
- Cada herramienta se genera contra el esquema de columnas de la base de datos e incluye pistas de formato, para que el agente entregue los valores con la forma correcta — listas de opciones para columnas de opción, códigos de moneda, rangos de calificación y las formas JSON de arriba para columnas compuestas.
- Las herramientas que cambian registros emiten las mismas notificaciones de actualización en vivo que las ediciones hechas en la interfaz.
Límites y garantías
- Las lecturas de registros son paginadas; las bases de datos grandes se transmiten en lotes.
- Los valores compuestos son JSON — los clientes deben serializar y deserializar en consecuencia.
- Las vistas públicas son de solo lectura; el acceso de invitado tiene permisos (ver o editar) y se confirma por verificación de correo.
- Los datos compartidos con la organización permanecen en el espacio de trabajo del propietario; los colaboradores operan sobre ellos en su lugar, sin hacer copias.
Qué sigue
- Funciones de IA — las herramientas para agentes y la consulta en lenguaje natural en la práctica
- Tareas de Agentes — la guía para usuarios sobre asignar agentes a registros
- Automatizaciones — coordina acciones de base de datos en varios pasos