trustgraph/docs/tech-specs/collection-management.es.md

layout	title	parent
default	Especificación Técnica de Gestión de Colecciones	Spanish (Beta)

Especificación Técnica de Gestión de Colecciones

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Descripción General

Esta especificación describe las capacidades de gestión de colecciones para TrustGraph, que requieren la creación explícita de colecciones y proporcionan un control directo sobre el ciclo de vida de la colección. Las colecciones deben crearse explícitamente antes de su uso, lo que garantiza una sincronización adecuada entre los metadatos del bibliotecario y todos los backends de almacenamiento. La función admite cuatro casos de uso principales:

1. Creación de Colecciones: Crear explícitamente colecciones antes de almacenar datos
2. Listado de Colecciones: Ver todas las colecciones existentes en el sistema
3. Gestión de Metadatos de Colecciones: Actualizar los nombres, las descripciones y las etiquetas de las colecciones
4. Eliminación de Colecciones: Eliminar colecciones y sus datos asociados en todos los tipos de almacenamiento

Objetivos

Creación Explícita de Colecciones: Requerir que las colecciones se creen antes de que se puedan almacenar datos Sincronización de Almacenamiento: Asegurar que las colecciones existan en todos los backends de almacenamiento (vectores, objetos, triples) Visibilidad de Colecciones: Permitir a los usuarios listar e inspeccionar todas las colecciones en su entorno Limpieza de Colecciones: Permitir la eliminación de colecciones que ya no son necesarias Organización de Colecciones: Compatibilidad con etiquetas para un mejor seguimiento y descubrimiento de colecciones Gestión de Metadatos: Asociar metadatos significativos con las colecciones para una mayor claridad operativa Descubrimiento de Colecciones: Facilitar la búsqueda de colecciones específicas mediante el filtrado y la búsqueda Transparencia Operacional: Proporcionar una visibilidad clara del ciclo de vida y el uso de las colecciones Gestión de Recursos: Permitir la limpieza de colecciones no utilizadas para optimizar la utilización de recursos Integridad de Datos: Prevenir la existencia de colecciones huérfanas en el almacenamiento sin seguimiento de metadatos

Antecedentes

Anteriormente, las colecciones en TrustGraph se creaban implícitamente durante las operaciones de carga de datos, lo que provocaba problemas de sincronización en los que las colecciones podían existir en los backends de almacenamiento sin metadatos correspondientes en el bibliotecario. Esto creaba desafíos de gestión y posibles datos huérfanos.

El modelo de creación explícita de colecciones aborda estos problemas mediante: La necesidad de crear colecciones antes de su uso a través de tg-set-collection La difusión de la creación de colecciones a todos los backends de almacenamiento El mantenimiento de un estado sincronizado entre los metadatos del bibliotecario y el almacenamiento La prevención de escrituras en colecciones inexistentes La provisión de una gestión clara del ciclo de vida de las colecciones

Esta especificación define el modelo de gestión explícita de colecciones. Al requerir la creación explícita de colecciones, TrustGraph garantiza: Que las colecciones se rastreen en los metadatos del bibliotecario desde su creación Que todos los backends de almacenamiento conozcan las colecciones antes de recibir datos Que no existan colecciones huérfanas en el almacenamiento Una visibilidad y un control claros del ciclo de vida de las colecciones Un manejo de errores coherente cuando las operaciones hacen referencia a colecciones inexistentes

Diseño Técnico

Arquitectura

El sistema de gestión de colecciones se implementará dentro de la infraestructura existente de TrustGraph:

1. Integración del Servicio del Bibliotecario Las operaciones de gestión de colecciones se agregarán al servicio del bibliotecario existente No se requiere un nuevo servicio; aprovecha los patrones de autenticación y acceso existentes Gestiona el listado, la eliminación y la gestión de metadatos de colecciones

   Módulo: trustgraph-librarian

2. Tabla de Metadatos de Colecciones de Cassandra Nueva tabla en el keyspace existente del bibliotecario Almacena metadatos de colecciones con acceso específico al usuario Clave primaria: (user_id, collection_id) para una correcta multi-tenencia

   Módulo: trustgraph-librarian

3. CLI de Gestión de Colecciones Interfaz de línea de comandos para operaciones de colecciones Proporciona comandos de listado, eliminación, etiquetado y gestión de etiquetas Se integra con el marco de CLI existente

   Módulo: trustgraph-cli

Modelos de Datos

Tabla de Metadatos de Colecciones de Cassandra

Los metadatos de la colección se almacenarán en una tabla estructurada de Cassandra en el keyspace del bibliotecario:

CREATE TABLE collections (
    user text,
    collection text,
    name text,
    description text,
    tags set<text>,
    created_at timestamp,
    updated_at timestamp,
    PRIMARY KEY (user, collection)
);

Estructura de la tabla: user + collection: Clave primaria compuesta que asegura el aislamiento del usuario name: Nombre legible por humanos de la colección description: Descripción detallada del propósito de la colección tags: Conjunto de etiquetas para la categorización y el filtrado created_at: Marca de tiempo de creación de la colección updated_at: Marca de tiempo de la última modificación

Este enfoque permite: Gestión de colecciones multi-inquilino con aislamiento de usuario Consulta eficiente por usuario y colección Sistema de etiquetado flexible para la organización Seguimiento del ciclo de vida para obtener información operativa

Ciclo de vida de la colección

Las colecciones se crean explícitamente en el bibliotecario antes de que puedan comenzar las operaciones de datos:

1. Creación de la colección (Dos caminos):

   Camino A: Creación iniciada por el usuario a través de tg-set-collection: El usuario proporciona el ID de la colección, el nombre, la descripción y las etiquetas El bibliotecario crea un registro de metadatos en la tabla collections El bibliotecario transmite "crear-colección" a todos los backends de almacenamiento Todos los procesadores de almacenamiento crean la colección y confirman el éxito La colección está ahora lista para las operaciones de datos

   Camino B: Creación automática al enviar un documento: El usuario envía un documento que especifica un ID de colección El bibliotecario comprueba si existe la colección en la tabla de metadatos Si no existe: El bibliotecario crea metadatos con valores predeterminados (nombre=id_colección, descripción/etiquetas vacías) El bibliotecario transmite "crear-colección" a todos los backends de almacenamiento Todos los procesadores de almacenamiento crean la colección y confirman el éxito El procesamiento del documento continúa con la colección ahora establecida

   Ambos caminos garantizan que la colección exista en los metadatos del bibliotecario Y en todos los backends de almacenamiento antes de permitir las operaciones de datos.

2. Validación de almacenamiento: Las operaciones de escritura validan la existencia de la colección: Los procesadores de almacenamiento comprueban el estado de la colección antes de aceptar escrituras Las escrituras en colecciones inexistentes devuelven un error Esto evita las escrituras directas que omiten la lógica de creación de colecciones del bibliotecario

3. Comportamiento de la consulta: Las operaciones de consulta gestionan las colecciones inexistentes de forma elegante: Las consultas a colecciones inexistentes devuelven resultados vacíos No se lanza ningún error para las operaciones de consulta Permite la exploración sin requerir que la colección exista

4. Actualizaciones de metadatos: Los usuarios pueden actualizar los metadatos de la colección después de la creación: Actualice el nombre, la descripción y las etiquetas a través de tg-set-collection Las actualizaciones se aplican solo a los metadatos del bibliotecario Los backends de almacenamiento mantienen la colección, pero las actualizaciones de metadatos no se propagan

5. Eliminación explícita: Los usuarios eliminan las colecciones a través de tg-delete-collection: El bibliotecario transmite "eliminar-colección" a todos los backends de almacenamiento Espera la confirmación de todos los procesadores de almacenamiento Elimina el registro de metadatos del bibliotecario solo después de que se complete la limpieza del almacenamiento Garantiza que no queden datos huérfanos en el almacenamiento

Principio clave: El bibliotecario es el único punto de control para la creación de colecciones. Ya sea iniciado por un comando de usuario o por la presentación de un documento, el bibliotecario garantiza el seguimiento adecuado de los metadatos y la sincronización del backend de almacenamiento antes de permitir las operaciones de datos.

Operaciones requeridas: Crear colección: Operación del usuario a través de tg-set-collection O automática al enviar un documento Actualizar metadatos de la colección: Operación del usuario para modificar el nombre, la descripción y las etiquetas Eliminar colección: Operación del usuario para eliminar la colección y sus datos en todos los almacenes Listar colecciones: Operación del usuario para ver las colecciones con filtrado por etiquetas

Gestión de colecciones multi-almacén

Las colecciones existen en varios backends de almacenamiento en TrustGraph: Tiendas vectoriales (Qdrant, Milvus, Pinecone): Almacena incrustaciones y datos vectoriales Tiendas de objetos (Cassandra): Almacena documentos y datos de archivos Tiendas de triples (Cassandra, Neo4j, Memgraph, FalkorDB): Almacena datos de grafos/RDF Después de la última línea traducida, incluir una línea final que contenga exactamente: [[END_OF_TRANSLATION]] Cada tipo de tienda implementa: Seguimiento del estado de la colección: Mantener conocimiento de qué colecciones existen Creación de colecciones: Aceptar y procesar operaciones de "crear-colección" Validación de colecciones: Comprobar si la colección existe antes de aceptar escrituras Eliminación de colecciones: Eliminar todos los datos para la colección especificada

El servicio de bibliotecario coordina las operaciones de colección en todos los tipos de tienda, asegurando: Que las colecciones se creen en todos los backends antes de su uso Que todos los backends confirmen la creación antes de devolver el éxito Un ciclo de vida de colección sincronizado en todos los tipos de almacenamiento Un manejo de errores consistente cuando las colecciones no existen

Seguimiento del estado de la colección por tipo de almacenamiento

Cada backend de almacenamiento realiza el seguimiento del estado de la colección de manera diferente según sus capacidades:

Triple Store de Cassandra: Utiliza la tabla triples_collection existente Crea un triple de marcador de sistema cuando se crea una colección Consulta: SELECT collection FROM triples_collection WHERE collection = ? LIMIT 1 Comprobación de existencia de colección eficiente de partición única

Almacenes de vectores Qdrant/Milvus/Pinecone: Las API nativas de colección proporcionan la comprobación de existencia Las colecciones se crean con la configuración de vectores adecuada El método collection_exists() utiliza la API de almacenamiento La creación de colecciones valida los requisitos de dimensión

Almacenes de grafos Neo4j/Memgraph/FalkorDB: Utiliza nodos :CollectionMetadata para realizar el seguimiento de las colecciones Propiedades del nodo: {user, collection, created_at} Consulta: MATCH (c:CollectionMetadata {user: $user, collection: $collection}) Separado de los nodos de datos para una separación limpia Permite una enumeración y validación eficientes de las colecciones

Almacén de objetos de Cassandra: Utiliza la tabla de metadatos de la colección o filas de marcador Patrón similar al triple store Valida la colección antes de las escrituras de documentos

API

API de administración de colecciones (Bibliotecario): Crear/Actualizar colección: Crear una nueva colección o actualizar los metadatos existentes a través de tg-set-collection Listar colecciones: Recuperar colecciones para un usuario con filtrado opcional por etiqueta Eliminar colección: Eliminar la colección y los datos asociados, propagándose a todos los tipos de tienda

API de administración de almacenamiento (Todos los procesadores de almacenamiento): Crear colección: Manejar la operación de "crear-colección", establecer la colección en el almacenamiento Eliminar colección: Manejar la operación de "eliminar-colección", eliminar todos los datos de la colección Comprobación de existencia de colección: Validación interna antes de aceptar operaciones de escritura

API de operación de datos (Comportamiento modificado): API de escritura: Validar que la colección exista antes de aceptar datos, devolver un error si no es así API de consulta: Devolver resultados vacíos para colecciones inexistentes sin error

Detalles de implementación

La implementación seguirá los patrones existentes de TrustGraph para la integración de servicios y la estructura de comandos de la CLI.

Eliminación en cascada de colecciones

Cuando un usuario inicia la eliminación de una colección a través del servicio de bibliotecario:

1. Validación de metadatos: Verificar que la colección exista y que el usuario tenga permiso para eliminarla
2. Propagación a tiendas: El bibliotecario coordina la eliminación en todos los escritores de tiendas: Escritor de almacenamiento de vectores: Eliminar incrustaciones e índices de vectores para el usuario y la colección Escritor de almacenamiento de objetos: Eliminar documentos y archivos para el usuario y la colección Escritor de triple store: Eliminar datos de grafos y triples para el usuario y la colección
3. Limpieza de metadatos: Eliminar el registro de metadatos de la colección de Cassandra
4. Manejo de errores: Si falla la eliminación de alguna tienda, mantener la coherencia a través de mecanismos de reversión o reintento

Interfaz de administración de colecciones

⚠️ ENFOQUE ANTIGUO: REEMPLAZADO POR UN PATRÓN BASADO EN CONFIGURACIÓN

La arquitectura basada en colas descrita a continuación ha sido reemplazada por un enfoque basado en configuración que utiliza CollectionConfigHandler. Todos los backends de almacenamiento ahora reciben actualizaciones de colecciones a través de mensajes de configuración en lugar de colas de administración dedicadas.

Todos los escritores de tiendas implementan una interfaz de administración de colecciones estandarizada con un esquema común:

Esquema de mensaje (StorageManagementRequest):

{
  "operation": "create-collection" | "delete-collection",
  "user": "user123",
  "collection": "documents-2024"
}

Arquitectura de la Cola: Cola de Gestión de Almacenes Vectoriales (vector-storage-management): Almacenes de vectores/incrustaciones Cola de Gestión de Almacenes de Objetos (object-storage-management): Almacenes de objetos/documentos Cola de Gestión de Almacenes Triples (triples-storage-management): Almacenes de grafos/RDF Cola de Respuestas de Almacenamiento (storage-management-response): Todas las respuestas se envían aquí

Implementación Actual:

Todos los backends de almacenamiento ahora utilizan CollectionConfigHandler: Integración de Configuración Push: Los servicios de almacenamiento se registran para recibir notificaciones de configuración push. Sincronización Automática: Las colecciones se crean/eliminan en función de los cambios de configuración. Modelo Declarativo: Las colecciones se definen en el servicio de configuración, y los backends se sincronizan para que coincidan. Sin Solicitud/Respuesta: Elimina la sobrecarga de coordinación y el seguimiento de respuestas. Seguimiento del Estado de la Colección: Se mantiene a través de la caché known_collections. Operaciones Idempotentes: Es seguro procesar la misma configuración varias veces.

Cada backend de almacenamiento implementa: create_collection(user: str, collection: str, metadata: dict) - Crear estructuras de colección delete_collection(user: str, collection: str) - Eliminar todos los datos de la colección collection_exists(user: str, collection: str) -> bool - Validar antes de escribir

Refactorización del Almacén Triples de Cassandra

Como parte de esta implementación, el almacén triples de Cassandra se refactorizará de un modelo de una tabla por colección a un modelo de una tabla unificada:

Arquitectura Actual: Keyspace por usuario, tabla separada por colección Esquema: (s, p, o) con PRIMARY KEY (s, p, o) Nombres de tabla: las colecciones de usuario se convierten en tablas separadas de Cassandra.

Nueva Arquitectura: Keyspace por usuario, una sola tabla "triples" para todas las colecciones Esquema: (collection, s, p, o) con PRIMARY KEY (collection, s, p, o) Aislamiento de colecciones a través de la partición de colecciones

Cambios Requeridos:

1. Refactorización de la Clase TrustGraph (trustgraph/direct/cassandra.py): Eliminar el parámetro table del constructor, usar la tabla "triples" fija. Agregar el parámetro collection a todos los métodos. Actualizar el esquema para incluir la colección como la primera columna. Actualizaciones de Índice: Se crearán nuevos índices para admitir los 8 patrones de consulta: Índice en (s) para consultas basadas en el sujeto. Índice en (p) para consultas basadas en el predicado. Índice en (o) para consultas basadas en el objeto. Nota: Cassandra no admite índices secundarios de varias columnas, por lo que estos son índices de una sola columna.

   Rendimiento del Patrón de Consulta: ✅ get_all() - escaneo de partición en collection ✅ get_s(s) - utiliza la clave primaria de manera eficiente (collection, s) ✅ get_p(p) - utiliza idx_p con collection de filtrado ✅ get_o(o) - utiliza idx_o con collection de filtrado ✅ get_sp(s, p) - utiliza la clave primaria de manera eficiente (collection, s, p) ⚠️ get_po(p, o) - requiere ALLOW FILTERING (utiliza idx_p o idx_o más filtrado) ✅ get_os(o, s) - utiliza idx_o con filtrado adicional en s ✅ get_spo(s, p, o) - utiliza toda la clave primaria de manera eficiente

   Nota sobre ALLOW FILTERING: El patrón de consulta get_po requiere ALLOW FILTERING porque necesita tanto las restricciones de predicado como las de objeto sin un índice compuesto adecuado. Esto es aceptable porque este patrón de consulta es menos común que las consultas basadas en el sujeto en el uso típico de un almacén triples.

2. Actualizaciones del Escritor de Almacenamiento (trustgraph/storage/triples/cassandra/write.py): Mantener una única conexión TrustGraph por usuario en lugar de por (usuario, colección). Pasar la colección a las operaciones de inserción. Mejor utilización de recursos con menos conexiones.

3. Actualizaciones del Servicio de Consulta (trustgraph/query/triples/cassandra/service.py): Una única conexión TrustGraph por usuario. Pasar la colección a todas las operaciones de consulta. Mantener la misma lógica de consulta con el parámetro de colección.

Beneficios: Eliminación Simplificada de Colecciones: Eliminar utilizando la clave de partición collection en las 4 tablas. Eficiencia de Recursos: Menos conexiones de base de datos y objetos de tabla. Operaciones entre Colecciones: Más fácil de implementar operaciones que abarcan múltiples colecciones. Arquitectura Consistente: Se alinea con el enfoque unificado de metadatos de colección. Validación de Colecciones: Es fácil comprobar la existencia de la colección mediante la tabla triples_collection.

Las operaciones de colección serán atómicas siempre que sea posible y proporcionarán un manejo de errores y una validación adecuados.

Consideraciones de seguridad

Las operaciones de administración de colecciones requieren la autorización adecuada para evitar el acceso no autorizado o la eliminación de colecciones. El control de acceso se alineará con los modelos de seguridad de TrustGraph existentes.

Consideraciones de rendimiento

Las operaciones de listado de colecciones pueden requerir paginación para entornos con un gran número de colecciones. Las consultas de metadatos deben optimizarse para patrones de filtrado comunes.

Estrategia de pruebas

La prueba exhaustiva cubrirá: Flujo de trabajo de creación de colecciones de extremo a extremo Sincronización del almacenamiento en segundo plano Validación de escritura para colecciones inexistentes Manejo de consultas de colecciones inexistentes Eliminación de colecciones en cascada en todos los almacenes Manejo de errores y escenarios de recuperación Pruebas unitarias para cada almacenamiento en segundo plano Pruebas de integración para operaciones entre almacenes

Estado de la implementación

✅ Componentes completados

1. Servicio de administración de colecciones Librarian (trustgraph-flow/trustgraph/librarian/collection_manager.py) Operaciones CRUD de metadatos de colecciones (listar, actualizar, eliminar) Integración de la tabla de metadatos de colecciones de Cassandra a través de LibraryTableStore Coordinación de la eliminación de colecciones en cascada en todos los tipos de almacenamiento Manejo de solicitudes/respuestas asíncronas con una gestión de errores adecuada

2. Esquema de metadatos de colecciones (trustgraph-base/trustgraph/schema/services/collection.py) Esquemas CollectionManagementRequest y CollectionManagementResponse Esquema CollectionMetadata para registros de colecciones Definiciones de temas de cola de solicitudes/respuestas de colecciones

3. Esquema de administración de almacenamiento (trustgraph-base/trustgraph/schema/services/storage.py) Esquemas StorageManagementRequest y StorageManagementResponse Temas de cola de administración de almacenamiento definidos Formato de mensaje para operaciones de colecciones a nivel de almacenamiento

4. Esquema de tabla Cassandra de 4 tablas (trustgraph-flow/trustgraph/direct/cassandra_kg.py) Claves de partición compuestas para el rendimiento de la consulta Tabla triples_collection para consultas SPO y seguimiento de eliminación Implementación de la eliminación de colecciones con el patrón de lectura y eliminación

✅ Migración a patrón basado en configuración - COMPLETADO

Todos los backends de almacenamiento se han migrado del patrón basado en cola al patrón CollectionConfigHandler basado en configuración.

Migraciones completadas: ✅ trustgraph-flow/trustgraph/storage/triples/cassandra/write.py ✅ trustgraph-flow/trustgraph/storage/triples/neo4j/write.py ✅ trustgraph-flow/trustgraph/storage/triples/memgraph/write.py ✅ trustgraph-flow/trustgraph/storage/triples/falkordb/write.py ✅ trustgraph-flow/trustgraph/storage/doc_embeddings/qdrant/write.py ✅ trustgraph-flow/trustgraph/storage/graph_embeddings/qdrant/write.py ✅ trustgraph-flow/trustgraph/storage/doc_embeddings/milvus/write.py ✅ trustgraph-flow/trustgraph/storage/graph_embeddings/milvus/write.py ✅ trustgraph-flow/trustgraph/storage/doc_embeddings/pinecone/write.py ✅ trustgraph-flow/trustgraph/storage/graph_embeddings/pinecone/write.py ✅ trustgraph-flow/trustgraph/storage/objects/cassandra/write.py

Todos los backends ahora: Heredan de CollectionConfigHandler Se registran para notificaciones de configuración push a través de self.register_config_handler(self.on_collection_config) Implementan create_collection(user, collection, metadata) y delete_collection(user, collection) Utilizan collection_exists(user, collection) para validar antes de escribir Se sincronizan automáticamente con los cambios del servicio de configuración

Infraestructura basada en cola heredada eliminada: ✅ Esquemas StorageManagementRequest y StorageManagementResponse eliminados ✅ Definiciones de temas de cola de administración de almacenamiento eliminadas ✅ Consumidor/productor de administración de almacenamiento eliminado de todos los backends ✅ Manejadores on_storage_management eliminados de todos los backends