apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-25 16:36:21 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
trustgraph/docs/tech-specs/ru/graphql-query.ru.md
cybermaggedon e7efb673ef
Structure the tech specs directory (#836) 
Tech spec some subdirectories for different languages
2026-04-21 16:06:41 +01:00

34 KiB
Raw Blame History

layout title parent
default Техническая спецификация запросов GraphQL 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 при изменении конфигурации.

  4. Исполнитель запросов Разбирает входящие запросы GraphQL с использованием библиотеки Strawberry.

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

  1. Транслятор запросов Cassandra Преобразует выборки GraphQL в запросы CQL. Оптимизирует запросы на основе доступных индексов и первичных ключей. Обрабатывает фильтрацию, пагинацию и сортировку. Управляет пулом соединений и жизненным циклом сессии.

  2. Разрешитель отношений Реализует решатели полей для отношений между объектами. Выполняет эффективную пакетную загрузку для предотвращения запросов 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 <<<<<<< HEAD Создание запроса CQL с правильными предложениями WHERE ======= Построение запроса CQL с правильными предложениями WHERE

82edf2d (New md files from RunPod) Включение коллекции в ключ партиции Применение фильтров на основе аргументов GraphQL

  1. Выполнение запроса: Выполнение запроса CQL к Cassandra Отображение результатов в структуру ответа GraphQL Разрешение любых полей отношений Форматирование ответа в соответствии со спецификацией GraphQL

  2. Доставка ответа: Создание 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
  }
}

<<<<<<< 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-поля =======

  6. Считывать существующие схемы из конфигурации. Подключаться к существующим таблицам Cassandra, созданным модулем хранения.

  7. Начинать принимать запросы сразу после развертывания.

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

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

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

Поддержка федерации: Должен ли сервис поддерживать федерацию 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)