mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-09 13:22:10 +02:00
add more docs
Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>
This commit is contained in:
Jenkins, Kenneth Alexander
parent
23e18cd562
commit
835acaa70e
94 changed files with 60854 additions and 1126 deletions
383
docs/tech-specs/graphql-query.ru.md
Normal file
383
docs/tech-specs/graphql-query.ru.md
Normal file
|
|
@ -0,0 +1,383 @@
|
|||
# Техническая спецификация запросов GraphQL
|
||||
|
||||
## Обзор
|
||||
|
||||
Эта спецификация описывает реализацию интерфейса запросов GraphQL для хранения структурированных данных TrustGraph в Apache Cassandra. Основываясь на возможностях структурированных данных, описанных в спецификации structured-data.md, этот документ подробно описывает, как запросы GraphQL будут выполняться к таблицам Cassandra, содержащим извлеченные и импортированные структурированные объекты.
|
||||
|
||||
Сервис запросов GraphQL предоставит гибкий и типобезопасный интерфейс для запроса структурированных данных, хранящихся в Cassandra. Он будет динамически адаптироваться к изменениям схемы, поддерживать сложные запросы, включая отношения между объектами, и беспрепятственно интегрироваться с существующей архитектурой TrustGraph, основанной на обмене сообщениями.
|
||||
|
||||
## Цели
|
||||
|
||||
**Динамическая поддержка схемы**: Автоматическая адаптация к изменениям схемы в конфигурации без перезапуска сервиса.
|
||||
**Соответствие стандартам GraphQL**: Предоставление стандартного интерфейса GraphQL, совместимого с существующими инструментами и клиентами GraphQL.
|
||||
**Эффективные запросы к Cassandra**: Преобразование запросов GraphQL в эффективные запросы CQL к Cassandra, учитывающие первичные ключи и индексы.
|
||||
**Разрешение отношений**: Поддержка решателей полей GraphQL для отношений между различными типами объектов.
|
||||
**Типобезопасность**: Обеспечение типобезопасного выполнения запросов и генерации ответов на основе определений схемы.
|
||||
**Масштабируемая производительность**: Эффективная обработка одновременных запросов с использованием правильного пула соединений и оптимизации запросов.
|
||||
**Интеграция запросов/ответов**: Поддержка существующей архитектуры TrustGraph, основанной на шаблоне запросов/ответов с использованием Pulsar.
|
||||
**Обработка ошибок**: Предоставление подробной отчетности об ошибках для несоответствий схемы, ошибок запросов и проблем проверки данных.
|
||||
|
||||
## Предыстория
|
||||
|
||||
Реализация хранения структурированных данных (trustgraph-flow/trustgraph/storage/objects/cassandra/) записывает объекты в таблицы Cassandra на основе определений схемы, хранящихся в системе конфигурации TrustGraph. Эти таблицы используют структуру составного первичного ключа с коллекциями и первичными ключами, определенными схемой, что обеспечивает эффективные запросы внутри коллекций.
|
||||
|
||||
Текущие ограничения, которые эта спецификация решает:
|
||||
Отсутствие интерфейса запросов для структурированных данных, хранящихся в Cassandra.
|
||||
Невозможность использования мощных возможностей запросов GraphQL для структурированных данных.
|
||||
Отсутствие поддержки обхода отношений между связанными объектами.
|
||||
Отсутствие стандартизированного языка запросов для доступа к структурированным данным.
|
||||
|
||||
Сервис запросов GraphQL устранит эти недостатки, предоставив:
|
||||
Стандартный интерфейс GraphQL для запросов к таблицам Cassandra.
|
||||
Динамическую генерацию схем GraphQL из конфигурации TrustGraph.
|
||||
Эффективное преобразование запросов GraphQL в CQL для Cassandra.
|
||||
Поддержку разрешения отношений с помощью решателей полей.
|
||||
|
||||
## Технический дизайн
|
||||
|
||||
### Архитектура
|
||||
|
||||
Сервис запросов GraphQL будет реализован как новый обработчик потоков TrustGraph, следуя установленным шаблонам:
|
||||
|
||||
**Местоположение модуля**: `trustgraph-flow/trustgraph/query/objects/cassandra/`
|
||||
|
||||
**Основные компоненты**:
|
||||
|
||||
1. **Обработчик сервиса запросов GraphQL**
|
||||
Расширяет базовый класс FlowProcessor.
|
||||
Реализует шаблон запросов/ответов, аналогичный существующим сервисам запросов.
|
||||
Отслеживает конфигурацию на предмет обновлений схемы.
|
||||
Поддерживает синхронизацию схемы GraphQL с конфигурацией.
|
||||
|
||||
2. **Генератор динамической схемы**
|
||||
Преобразует определения RowSchema TrustGraph в типы GraphQL.
|
||||
Создает типы объектов GraphQL с соответствующими определениями полей.
|
||||
Генерирует корневой тип запроса с решателями на основе коллекций.
|
||||
Обновляет схему GraphQL при изменении конфигурации.
|
||||
|
||||
3. **Исполнитель запросов**
|
||||
Анализирует входящие запросы GraphQL с использованием библиотеки Strawberry.
|
||||
Проверяет запросы на соответствие текущей схеме.
|
||||
Выполняет запросы и возвращает структурированные ответы.
|
||||
Обрабатывает ошибки с подробными сообщениями об ошибках.
|
||||
|
||||
4. **Транслятор запросов Cassandra**
|
||||
Преобразует выборки GraphQL в запросы CQL.
|
||||
Оптимизирует запросы на основе доступных индексов и первичных ключей.
|
||||
Обрабатывает фильтрацию, пагинацию и сортировку.
|
||||
Управляет пулом соединений и жизненным циклом сессии.
|
||||
|
||||
5. **Разрешитель отношений**
|
||||
Реализует решатели полей для отношений между объектами.
|
||||
Выполняет эффективную пакетную загрузку для предотвращения запросов N+1.
|
||||
Кэширует разрешенные отношения в контексте запроса.
|
||||
Поддерживает как прямой, так и обратный обход отношений.
|
||||
|
||||
### Мониторинг схемы конфигурации
|
||||
|
||||
Сервис зарегистрирует обработчик конфигурации для получения обновлений схемы:
|
||||
|
||||
```python
|
||||
self.register_config_handler(self.on_schema_config)
|
||||
```
|
||||
|
||||
Когда схемы меняются:
|
||||
1. Разбор новых определений схемы из конфигурации
|
||||
2. Регенерация типов GraphQL и решателей
|
||||
3. Обновление исполняемой схемы
|
||||
4. Очистка любых кэшей, зависящих от схемы
|
||||
|
||||
### Генерация схемы GraphQL
|
||||
|
||||
Для каждой RowSchema в конфигурации, генерируется:
|
||||
|
||||
1. **Тип объекта GraphQL**:
|
||||
Отображение типов полей (string → String, integer → Int, float → Float, boolean → Boolean)
|
||||
Отметка обязательных полей как non-nullable в GraphQL
|
||||
Добавление описаний полей из схемы
|
||||
|
||||
2. **Корневые поля запроса**:
|
||||
Запрос коллекции (например, `customers`, `transactions`)
|
||||
Аргументы фильтрации на основе индексированных полей
|
||||
Поддержка пагинации (limit, offset)
|
||||
Варианты сортировки для полей, поддерживающих сортировку
|
||||
|
||||
3. **Поля отношений**:
|
||||
Определение отношений внешнего ключа из схемы
|
||||
Создание решателей полей для связанных объектов
|
||||
Поддержка как одиночных объектов, так и списков отношений
|
||||
|
||||
### Поток выполнения запроса
|
||||
|
||||
1. **Прием запроса**:
|
||||
Получение ObjectsQueryRequest от Pulsar
|
||||
Извлечение строки запроса GraphQL и переменных
|
||||
Определение контекста пользователя и коллекции
|
||||
|
||||
2. **Валидация запроса**:
|
||||
Разбор запроса GraphQL с использованием Strawberry
|
||||
Проверка на соответствие текущей схеме
|
||||
Проверка выбранных полей и типов аргументов
|
||||
|
||||
3. **Генерация CQL**:
|
||||
Анализ выбранных элементов GraphQL
|
||||
Создание запроса CQL с правильными предложениями WHERE
|
||||
Включение коллекции в ключ партиции
|
||||
Применение фильтров на основе аргументов GraphQL
|
||||
|
||||
4. **Выполнение запроса**:
|
||||
Выполнение запроса CQL к Cassandra
|
||||
Отображение результатов в структуру ответа GraphQL
|
||||
Разрешение любых полей отношений
|
||||
Форматирование ответа в соответствии со спецификацией GraphQL
|
||||
|
||||
5. **Доставка ответа**:
|
||||
Создание ObjectsQueryResponse с результатами
|
||||
Включение любых ошибок выполнения
|
||||
Отправка ответа через Pulsar с идентификатором корреляции
|
||||
|
||||
### Модели данных
|
||||
|
||||
> **Примечание**: Существует существующая схема StructuredQueryRequest/Response в `trustgraph-base/trustgraph/schema/services/structured_query.py`. Однако, в ней отсутствуют критические поля (user, collection) и используются неоптимальные типы. Схемы ниже представляют собой рекомендуемую эволюцию, которая должна либо заменить существующие схемы, либо быть создана как новые типы ObjectsQueryRequest/Response.
|
||||
|
||||
#### Схема запроса (ObjectsQueryRequest)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Map, Array
|
||||
|
||||
class ObjectsQueryRequest(Record):
|
||||
user = String() # Cassandra keyspace (follows pattern from TriplesQueryRequest)
|
||||
collection = String() # Data collection identifier (required for partition key)
|
||||
query = String() # GraphQL query string
|
||||
variables = Map(String()) # GraphQL variables (consider enhancing to support all JSON types)
|
||||
operation_name = String() # Operation to execute for multi-operation documents
|
||||
```
|
||||
|
||||
**Обоснование изменений по сравнению с существующим запросом StructuredQueryRequest:**
|
||||
Добавлены поля `user` и `collection` для соответствия шаблону других сервисов запросов.
|
||||
Эти поля необходимы для идентификации пространства ключей и коллекции Cassandra.
|
||||
Переменные пока остаются Map(String()), но в идеале должны поддерживать все типы JSON.
|
||||
|
||||
#### Схема ответа (ObjectsQueryResponse)
|
||||
|
||||
```python
|
||||
from pulsar.schema import Record, String, Array
|
||||
from ..core.primitives import Error
|
||||
|
||||
class GraphQLError(Record):
|
||||
message = String()
|
||||
path = Array(String()) # Path to the field that caused the error
|
||||
extensions = Map(String()) # Additional error metadata
|
||||
|
||||
class ObjectsQueryResponse(Record):
|
||||
error = Error() # System-level error (connection, timeout, etc.)
|
||||
data = String() # JSON-encoded GraphQL response data
|
||||
errors = Array(GraphQLError) # GraphQL field-level errors
|
||||
extensions = Map(String()) # Query metadata (execution time, etc.)
|
||||
```
|
||||
|
||||
**Обоснование изменений по сравнению с существующим StructuredQueryResponse:**
|
||||
Различает системные ошибки (`error`) и ошибки GraphQL (`errors`)
|
||||
Использует структурированные объекты GraphQLError вместо массива строк
|
||||
Добавляет поле `extensions` для соответствия спецификации GraphQL
|
||||
Сохраняет данные в виде строки JSON для совместимости, хотя нативные типы были бы предпочтительнее
|
||||
|
||||
### Оптимизация запросов Cassandra
|
||||
|
||||
Сервис будет оптимизировать запросы Cassandra следующим образом:
|
||||
|
||||
1. **Соблюдение ключей разделов (Partition Keys):**
|
||||
Всегда включайте коллекцию в запросы
|
||||
Эффективно используйте первичные ключи, определенные в схеме
|
||||
Избегайте полного сканирования таблицы
|
||||
|
||||
2. **Использование индексов:**
|
||||
Используйте вторичные индексы для фильтрации
|
||||
Объединяйте несколько фильтров, когда это возможно
|
||||
Предупреждайте, когда запросы могут быть неэффективными
|
||||
|
||||
3. **Пакетная загрузка:**
|
||||
Собирайте запросы для получения взаимосвязей
|
||||
Выполняйте их пакетами для уменьшения количества обращений
|
||||
Кэшируйте результаты в контексте запроса
|
||||
|
||||
4. **Управление соединениями:**
|
||||
Поддерживайте постоянные сессии Cassandra
|
||||
Используйте пули соединений
|
||||
Обрабатывайте повторное подключение в случае сбоев
|
||||
|
||||
### Примеры запросов GraphQL
|
||||
|
||||
#### Простой запрос коллекции
|
||||
```graphql
|
||||
{
|
||||
customers(status: "active") {
|
||||
customer_id
|
||||
name
|
||||
email
|
||||
registration_date
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Запрос со связями
|
||||
```graphql
|
||||
{
|
||||
orders(order_date_gt: "2024-01-01") {
|
||||
order_id
|
||||
total_amount
|
||||
customer {
|
||||
name
|
||||
email
|
||||
}
|
||||
items {
|
||||
product_name
|
||||
quantity
|
||||
price
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Разделенная на страницы выборка
|
||||
```graphql
|
||||
{
|
||||
products(limit: 20, offset: 40) {
|
||||
product_id
|
||||
name
|
||||
price
|
||||
category
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Зависимости реализации
|
||||
|
||||
**Strawberry GraphQL**: Для определения схемы GraphQL и выполнения запросов.
|
||||
**Cassandra Driver**: Для подключения к базе данных (уже используется в модуле хранения).
|
||||
**TrustGraph Base**: Для FlowProcessor и определений схем.
|
||||
**Configuration System**: Для мониторинга и обновления схем.
|
||||
|
||||
### Интерфейс командной строки
|
||||
|
||||
Сервис предоставит команду интерфейса командной строки: `kg-query-objects-graphql-cassandra`
|
||||
|
||||
Аргументы:
|
||||
`--cassandra-host`: Точка контакта кластера Cassandra.
|
||||
`--cassandra-username`: Имя пользователя для аутентификации.
|
||||
`--cassandra-password`: Пароль для аутентификации.
|
||||
`--config-type`: Тип конфигурации для схем (по умолчанию: "schema").
|
||||
Стандартные аргументы FlowProcessor (конфигурация Pulsar и т.д.).
|
||||
|
||||
## Интеграция API
|
||||
|
||||
### Темы Pulsar
|
||||
|
||||
**Входная тема**: `objects-graphql-query-request`
|
||||
Схема: ObjectsQueryRequest
|
||||
Получает GraphQL-запросы от шлюзовых сервисов.
|
||||
|
||||
**Выходная тема**: `objects-graphql-query-response`
|
||||
Схема: ObjectsQueryResponse
|
||||
Возвращает результаты запросов и ошибки.
|
||||
|
||||
### Интеграция с шлюзом
|
||||
|
||||
Шлюз и обратный шлюз потребуют конечных точек для:
|
||||
1. Приема GraphQL-запросов от клиентов.
|
||||
2. Передачи запросов сервису запросов через Pulsar.
|
||||
3. Возврата ответов клиентам.
|
||||
4. Поддержки GraphQL-запросов на интроспекцию.
|
||||
|
||||
### Интеграция с инструментом агента
|
||||
|
||||
Новый класс инструмента агента позволит:
|
||||
Генерировать GraphQL-запросы из естественного языка.
|
||||
Выполнять GraphQL-запросы напрямую.
|
||||
Интерпретировать и форматировать результаты.
|
||||
Интегрироваться с потоками принятия решений агентом.
|
||||
|
||||
## Вопросы безопасности
|
||||
|
||||
**Ограничение глубины запросов**: Предотвращает вложенные запросы, которые могут вызвать проблемы с производительностью.
|
||||
**Анализ сложности запросов**: Ограничивает сложность запросов для предотвращения исчерпания ресурсов.
|
||||
**Разрешения на уровне полей**: Будущая поддержка контроля доступа на уровне полей на основе ролей пользователей.
|
||||
**Санитизация входных данных**: Проверяет и очищает все входные данные запросов для предотвращения атак внедрения.
|
||||
**Ограничение скорости**: Реализует ограничение скорости запросов на пользователя/коллекцию.
|
||||
|
||||
## Вопросы производительности
|
||||
|
||||
**Планирование запросов**: Анализирует запросы перед выполнением для оптимизации генерации CQL.
|
||||
**Кэширование результатов**: Рассмотрите возможность кэширования часто используемых данных на уровне решателя полей.
|
||||
**Пул соединений**: Поддерживайте эффективные пулы соединений к Cassandra.
|
||||
**Пакетные операции**: Объединяйте несколько запросов, когда это возможно, для уменьшения задержки.
|
||||
**Мониторинг**: Отслеживайте метрики производительности запросов для оптимизации.
|
||||
|
||||
## Стратегия тестирования
|
||||
|
||||
### Unit Tests
|
||||
Генерация схемы на основе определений RowSchema
|
||||
Разбор и проверка запросов GraphQL
|
||||
Логика генерации запросов CQL
|
||||
Реализации решателей полей
|
||||
|
||||
### Contract Tests
|
||||
Соответствие контракту сообщений Pulsar
|
||||
Достоверность схемы GraphQL
|
||||
Проверка формата ответа
|
||||
Проверка структуры ошибок
|
||||
|
||||
### Integration Tests
|
||||
Комплексное выполнение запросов к тестовой инстанции Cassandra
|
||||
Обработка обновлений схемы
|
||||
Разрешение связей
|
||||
Пагинация и фильтрация
|
||||
Сценарии ошибок
|
||||
|
||||
### Performance Tests
|
||||
Производительность запросов при высокой нагрузке
|
||||
Время отклика для различных уровней сложности запросов
|
||||
Использование памяти при работе с большими наборами результатов
|
||||
Эффективность пула соединений
|
||||
|
||||
## План миграции
|
||||
|
||||
Миграция не требуется, так как это новая функциональность. Сервис будет:
|
||||
1. Считывать существующие схемы из конфигурации
|
||||
2. Подключаться к существующим таблицам Cassandra, созданным модулем хранения
|
||||
3. Начинать принимать запросы сразу после развертывания
|
||||
|
||||
## Сроки
|
||||
|
||||
1-2 неделя: Реализация основного сервиса и генерация схемы
|
||||
3 неделя: Выполнение запросов и трансляция CQL
|
||||
4 неделя: Разрешение связей и оптимизация
|
||||
5 неделя: Тестирование и настройка производительности
|
||||
6 неделя: Интеграция с шлюзом и документация
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
1. **Эволюция схемы**: Как сервис должен обрабатывать запросы во время изменений схемы?
|
||||
Вариант: Помещать запросы в очередь во время обновлений схемы
|
||||
Вариант: Поддерживать несколько версий схемы одновременно
|
||||
|
||||
2. **Стратегия кэширования**: Следует ли кэшировать результаты запросов?
|
||||
Рассмотреть: Временное истечение срока действия
|
||||
Рассмотреть: Инвалидация на основе событий
|
||||
|
||||
3. **Поддержка федерации**: Следует ли сервису поддерживать GraphQL federation для объединения с другими источниками данных?
|
||||
Это позволит выполнять унифицированные запросы к структурированным и графовым данным
|
||||
|
||||
4. **Поддержка подписок**: Следует ли сервису поддерживать GraphQL subscriptions для получения обновлений в реальном времени?
|
||||
Это потребует поддержки WebSocket в шлюзе
|
||||
|
||||
5. **Пользовательские скаляры**: Следует ли поддерживать пользовательские скалярные типы для специфических типов данных?
|
||||
Примеры: DateTime, UUID, JSON-поля
|
||||
|
||||
## Ссылки
|
||||
|
||||
Техническая спецификация структурированных данных: `docs/tech-specs/structured-data.md`
|
||||
Документация Strawberry GraphQL: https://strawberry.rocks/
|
||||
Спецификация GraphQL: https://spec.graphql.org/
|
||||
Справочник Apache Cassandra CQL: https://cassandra.apache.org/doc/stable/cassandra/cql/
|
||||
Документация TrustGraph Flow Processor: Внутренняя документация
|
||||
Loading…
Add table
Add a link
Reference in a new issue