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

layout	title	parent
default	Техническая спецификация управления коллекциями	Russian (Beta)

Техническая спецификация управления коллекциями

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.

Обзор

Эта спецификация описывает возможности управления коллекциями для TrustGraph, требуя явного создания коллекций и обеспечивая прямой контроль над жизненным циклом коллекций. Коллекции должны быть явно созданы перед использованием, что обеспечивает надлежащую синхронизацию между метаданными библиотекаря и всеми хранилищами. Эта функция поддерживает четыре основных сценария использования:

1. Создание коллекции: Явно создавайте коллекции перед сохранением данных.
2. Перечисление коллекций: Просматривайте все существующие коллекции в системе.
3. Управление метаданными коллекции: Обновляйте имена, описания и теги коллекций.
4. Удаление коллекции: Удаляйте коллекции и связанные с ними данные во всех типах хранилищ.

Цели

Явное создание коллекции: Требуйте, чтобы коллекции создавались перед сохранением данных. Синхронизация хранилищ: Обеспечьте наличие коллекций во всех хранилищах (векторах, объектах, тройках). Видимость коллекций: Предоставьте пользователям возможность перечислять и просматривать все коллекции в их среде. Очистка коллекций: Разрешите удаление коллекций, которые больше не нужны. Организация коллекций: Поддержка меток и тегов для лучшего отслеживания и обнаружения коллекций. Управление метаданными: Связывайте значимые метаданные с коллекциями для обеспечения оперативной ясности. Обнаружение коллекций: Облегчите поиск конкретных коллекций с помощью фильтрации и поиска. Оперативная прозрачность: Обеспечьте четкую видимость жизненного цикла и использования коллекций. Управление ресурсами: Позвольте очищать неиспользуемые коллекции для оптимизации использования ресурсов. Целостность данных: Предотвратите появление "сиротских" коллекций в хранилище без отслеживания метаданных.

Предыстория

Ранее коллекции в TrustGraph создавались неявно во время операций загрузки данных, что приводило к проблемам синхронизации, когда коллекции могли существовать в хранилищах без соответствующих метаданных в библиотекаре. Это создавало проблемы управления и потенциальные "сиротские" данные.

Модель явного создания коллекций решает эти проблемы следующим образом: Требует создания коллекций перед использованием через tg-set-collection. Передает информацию о создании коллекции во все хранилища. Поддерживает синхронизированное состояние между метаданными библиотекаря и хранилищем. Предотвращает запись в несуществующие коллекции. Обеспечивает четкое управление жизненным циклом коллекций.

Эта спецификация определяет модель явного управления коллекциями. Требуя явного создания коллекций, TrustGraph обеспечивает: Отслеживание коллекций в метаданных библиотекаря с момента создания. Знание всеми хранилищами о коллекциях до получения данных. Отсутствие "сиротских" коллекций в хранилище. Четкую оперативную видимость и контроль над жизненным циклом коллекций. Последовательную обработку ошибок при выполнении операций, ссылающихся на несуществующие коллекции.

Технический дизайн

Архитектура

Система управления коллекциями будет реализована в существующей инфраструктуре TrustGraph:

1. Интеграция с сервисом библиотекаря Операции управления коллекциями будут добавлены в существующий сервис библиотекаря. Не требуется новый сервис - используется существующая аутентификация и модели доступа. Обрабатывает перечисление коллекций, удаление и управление метаданными.

   Модуль: trustgraph-librarian

2. Таблица метаданных коллекций Cassandra Новая таблица в существующем пространстве ключей библиотекаря. Хранит метаданные коллекций с доступом, специфичным для пользователя. Первичный ключ: (user_id, collection_id) для обеспечения правильной многопользовательской среды.

   Модуль: trustgraph-librarian

3. CLI для управления коллекциями Интерфейс командной строки для операций с коллекциями. Предоставляет команды для перечисления, удаления, добавления меток и тегов. Интегрируется с существующей инфраструктурой CLI.

   Модуль: trustgraph-cli

Модели данных

Таблица метаданных коллекций Cassandra

Метаданные коллекций будут храниться в структурированной таблице Cassandra в пространстве ключей библиотекаря:

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

Структура таблицы: user + collection: Составной первичный ключ, обеспечивающий изоляцию пользователей name: Человекочитаемое имя коллекции description: Подробное описание назначения коллекции tags: Набор тегов для категоризации и фильтрации created_at: Временная метка создания коллекции updated_at: Временная метка последнего изменения

Этот подход позволяет: Управление коллекциями с поддержкой многопользовательского режима и изоляцией пользователей Эффективный поиск по пользователю и коллекции Гибкая система тегирования для организации Отслеживание жизненного цикла для получения оперативной информации

Жизненный цикл коллекции

Коллекции явно создаются в библиотечнике, прежде чем можно будет выполнять операции с данными:

1. Создание коллекции (Два пути):

   Путь A: Создание, инициированное пользователем через tg-set-collection: Пользователь предоставляет идентификатор коллекции, имя, описание и теги Библиотечник создает запись метаданных в таблице collections Библиотечник отправляет сообщение "create-collection" всем хранилищам данных Все процессоры хранилищ создают коллекцию и подтверждают успешное выполнение Коллекция готова для операций с данными

   Путь B: Автоматическое создание при отправке документа: Пользователь отправляет документ, указывающий идентификатор коллекции Библиотечник проверяет, существует ли коллекция в таблице метаданных Если коллекция не существует: Библиотечник создает метаданные с настройками по умолчанию (имя = идентификатор коллекции, пустое описание/теги) Библиотечник отправляет сообщение "create-collection" всем хранилищам данных Все процессоры хранилищ создают коллекцию и подтверждают успешное выполнение Обработка документа продолжается после создания коллекции

   Оба пути обеспечивают существование коллекции в метаданных библиотечника И во всех хранилищах данных перед выполнением операций с данными.

2. Проверка хранилища: Операции записи проверяют существование коллекции: Процессоры хранилищ проверяют состояние коллекции перед принятием записи Записи в несуществующие коллекции возвращают ошибку Это предотвращает прямые записи, обходя логику создания коллекции библиотечником

3. Поведение при запросах: Операции запроса корректно обрабатывают несуществующие коллекции: Запросы к несуществующим коллекциям возвращают пустые результаты Не возникает ошибок для операций запроса Позволяет исследовать данные без необходимости существования коллекции

4. Обновление метаданных: Пользователи могут обновлять метаданные коллекции после ее создания: Обновление имени, описания и тегов через tg-set-collection Обновления применяются только к метаданным библиотечника Хранилища данных сохраняют коллекцию, но обновления метаданных не распространяются

5. Явное удаление: Пользователи удаляют коллекции через tg-delete-collection: Библиотечник отправляет сообщение "delete-collection" всем хранилищам данных Ожидает подтверждение от всех процессоров хранилищ Удаляет запись метаданных библиотечника только после завершения очистки хранилища Обеспечивает отсутствие "осиротевших" данных в хранилище

Ключевой принцип: Библиотечник является центральной точкой управления созданием коллекций. Независимо от того, инициировано ли это пользовательской командой или отправкой документа, библиотечник обеспечивает правильное отслеживание метаданных и синхронизацию хранилищ данных, прежде чем разрешить операции с данными.

Требуемые операции: Создание коллекции: Операция пользователя через tg-set-collection ИЛИ автоматическое создание при отправке документа Обновление метаданных коллекции: Операция пользователя для изменения имени, описания и тегов Удаление коллекции: Операция пользователя для удаления коллекции и ее данных во всех хранилищах Список коллекций: Операция пользователя для просмотра коллекций с фильтрацией по тегам

Управление коллекциями в нескольких хранилищах

Коллекции существуют в нескольких хранилищах данных в TrustGraph: Векторные хранилища (Qdrant, Milvus, Pinecone): Хранят вложения и векторные данные Объектные хранилища (Cassandra): Хранят документы и файлы Графовые хранилища (Cassandra, Neo4j, Memgraph, FalkorDB): Хранят данные графов/RDF

Каждый тип хранилища реализует: Отслеживание состояния коллекций: Поддержание информации о том, какие коллекции существуют. Создание коллекций: Прием и обработка операций "создать коллекцию". Проверка существования коллекций: Проверка существования коллекции перед записью данных. Удаление коллекций: Удаление всех данных для указанной коллекции.

Сервис библиотекаря координирует операции с коллекциями во всех типах хранилищ, обеспечивая: Создание коллекций во всех бэкендах перед использованием. Подтверждение создания всеми бэкендами перед возвратом успеха. Синхронизированный жизненный цикл коллекций во всех типах хранилища. Последовательную обработку ошибок, когда коллекции не существуют.

Отслеживание состояния коллекций по типу хранилища

Каждый бэкенд хранилища отслеживает состояние коллекций по-разному, в зависимости от его возможностей:

Triple Store на базе Cassandra: Использует существующую таблицу triples_collection. Создает системный маркер-трипл при создании коллекции. Запрос: SELECT collection FROM triples_collection WHERE collection = ? LIMIT 1. Эффективная проверка существования коллекции в одной партиции.

Векторные хранилища Qdrant/Milvus/Pinecone: Нативные API коллекций обеспечивают проверку существования. Коллекции создаются с правильной конфигурацией векторов. Метод collection_exists() использует API хранилища. Создание коллекции проверяет требования к размерности.

Графовые хранилища Neo4j/Memgraph/FalkorDB: Используют узлы :CollectionMetadata для отслеживания коллекций. Свойства узла: {user, collection, created_at}. Запрос: MATCH (c:CollectionMetadata {user: $user, collection: $collection}). Отделены от узлов данных для четкого разделения. Обеспечивает эффективное перечисление и проверку коллекций.

Объектное хранилище на базе Cassandra: Использует таблицу метаданных коллекции или маркерные строки. Аналогичный шаблон, что и для triple store. Проверяет существование коллекции перед записью документов.

API

API управления коллекциями (Библиотекарь): Создание/Обновление коллекции: Создание новой коллекции или обновление существующих метаданных через tg-set-collection. Список коллекций: Получение коллекций для пользователя с необязательной фильтрацией по тегам. Удаление коллекции: Удаление коллекции и связанных данных, распространяясь на все типы хранилищ.

API управления хранилищем (Все процессоры хранилища): Создание коллекции: Обработка операции "создать коллекцию", создание коллекции в хранилище. Удаление коллекции: Обработка операции "удалить коллекцию", удаление всех данных коллекции. Проверка существования коллекции: Внутренняя проверка перед принятием операций записи.

API операций с данными (Измененное поведение): API записи: Проверка существования коллекции перед принятием данных, возврат ошибки, если коллекция не существует. API запросов: Возврат пустых результатов для несуществующих коллекций без ошибки.

Детали реализации

Реализация будет следовать существующим шаблонам TrustGraph для интеграции служб и структуры командной строки.

Каскадное удаление коллекций

Когда пользователь инициирует удаление коллекции через сервис библиотекаря:

1. Проверка метаданных: Проверка существования коллекции и наличие у пользователя разрешения на удаление.
2. Каскадное удаление в хранилищах: Библиотекарь координирует удаление во всех хранилищах записи: Хранилище векторов: Удаление вложений и индексов векторов для пользователя и коллекции. Объектное хранилище: Удаление документов и файлов для пользователя и коллекции. Графовое хранилище: Удаление данных графа и триплетов для пользователя и коллекции.
3. Очистка метаданных: Удаление записи метаданных коллекции из Cassandra.
4. Обработка ошибок: Если удаление в каком-либо хранилище не удалось, поддерживайте согласованность с помощью механизмов отката или повторной попытки.

Интерфейс управления коллекциями

⚠️ УСТАРЕВШИЙ ПОДХОД - ЗАМЕЩЕН ШАБЛОНОМ НА ОСНОВЕ КОНФИГУРАЦИИ

Архитектура на основе очереди, описанная ниже, была заменена подходом на основе конфигурации с использованием CollectionConfigHandler. Все бэкенды хранилищ теперь получают обновления коллекций через сообщения push конфигурации, а не через выделенные очереди управления.

Все хранилища записи реализуют стандартизированный интерфейс управления коллекциями с общей схемой:

Схема сообщения (StorageManagementRequest):

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

Архитектура очередей: Очередь управления векторными хранилищами (vector-storage-management): векторные/эмбеддинговые хранилища Очередь управления хранилищами объектов (object-storage-management): хранилища объектов/документов Очередь управления графовыми хранилищами (triples-storage-management): графовые/RDF хранилища Очередь обработки ответов хранилища (storage-management-response): все ответы отправляются сюда

Текущая реализация:

Все бэкенды хранилищ теперь используют CollectionConfigHandler: Интеграция с системой push-уведомлений конфигурации: службы хранилищ регистрируются для получения уведомлений об изменениях конфигурации Автоматическая синхронизация: коллекции создаются/удаляются на основе изменений конфигурации Декларативная модель: коллекции определены в службе конфигурации, бэкенды синхронизируются для соответствия Отсутствие запросов/ответов: устраняет накладные расходы на координацию и отслеживание ответов Отслеживание состояния коллекций: поддерживается через кэш known_collections Идемпотентные операции: безопасно обрабатывать одну и ту же конфигурацию несколько раз

Каждый бэкенд хранилища реализует: create_collection(user: str, collection: str, metadata: dict) - Создание структур коллекций delete_collection(user: str, collection: str) - Удаление всех данных коллекций collection_exists(user: str, collection: str) -> bool - Проверка перед записью

Рефакторинг графового хранилища Cassandra

В рамках этой реализации графовое хранилище Cassandra будет переработано с модели "таблица на коллекцию" на унифицированную модель "одна таблица":

Текущая архитектура: Keyspace на пользователя, отдельная таблица на коллекцию Схема: (s, p, o) с PRIMARY KEY (s, p, o) Имена таблиц: коллекции пользователя становятся отдельными таблицами Cassandra

Новая архитектура: Keyspace на пользователя, одна таблица "triples" для всех коллекций Схема: (collection, s, p, o) с PRIMARY KEY (collection, s, p, o) Изоляция коллекций через партиционирование коллекций

Необходимые изменения:

1. Рефакторинг класса TrustGraph (trustgraph/direct/cassandra.py): Удалить параметр table из конструктора, использовать фиксированную таблицу "triples" Добавить параметр collection ко всем методам Обновить схему для включения коллекции в качестве первого столбца Обновления индексов: Будут созданы новые индексы для поддержки всех 8 шаблонов запросов: Индекс на (s) для запросов на основе субъекта Индекс на (p) для запросов на основе предиката Индекс на (o) для запросов на основе объекта Обратите внимание: Cassandra не поддерживает многоколоночные вторичные индексы, поэтому это одноколоночные индексы

   Производительность шаблонов запросов: ✅ get_all() - сканирование раздела на collection ✅ get_s(s) - эффективно использует первичный ключ (collection, s) ✅ get_p(p) - использует idx_p с фильтрацией collection ✅ get_o(o) - использует idx_o с фильтрацией collection ✅ get_sp(s, p) - эффективно использует первичный ключ (collection, s, p) ⚠️ get_po(p, o) - требует ALLOW FILTERING (использует либо idx_p, либо idx_o плюс фильтрацию) ✅ get_os(o, s) - использует idx_o с дополнительной фильтрацией на s ✅ get_spo(s, p, o) - эффективно использует полный первичный ключ

   Примечание об ALLOW FILTERING: Шаблон запроса get_po требует ALLOW FILTERING, поскольку ему необходимы ограничения как предиката, так и объекта без подходящего составного индекса. Это допустимо, поскольку этот шаблон запроса менее распространен, чем запросы на основе субъекта, в типичном использовании хранилища тройных данных.

2. Обновления модуля записи данных (trustgraph/storage/triples/cassandra/write.py): Поддерживать одно соединение TrustGraph на пользователя вместо одного соединения на (пользователь, коллекция) Передавать коллекцию в операции вставки Улучшенное использование ресурсов за счет меньшего количества соединений

3. Обновления сервиса запросов (trustgraph/query/triples/cassandra/service.py): Одно соединение TrustGraph на пользователя Передавать коллекцию во все операции запросов Сохранять ту же логику запросов с параметром коллекции

Преимущества: Упрощенное удаление коллекций: Удаление с использованием ключа раздела collection во всех 4 таблицах Эффективность использования ресурсов: Меньшее количество соединений с базой данных и объектов таблиц Операции, охватывающие несколько коллекций: Легче реализовать операции, охватывающие несколько коллекций Согласованная архитектура: Соответствует унифицированному подходу к метаданным коллекций Проверка коллекций: Легко проверить существование коллекции через таблицу triples_collection

Операции с коллекциями будут выполняться атомарно, где это возможно, и обеспечивать соответствующую обработку ошибок и проверку.

Вопросы безопасности

Управление коллекциями требует соответствующей авторизации для предотвращения несанкционированного доступа или удаления коллекций. Контроль доступа будет соответствовать существующим моделям безопасности TrustGraph.

Вопросы производительности

Операции перечисления коллекций могут требовать постраничной разбивки для сред с большим количеством коллекций. Запросы метаданных должны быть оптимизированы для распространенных шаблонов фильтрации.

Стратегия тестирования

Комплексное тестирование будет охватывать: Рабочий процесс создания коллекции от начала до конца Синхронизация с хранилищем Проверка при записи для несуществующих коллекций Обработка запросов для несуществующих коллекций Каскадное удаление коллекций во всех хранилищах Обработка ошибок и сценарии восстановления Юнит-тесты для каждого хранилища Интеграционные тесты для операций между хранилищами

Статус реализации

✅ Завершенные компоненты

1. Сервис управления коллекциями Librarian (trustgraph-flow/trustgraph/librarian/collection_manager.py) Операции CRUD (создание, чтение, обновление, удаление) метаданных коллекции Интеграция с таблицей метаданных коллекций Cassandra через LibraryTableStore Координация каскадного удаления коллекций во всех типах хранилищ Асинхронная обработка запросов/ответов с надлежащим управлением ошибками

2. Схема метаданных коллекции (trustgraph-base/trustgraph/schema/services/collection.py) Схемы CollectionManagementRequest и CollectionManagementResponse Схема CollectionMetadata для записей коллекций Определения тем очередей для запросов/ответов коллекции

3. Схема управления хранилищем (trustgraph-base/trustgraph/schema/services/storage.py) Схемы StorageManagementRequest и StorageManagementResponse Определены темы очередей для управления хранилищем Формат сообщения для операций с коллекциями на уровне хранилища

4. Схема Cassandra для 4 таблиц (trustgraph-flow/trustgraph/direct/cassandra_kg.py) Составные ключи разделов для повышения производительности запросов Таблица triples_collection для запросов SPO и отслеживания удаления Реализовано удаление коллекций с использованием шаблона "чтение-затем-удаление"

✅ Миграция на конфигурационно-ориентированный шаблон - ЗАВЕРШЕНО

Все хранилища были перенесены из шаблона на основе очереди на конфигурационно-ориентированный шаблон CollectionConfigHandler.

Выполненные миграции: ✅ 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

Теперь все хранилища: Наследуют от CollectionConfigHandler Регистрируются для получения уведомлений об изменениях конфигурации через self.register_config_handler(self.on_collection_config) Реализуют create_collection(user, collection, metadata) и delete_collection(user, collection) Используют collection_exists(user, collection) для проверки перед записью Автоматически синхронизируются с изменениями сервиса конфигурации

Устаревшая инфраструктура на основе очереди удалена: ✅ Удалены схемы StorageManagementRequest и StorageManagementResponse ✅ Удалены определения тем управления хранилищем ✅ Удален потребитель/производитель очереди управления хранилищем из всех хранилищ ✅ Удалены обработчики on_storage_management из всех хранилищ