apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-09 05:12:12 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
trustgraph/docs/tech-specs/graphql-query.ru.md
Jenkins, Kenneth Alexander 835acaa70e
add more docs 
Signed-off-by: Jenkins, Kenneth Alexander <kjenkins60@gatech.edu>
2026-04-10 12:22:20 -04:00

25 KiB
Raw Blame History

Техническая спецификация запросов 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. Кэширует разрешенные отношения в контексте запроса. Поддерживает как прямой, так и обратный обход отношений.

Мониторинг схемы конфигурации

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

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)

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)

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

Простой запрос коллекции

{
  customers(status: "active") {
    customer_id
    name
    email
    registration_date
  }
}

Запрос со связями

{
  orders(order_date_gt: "2024-01-01") {
    order_id
    total_amount
    customer {
      name
      email
    }
    items {
      product_name
      quantity
      price
    }
  }
}

Разделенная на страницы выборка

{
  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: Внутренняя документация