trustgraph/docs/tech-specs/graphql-query.ru.md

---
layout: default
title: "Техническая спецификация запросов GraphQL"
parent: "Russian (Beta)"
---

# Техническая спецификация запросов GraphQL

> **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.

## Обзор

Эта спецификация описывает реализацию интерфейса запросов GraphQL для хранения структурированных данных TrustGraph в Apache Cassandra. Основываясь на возможностях структурированных данных, описанных в спецификации structured-data.md, этот документ подробно описывает, как запросы GraphQL будут выполняться к таблицам Cassandra, содержащим извлеченные и импортированные структурированные объекты.

Сервис запросов GraphQL предоставит гибкий и типобезопасный интерфейс для запроса структурированных данных, хранящихся в Cassandra. Он будет динамически адаптироваться к изменениям схемы, поддерживать сложные запросы, включая отношения между объектами, и беспрепятственно интегрироваться с существующей архитектурой TrustGraph, основанной на обмене сообщениями.

## Цели

**Динамическая поддержка схемы**: Автоматическая адаптация к изменениям схемы в конфигурации без перезапуска сервиса.
**Соответствие стандартам GraphQL**: Предоставление стандартного интерфейса GraphQL, совместимого с существующими инструментами и клиентами GraphQL.
<<<<<<< HEAD
**Эффективные запросы к Cassandra**: Преобразование запросов GraphQL в эффективные запросы CQL к Cassandra, учитывающие первичные ключи и индексы.
**Разрешение отношений**: Поддержка решателей полей GraphQL для отношений между различными типами объектов.
**Типобезопасность**: Обеспечение типобезопасного выполнения запросов и генерации ответов на основе определений схемы.
**Масштабируемая производительность**: Эффективная обработка одновременных запросов с использованием правильного пула соединений и оптимизации запросов.
**Интеграция запросов/ответов**: Поддержка существующей архитектуры TrustGraph, основанной на шаблоне запросов/ответов с использованием Pulsar.
=======
**Эффективные запросы к Cassandra**: Преобразование запросов GraphQL в эффективные запросы CQL для Cassandra, учитывающие первичные ключи и индексы.
**Разрешение отношений**: Поддержка решателей полей GraphQL для отношений между различными типами объектов.
**Типобезопасность**: Обеспечение типобезопасного выполнения запросов и генерации ответов на основе определений схемы.
**Масштабируемая производительность**: Эффективная обработка одновременных запросов с использованием правильного пула соединений и оптимизации запросов.
**Интеграция запросов/ответов**: Поддержка существующего шаблона запросов/ответов TrustGraph, основанного на Pulsar.
>>>>>>> 82edf2d (New md files from RunPod)
**Обработка ошибок**: Предоставление подробной отчетности об ошибках для несоответствий схемы, ошибок запросов и проблем проверки данных.

## Предыстория

<<<<<<< HEAD
Реализация хранения структурированных данных (trustgraph-flow/trustgraph/storage/objects/cassandra/) записывает объекты в таблицы Cassandra на основе определений схемы, хранящихся в системе конфигурации TrustGraph. Эти таблицы используют структуру составного первичного ключа с коллекциями и первичными ключами, определенными схемой, что обеспечивает эффективные запросы внутри коллекций.
=======
Реализация хранения структурированных данных (trustgraph-flow/trustgraph/storage/objects/cassandra/) записывает объекты в таблицы Cassandra на основе определений схемы, хранящихся в системе конфигурации TrustGraph. Эти таблицы используют структуру составного первичного ключа с коллекциями и первичными ключами, определенными схемой, что обеспечивает эффективные запросы в пределах коллекций.
>>>>>>> 82edf2d (New md files from RunPod)

Текущие ограничения, которые эта спецификация решает:
Отсутствие интерфейса запросов для структурированных данных, хранящихся в Cassandra.
Невозможность использования мощных возможностей запросов GraphQL для структурированных данных.
Отсутствие поддержки обхода отношений между связанными объектами.
Отсутствие стандартизированного языка запросов для доступа к структурированным данным.

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

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

### Архитектура

Сервис запросов GraphQL будет реализован как новый обработчик потоков TrustGraph, следуя установленным шаблонам:

<<<<<<< HEAD
**Местоположение модуля**: `trustgraph-flow/trustgraph/query/objects/cassandra/`
=======
**Расположение модуля**: `trustgraph-flow/trustgraph/query/objects/cassandra/`
>>>>>>> 82edf2d (New md files from RunPod)

**Основные компоненты**:

1. **Обработчик сервиса запросов GraphQL**
   Расширяет базовый класс FlowProcessor.
   Реализует шаблон запросов/ответов, аналогичный существующим сервисам запросов.
   Отслеживает конфигурацию на предмет обновлений схемы.
   Поддерживает синхронизацию схемы GraphQL с конфигурацией.

2. **Генератор динамической схемы**
<<<<<<< HEAD
   Преобразует определения RowSchema TrustGraph в типы GraphQL.
   Создает типы объектов GraphQL с соответствующими определениями полей.
   Генерирует корневой тип запроса с решателями на основе коллекций.
   Обновляет схему GraphQL при изменении конфигурации.

3. **Исполнитель запросов**
   Анализирует входящие запросы GraphQL с использованием библиотеки Strawberry.
=======
   Преобразует определения схемы TrustGraph в типы GraphQL.
   Создает типы объектов GraphQL с правильными определениями полей.
   Генерирует корневой тип Query с решателями на основе коллекций.
   Обновляет схему GraphQL при изменении конфигурации.

3. **Исполнитель запросов**
   Разбирает входящие запросы GraphQL с использованием библиотеки Strawberry.
>>>>>>> 82edf2d (New md files from RunPod)
   Проверяет запросы на соответствие текущей схеме.
   Выполняет запросы и возвращает структурированные ответы.
   Обрабатывает ошибки с подробными сообщениями об ошибках.

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
<<<<<<< HEAD
   Создание запроса CQL с правильными предложениями WHERE
=======
   Построение запроса CQL с правильными предложениями WHERE
>>>>>>> 82edf2d (New md files from RunPod)
   Включение коллекции в ключ партиции
   Применение фильтров на основе аргументов 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
  }
}
```

<<<<<<< HEAD
### Зависимости реализации
=======
### Реализация и зависимости
>>>>>>> 82edf2d (New md files from RunPod)

**Strawberry GraphQL**: Для определения схемы GraphQL и выполнения запросов.
**Cassandra Driver**: Для подключения к базе данных (уже используется в модуле хранения).
**TrustGraph Base**: Для FlowProcessor и определений схем.
**Configuration System**: Для мониторинга и обновления схем.

### Интерфейс командной строки

Сервис предоставит команду интерфейса командной строки: `kg-query-objects-graphql-cassandra`

Аргументы:
<<<<<<< HEAD
`--cassandra-host`: Точка контакта кластера Cassandra.
=======
`--cassandra-host`: Контактная точка кластера Cassandra.
>>>>>>> 82edf2d (New md files from RunPod)
`--cassandra-username`: Имя пользователя для аутентификации.
`--cassandra-password`: Пароль для аутентификации.
`--config-type`: Тип конфигурации для схем (по умолчанию: "schema").
Стандартные аргументы FlowProcessor (конфигурация Pulsar и т.д.).

<<<<<<< HEAD
## Интеграция API
=======
## Интеграция с API
>>>>>>> 82edf2d (New md files from RunPod)

### Темы Pulsar

**Входная тема**: `objects-graphql-query-request`
Схема: ObjectsQueryRequest
<<<<<<< HEAD
Получает GraphQL-запросы от шлюзовых сервисов.
=======
Получает запросы GraphQL от шлюзовых сервисов.
>>>>>>> 82edf2d (New md files from RunPod)

**Выходная тема**: `objects-graphql-query-response`
Схема: ObjectsQueryResponse
Возвращает результаты запросов и ошибки.

<<<<<<< HEAD
### Интеграция с шлюзом

Шлюз и обратный шлюз потребуют конечных точек для:
1. Приема GraphQL-запросов от клиентов.
2. Передачи запросов сервису запросов через Pulsar.
3. Возврата ответов клиентам.
4. Поддержки GraphQL-запросов на интроспекцию.
=======
### Интеграция со шлюзом

Шлюз и обратный шлюз потребуют конечных точек для:
1. Приема запросов GraphQL от клиентов.
2. Передачи запросов сервису запросов через Pulsar.
3. Возврата ответов клиентам.
4. Поддержки запросов introspection GraphQL.
>>>>>>> 82edf2d (New md files from RunPod)

### Интеграция с инструментом агента

Новый класс инструмента агента позволит:
<<<<<<< HEAD
Генерировать GraphQL-запросы из естественного языка.
Выполнять GraphQL-запросы напрямую.
Интерпретировать и форматировать результаты.
Интегрироваться с потоками принятия решений агентом.

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

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

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

**Планирование запросов**: Анализирует запросы перед выполнением для оптимизации генерации CQL.
=======
Преобразование естественного языка в запросы GraphQL.
Непосредственное выполнение запросов GraphQL.
Интерпретацию и форматирование результатов.
Интеграцию с потоками принятия решений агентом.

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

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

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

**Планирование запросов**: Анализ запросов перед выполнением для оптимизации генерации CQL.
>>>>>>> 82edf2d (New md files from RunPod)
**Кэширование результатов**: Рассмотрите возможность кэширования часто используемых данных на уровне решателя полей.
**Пул соединений**: Поддерживайте эффективные пулы соединений к Cassandra.
**Пакетные операции**: Объединяйте несколько запросов, когда это возможно, для уменьшения задержки.
**Мониторинг**: Отслеживайте метрики производительности запросов для оптимизации.

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

<<<<<<< HEAD
### Unit Tests
Генерация схемы на основе определений RowSchema
Разбор и проверка запросов GraphQL
Логика генерации запросов CQL
Реализации решателей полей

### Contract Tests
Соответствие контракту сообщений Pulsar
Достоверность схемы GraphQL
Проверка формата ответа
Проверка структуры ошибок

### Integration Tests
Комплексное выполнение запросов к тестовой инстанции Cassandra
Обработка обновлений схемы
Разрешение связей
Пагинация и фильтрация
Сценарии ошибок

### Performance Tests
Производительность запросов при высокой нагрузке
Время отклика для различных уровней сложности запросов
Использование памяти при работе с большими наборами результатов
Эффективность пула соединений
=======
### Юнит-тесты
Генерация схем из определений RowSchema.
Разбор и проверка запросов GraphQL.
Логика генерации запросов CQL.
Реализации решателей полей.

### Контрактные тесты
Соответствие контракту сообщений Pulsar.
Достоверность схемы GraphQL.
Проверка формата ответа.
Проверка структуры ошибок.

### Интеграционные тесты
Комплексное выполнение запросов к тестовой инстанции Cassandra.
Обработка обновления схем.
Разрешение взаимосвязей.
Пагинация и фильтрация.
Сценарии ошибок.

### Тесты производительности
Пропускная способность запросов при нагрузке.
Время отклика для различных уровней сложности запросов.
Использование памяти с большими наборами результатов.
Эффективность пула соединений.
>>>>>>> 82edf2d (New md files from RunPod)

## План миграции

Миграция не требуется, так как это новая функциональность. Сервис будет:
<<<<<<< HEAD
1. Считывать существующие схемы из конфигурации
2. Подключаться к существующим таблицам Cassandra, созданным модулем хранения
3. Начинать принимать запросы сразу после развертывания

## Сроки

1-2 неделя: Реализация основного сервиса и генерация схемы
3 неделя: Выполнение запросов и трансляция CQL
4 неделя: Разрешение связей и оптимизация
5 неделя: Тестирование и настройка производительности
6 неделя: Интеграция с шлюзом и документация

## Открытые вопросы

1. **Эволюция схемы**: Как сервис должен обрабатывать запросы во время изменений схемы?
   Вариант: Помещать запросы в очередь во время обновлений схемы
   Вариант: Поддерживать несколько версий схемы одновременно

2. **Стратегия кэширования**: Следует ли кэшировать результаты запросов?
   Рассмотреть: Временное истечение срока действия
   Рассмотреть: Инвалидация на основе событий

3. **Поддержка федерации**: Следует ли сервису поддерживать GraphQL federation для объединения с другими источниками данных?
   Это позволит выполнять унифицированные запросы к структурированным и графовым данным

4. **Поддержка подписок**: Следует ли сервису поддерживать GraphQL subscriptions для получения обновлений в реальном времени?
   Это потребует поддержки WebSocket в шлюзе

5. **Пользовательские скаляры**: Следует ли поддерживать пользовательские скалярные типы для специфических типов данных?
   Примеры: DateTime, UUID, JSON-поля
=======
1. Считывать существующие схемы из конфигурации.
Подключаться к существующим таблицам Cassandra, созданным модулем хранения.
3. Начинать принимать запросы сразу после развертывания.

## Открытые вопросы

**Эволюция схемы**: Как сервис должен обрабатывать запросы во время переходов схемы?
Вариант: Помещать запросы в очередь во время обновлений схемы.
Вариант: Поддерживать несколько версий схемы одновременно.

**Стратегия кэширования**: Следует ли кэшировать результаты запросов?
Рассмотреть: Временное истечение срока действия.
Рассмотреть: Инвалидация на основе событий.

**Поддержка федерации**: Должен ли сервис поддерживать федерацию GraphQL для объединения с другими источниками данных?
   Это позволит выполнять унифицированные запросы к структурированным и графовым данным.
   
**Поддержка подписок**: Должен ли сервис поддерживать подписки GraphQL для получения обновлений в режиме реального времени?
Это потребует поддержки WebSocket в шлюзе.
   
   **Пользовательские скаляры**: Должна ли поддерживаться поддержка пользовательских скалярных типов для специфических типов данных?
Примеры: DateTime, UUID, поля JSON.

   ## Ссылки

Техническая спецификация структурированных данных: ⟦CODE_0⟧
   Документация Strawberry GraphQL: ⟦URL_0⟧
Спецификация GraphQL: ⟦URL_0⟧
Документация Cassandra Driver: ⟦URL_0⟧
   Документация Pulsar: ⟦URL_0⟧
>>>>>>> 82edf2d (New md files from RunPod)

## Ссылки

Техническая спецификация структурированных данных: `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/
<<<<<<< HEAD
Документация TrustGraph Flow Processor: Внутренняя документация
=======
Документация процессора потоков TrustGraph: Внутренняя документация
>>>>>>> 82edf2d (New md files from RunPod)