Buckets
¿Qué son los Buckets?
Un Bucket es una tabla estructurada que vive dentro de Tavnit. Los Flows, Signals, Nets, Agentes y Pipelines escriben filas en ella automáticamente, puedes agregar filas mediante la API o desde un archivo CSV o Excel, y puedes filtrar, ordenar, graficar y hacerle preguntas al resultado sin exportarlo a ningún lado.
Un Run de un Flow guarda el resultado de un documento. Un Bucket es donde se acumulan los resultados de todos los Runs, así que la pregunta cambia de “¿qué decía esta factura?” a “¿cuánto nos han facturado este trimestre?”. Cada fila debe coincidir con las columnas del Bucket, y eso es lo que mantiene útil ese total.
Activa Exportar a Bucket en un Flow y mapea sus campos de salida a las columnas del Bucket. A partir de ahí, cada Run exitoso agrega sus filas, así que los resultados de muchos documentos se van reuniendo en una sola tabla.
Cuándo usar Buckets
Los Buckets son ideales para:
- Reunir en una sola tabla los resultados de extracción de muchos Runs de Flows
- Guardar datos de referencia (listas de precios, catálogos, listas de clientes) contra los que los Cleaners buscan valores
- Sincronizar datos con sistemas externos mediante la API, en ambos sentidos
- Juntar la salida estructurada de Signals, Nets y Agentes con tus datos de documentos
- Responder preguntas sobre tus datos en lenguaje natural, sin una hoja de cálculo
Los Runs de Flows guardan el resultado de cada documento. Los Buckets reúnen datos de muchos Runs y de otras fuentes en una sola tabla que puedes consultar, graficar y exportar.
Crear un Bucket
Los Propietarios y Administradores pueden crear Buckets:
- 1Ve a Buckets en la barra lateral y haz clic en "Crear Bucket" (o empieza "Desde plantilla")
- 2Escribe un nombre y, si quieres, una descripción, y elige un ícono y un color
- 3Haz clic en "Crear Bucket". Tavnit te ofrece "Gestionar Acceso" para definir quién puede verlo, o "Abrir Bucket" para ir directo a la cuadrícula
- 4Agrega columnas: en la cuadrícula usa "Insertar" → "Insertar Column", o importa un archivo CSV o Excel y deja que Tavnit cree las columnas por ti
- 5Para llenarlo desde un Flow, abre el Flow, activa "Exportar a Bucket", vincula este Bucket y mapea los campos del Flow a sus columnas
Cada columna tiene un nombre y un tipo de dato: Text, Number, Date, Checkbox o Dropdown (una lista fija de al menos dos opciones). Los tipos son los que permiten que el ordenamiento, los filtros, las agregaciones y los gráficos funcionen bien, así que vale la pena corregir en el origen una columna numérica que llega como texto.
Al escribir mediante la API, cada fila debe usar los nombres de columna del Bucket. Una fila con una columna que el Bucket no tiene cancela toda la escritura con un error de columnas que no coinciden, así que elige nombres claros y consistentes desde el inicio.
Encontrar el ID y el nombre de tu Bucket
Para usar la API de Buckets necesitas el ID y el nombre de tu Bucket. Ambos están en la página de detalles del Bucket:
- 1Ve a Buckets y haz clic en "Ver Detalles" en el Bucket que quieres usar
- 2Copia el nombre del Bucket desde el encabezado (tiene un botón para copiar)
- 3Abre "Bucket ID" en "Características" y copia el ID
La página de detalles también tiene la pestaña Esquema (cada columna, su tipo y sus marcas), la pestaña Historial de Escritura (cada escritura, su origen y cuántas filas agregó) y Flows Vinculados, los Flows que exportan a este Bucket.
La API exige bucket_id y bucket_name para evitar leer o escribir por accidente en el Bucket equivocado. Si el nombre no coincide con el ID, la solicitud se rechaza.
De dónde vienen los datos
Nada en un Bucket supone que los datos vinieron de un documento. Todas las fuentes de abajo escriben en la misma tabla, y por eso un Bucket sirve tanto como datos de referencia como de destino.
| Fuente | Cómo funciona | Uso típico |
|---|---|---|
| Exportar a Bucket en un Flow | Cada Run exitoso agrega sus filas, con los campos extraídos mapeados a las columnas del Bucket. | Acumular en una tabla cada factura que procesas. |
| Una acción de un Cleaner | Una acción edita un valor en una fila existente del Bucket que encontró un Lookup. | Marcar un pedido como recibido o descontar existencias. |
| Un Agente | Un Agente con entrega a Bucket escribe sus capturas en el Bucket después de cada Run. | Registrar precios vigentes de proveedores obtenidos de un portal. |
| Signals y Nets | Un Signal puede exportar las filas que estructura de cada grabación; una Net puede exportar las filas de cada captura completada. | Llevar el resultado de llamadas o publicaciones en redes junto a los datos de documentos. |
| Un Pipeline | Un nodo Bucket en el lienzo guarda lo que producen los pasos anteriores. | Terminar un Pipeline de varios pasos en una tabla. |
| La API REST | Agrega filas, o reemplaza las filas de la tabla, con una sola solicitud. | Sincronizar una lista de precios o un catálogo de clientes desde otro sistema. |
| Importación de CSV o Excel | Sube un archivo .csv, .xlsx o .xls desde la cuadrícula. | Cargar una hoja de cálculo existente una sola vez. |
| La propia cuadrícula | Cualquiera con acceso de edición puede agregar filas y escribir, pegar o borrar valores. | Correcciones rápidas y entradas manuales. |
Un Bucket no es solo un destino. Los campos Lookup de un Cleaner sacan valores de él para enriquecer una fila, y los campos Bucket Check preguntan si una fila ya existe, que es como funciona la deduplicación. Carga tu catálogo en un Bucket y todos tus Flows podrán compararse con él.
Si un Cleaner reorganiza las filas en formato ancho para la entrega, el Bucket igual recibe las filas originales en formato largo. Los datos guardados mantienen una fila por registro para que los totales y las búsquedas sigan siendo correctos.
Trabajar con los datos
La cuadrícula se parece más a una hoja de cálculo que a un informe de solo lectura. Puedes editar en el lugar, copiar y pegar celdas, filtrar y ordenar, y paginar tablas grandes, así que un Bucket con miles de filas sigue siendo cómodo de usar en el navegador.
| Control | Qué hace |
|---|---|
| Insertar | Agrega una fila o una columna, importa un archivo CSV o Excel, o abre Prompting. |
| Filtro | Reduce la vista a las filas que cumplen las condiciones que definas en cualquier columna. |
| Ordenar | Ordena las filas por una columna, de forma ascendente o descendente. |
f(x) | Muestra una fila de función bajo la cuadrícula con la suma, el promedio, el mínimo, el máximo o el conteo de cada columna, calculados sobre la página actual. |
| Gráfico | Crea un gráfico con los datos (ver Gráficos más abajo). |
| Chat | Abre un panel lateral para hacer preguntas sobre los datos (ver más abajo). |
| Exportar | Descarga todas las filas del Bucket como archivo CSV. |
| Deshacer / Rehacer | Retrocede y avanza entre las ediciones hechas en la cuadrícula. |
Quien tiene acceso de solo lectura ve la misma cuadrícula con un aviso de solo lectura: puede filtrar, ordenar, graficar y exportar, pero no editar.
Búsqueda IA en una columna
La coincidencia exacta falla cuando lo mismo se escribe de formas distintas: “Acme Corp.”, “ACME Corporation”, “acme”. La Búsqueda IA permite que un Cleaner encuentre coincidencias por significado.
- 1Abre el Bucket, haz clic en el encabezado de una columna de texto y elige "Editar Column"
- 2Activa "Búsqueda IA"
- 3Define la similitud mínima (de 1 a 100 %, 90 % por defecto). Por debajo de ese umbral, la búsqueda devuelve vacío en lugar de una coincidencia débil
- 4Haz clic en "Guardar Cambios". Tavnit indexa los valores de la columna en segundo plano
Una vez activada, un Lookup de un Cleaner puede usar el operador AI Match contra esa columna para encontrar la fila más parecida aunque el texto no coincida exactamente. La Búsqueda IA solo está disponible en columnas de texto.
Prompting: pregunta en lenguaje natural
Prompting responde preguntas como “¿Cuál es el monto total facturado por cada proveedor este año?” directamente desde el Bucket, y muestra cómo llegó a la respuesta.
- 1En la cuadrícula, abre "Insertar" → "Prompting"
- 2En "Configurar Prompting", elige las columnas de texto que quieres indexar y haz clic en "Activar". Tavnit agrupa sus valores distintos en categorías para que las preguntas puedan filtrar por significado
- 3Escribe tu pregunta en "Haz una Pregunta" (hasta 2,000 caracteres) y haz clic en "Preguntar"
Cada respuesta incluye los Supuestos que hizo, los Valores coincidentes que incluyó o excluyó, el resultado con un Desglose cuando corresponde, y Filas de muestra para que revises los datos detrás de ella. Las preguntas anteriores quedan en Historial.
Para configurar Prompting necesitas acceso de edición al Bucket.
Chatea con los datos
El botón Chat de la cuadrícula abre un panel lateral donde puedes conversar sobre el Bucket: totales, desgloses o pedidos del tipo “muéstrame”. Cuando una respuesta se refiere a un conjunto de filas, haz clic en Ver en la tabla para filtrar la cuadrícula a esas filas, y en Quitar vista para volver. Los chats se guardan, así que puedes retomar uno más tarde o empezar un Nuevo chat.
- El chat necesita Prompting activado en al menos una columna de texto del Bucket
- Cada organización tiene un cupo diario de mensajes, que se muestra en el panel y se restablece al día siguiente
- Los mensajes tienen un límite de 2,000 caracteres
El chat de Buckets se activa por organización. Si no ves el botón Chat, contacta a soporte para activarlo.
Control de acceso
Cada Bucket tiene una configuración de visibilidad y admite permisos por miembro, para que controles exactamente quién puede ver o editar tus datos. Los Propietarios y Administradores lo gestionan desde Acceso en la página de detalles.
Todos los miembros de tu organización pueden ver el Bucket. Por defecto los Administradores pueden editar y los Miembros solo pueden ver; puedes cambiarlo persona por persona.
Solo el Propietario y los usuarios con acceso explícito pueden ver este Bucket. Solo el Propietario de la organización puede hacer privado un Bucket, y los Administradores y Miembros sin un permiso explícito pierden el acceso de inmediato.
A cada persona se le puede dar uno de dos niveles de acceso:
- Solo lectura: puede abrir el Bucket y leer sus datos
- Editor: además puede agregar, editar y eliminar filas
En un Bucket privado hay una tercera opción, Sin acceso. Los Propietarios siempre tienen acceso completo. Los Administradores pueden definir el acceso de los Miembros; solo el Propietario puede cambiar el acceso de un Administrador. Modificar columnas y la configuración del Bucket sigue siendo de Propietarios y Administradores, sin importar el permiso. Consulta Roles de usuario para ver el modelo completo.
Gráficos
Puedes graficar los datos del Bucket directamente para ver tendencias y totales sin exportarlos a otra herramienta.
- 1Haz clic en "Gráfico" en la barra de herramientas de la cuadrícula
- 2Elige un tipo de gráfico: Barras, Línea, Circular o Dispersión (Tavnit marca el que mejor se ajusta a tus datos)
- 3Elige el campo por el que agrupar, y si quieres contar filas o agregar un campo numérico (Suma, Conteo, Promedio, Mínimo o Máximo)
- 4Si quieres, ordena, limita al Top 5, 10, 15 o 20, y define un título, tema de color, leyenda y cuadrícula
- 5Revisa la vista previa y haz clic en "Descargar como PNG" para guardarlo
Los gráficos usan todas las filas en Buckets de hasta 10,000 filas. Por encima de eso, Tavnit grafica una muestra de unas 10,000 filas y te lo indica. Los gráficos no se guardan con el Bucket: descarga el PNG si lo necesitas después.
Importar y exportar
Elige “Insertar” → “Importar CSV / Excel” y selecciona un archivo .csv, .xlsx o .xls. Tavnit empareja las columnas del archivo con las del Bucket por nombre; para las demás puedes mapear cada una a una columna existente, crearla como columna nueva u omitirla, y luego hacer clic en “Importar” (o “Crear e Importar”).
“Exportar” descarga todas las filas del Bucket como archivo CSV, sin importar los filtros que tengas en pantalla. Sirve para enviar datos a otras herramientas o guardar una copia de respaldo.
API de Buckets
Hay dos endpoints que funcionan con tu clave API (encabezado X-API-Key). Ambos exigen bucket_id y bucket_name.
| Endpoint | Qué hace |
|---|---|
POST /api/buckets/write | Agrega filas (overwrite: false) o reemplaza las filas de la tabla (overwrite: true). Hasta 50,000 filas por solicitud. |
GET /api/buckets/read | Devuelve las columnas y una página de filas, con total_count y has_more. Usa limit (100 por defecto, máximo 1,000) y offset para paginar. |
Los ejemplos completos de solicitud y respuesta están en la página de la API.
Solución de problemas
| Problema | Qué revisar |
|---|---|
| La cuadrícula dice que es de solo lectura | Tienes acceso de solo lectura. Pide a un Propietario o Administrador que te dé acceso de Editor en este Bucket. |
| Una escritura por API se rechaza porque las columnas no coinciden | Una fila usa un nombre de columna que el Bucket no tiene. Compara tus claves con la pestaña Esquema. |
| Una llamada a la API se rechaza porque el Bucket no coincide | bucket_name no coincide con el Bucket de ese bucket_id. Copia ambos de nuevo desde la página de detalles. |
| Un Flow se ejecuta pero no aparecen filas | Revisa que Exportar a Bucket esté activado en el Flow y que sus campos estén mapeados a columnas. Solo los Runs exitosos exportan. |
| No aparece el botón Chat | El chat de Buckets se activa por organización; contacta a soporte. |
| El chat dice que no está listo | Primero activa Prompting en al menos una columna de texto. |