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

---
layout: default
title: "Техническая спецификация управления коллекциями"
parent: "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 в пространстве ключей библиотекаря:

```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` для отслеживания коллекций.
Свойства узла: `{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`):**~~
```json
{
  "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` из всех хранилищ