> **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 в пространстве ключей библиотекаря:
```sql
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` для отслеживания коллекций.
Обеспечивает эффективное перечисление и проверку коллекций.
**Объектное хранилище на базе Cassandra:**
Использует таблицу метаданных коллекции или маркерные строки.
Аналогичный шаблон, что и для triple store.
Проверяет существование коллекции перед записью документов.
### API
API управления коллекциями (Библиотекарь):
**Создание/Обновление коллекции**: Создание новой коллекции или обновление существующих метаданных через `tg-set-collection`.
**Список коллекций**: Получение коллекций для пользователя с необязательной фильтрацией по тегам.
**Удаление коллекции**: Удаление коллекции и связанных данных, распространяясь на все типы хранилищ.
API управления хранилищем (Все процессоры хранилища):
**Создание коллекции**: Обработка операции "создать коллекцию", создание коллекции в хранилище.
**Удаление коллекции**: Обработка операции "удалить коллекцию", удаление всех данных коллекции.
**Проверка существования коллекции**: Внутренняя проверка перед принятием операций записи.
API операций с данными (Измененное поведение):
**API записи**: Проверка существования коллекции перед принятием данных, возврат ошибки, если коллекция не существует.
**API запросов**: Возврат пустых результатов для несуществующих коллекций без ошибки.
### Детали реализации
Реализация будет следовать существующим шаблонам TrustGraph для интеграции служб и структуры командной строки.
#### Каскадное удаление коллекций
Когда пользователь инициирует удаление коллекции через сервис библиотекаря:
1.**Проверка метаданных**: Проверка существования коллекции и наличие у пользователя разрешения на удаление.
2.**Каскадное удаление в хранилищах**: Библиотекарь координирует удаление во всех хранилищах записи:
Хранилище векторов: Удаление вложений и индексов векторов для пользователя и коллекции.
Объектное хранилище: Удаление документов и файлов для пользователя и коллекции.
Графовое хранилище: Удаление данных графа и триплетов для пользователя и коллекции.
3.**Очистка метаданных**: Удаление записи метаданных коллекции из Cassandra.
4.**Обработка ошибок**: Если удаление в каком-либо хранилище не удалось, поддерживайте согласованность с помощью механизмов отката или повторной попытки.
#### Интерфейс управления коллекциями
**⚠️ УСТАРЕВШИЙ ПОДХОД - ЗАМЕЩЕН ШАБЛОНОМ НАОСНОВЕ КОНФИГУРАЦИИ**
Архитектура на основе очереди, описанная ниже, была заменена подходом на основе конфигурации с использованием `CollectionConfigHandler`. Все бэкенды хранилищ теперь получают обновления коллекций через сообщения push конфигурации, а не через выделенные очереди управления.
~~Все хранилища записи реализуют стандартизированный интерфейс управления коллекциями с общей схемой:~~
~~**Схема сообщения (`StorageManagementRequest`):**~~
⚠️ `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 на пользователя вместо одного соединения на (пользователь, коллекция)
Передавать коллекцию в операции вставки
Улучшенное использование ресурсов за счет меньшего количества соединений
Сохранять ту же логику запросов с параметром коллекции
**Преимущества:**
**Упрощенное удаление коллекций**: Удаление с использованием ключа раздела `collection` во всех 4 таблицах
**Эффективность использования ресурсов**: Меньшее количество соединений с базой данных и объектов таблиц
**Операции, охватывающие несколько коллекций**: Легче реализовать операции, охватывающие несколько коллекций
**Согласованная архитектура**: Соответствует унифицированному подходу к метаданным коллекций
**Проверка коллекций**: Легко проверить существование коллекции через таблицу `triples_collection`
Операции с коллекциями будут выполняться атомарно, где это возможно, и обеспечивать соответствующую обработку ошибок и проверку.
## Вопросы безопасности
Управление коллекциями требует соответствующей авторизации для предотвращения несанкционированного доступа или удаления коллекций. Контроль доступа будет соответствовать существующим моделям безопасности TrustGraph.
## Вопросы производительности
Операции перечисления коллекций могут требовать постраничной разбивки для сред с большим количеством коллекций. Запросы метаданных должны быть оптимизированы для распространенных шаблонов фильтрации.
## Стратегия тестирования
Комплексное тестирование будет охватывать:
Рабочий процесс создания коллекции от начала до конца
Синхронизация с хранилищем
Проверка при записи для несуществующих коллекций
Обработка запросов для несуществующих коллекций
Каскадное удаление коллекций во всех хранилищах
Обработка ошибок и сценарии восстановления
Юнит-тесты для каждого хранилища
Интеграционные тесты для операций между хранилищами
## Статус реализации
### ✅ Завершенные компоненты
1.**Сервис управления коллекциями Librarian** (`trustgraph-flow/trustgraph/librarian/collection_manager.py`)
Операции CRUD (создание, чтение, обновление, удаление) метаданных коллекции
Интеграция с таблицей метаданных коллекций Cassandra через `LibraryTableStore`
Координация каскадного удаления коллекций во всех типах хранилищ
Асинхронная обработка запросов/ответов с надлежащим управлением ошибками
