trustgraph/docs/tech-specs/graph-contexts.ru.md

layout	title	parent
default	Техническая спецификация контекстов графов	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 для
соответствия RDF 1.2 и поддержки полной семантики набора данных RDF. Это
радикальное изменение для серии выпусков 2.x.

### Версионирование

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

Гибкость в отношении зрелости намеренна - ранние пользователи могут получить
доступ к новым возможностям, прежде чем все функции будут полностью
проверены.

## Цели

Основные цели этой работы - обеспечить возможность добавления метаданных к
фактам/утверждениям:

- **Временная информация**: Связывание фактов со временными метаданными
  - Когда факт считался истинным
  - Когда факт стал истинным
  - Когда факт был признан ложным

- **Происхождение/Источники**: Отслеживание источников, подтверждающих факт
  - "Этот факт подтверждается источником X"
  - Связывание фактов с исходными документами

- **Достоверность/Надежность**: Запись утверждений об истинности
  - "Пользователь P заявил, что это было правдой"
  - "Пользователь Q утверждает, что это неправда"
  - Обеспечение оценки надежности и обнаружения конфликтов

**Гипотеза**: Реификация (RDF-star / цитируемые тройки) является ключевым
механизмом для достижения этих результатов, поскольку все они требуют
создания утверждений об утверждениях.

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

Чтобы выразить фразу "факт (Алиса знает Боба) был обнаружен 15 января 2024 года"
или "источник X поддерживает утверждение (Y вызывает Z)", необходимо
обращаться к ребру как к чему-то, о чем можно делать утверждения. Стандартные
тройки не поддерживают это.

### Текущие ограничения

Текущий класс `Value` в `trustgraph-base/trustgraph/schema/core/primitives.py`
может представлять:
- URI-узлы (`is_uri=True`)
- Литеральные значения (`is_uri=False`)

Поле `type` существует, но не используется для представления типов данных XSD.

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

### Функции RDF для поддержки

#### Основные функции (связанные с целями реификации)

Эти функции напрямую связаны с целями временной информации, происхождения и
достоверности:

1. **Цитируемые тройки RDF 1.2 (RDF-star)**
   - Ребра, указывающие на другие ребра
   - Тройка может быть субъектом или объектом другой тройки
   - Позволяет делать утверждения об утверждениях (реификация)
   - Основной механизм для аннотирования отдельных фактов

2. **Набор данных RDF / Именованные графы**
   - Поддержка нескольких именованных графов внутри набора данных
   - Каждый граф идентифицируется IRI
   - Переход от троек (s, p, o) к квадам (s, p, o, g)
   - Включает граф по умолчанию и ноль или более именованных графов
   - IRI графа может быть субъектом в утверждениях, например:
     ```
     <graph-source-A> <discoveredOn> "2024-01-15"
     <graph-source-A> <hasVeracity> "high"
     ```
   - Обратите внимание: Именованные графы - это отдельная функция от
     реификации. Они имеют другие применения (разделение, контроль доступа,
     организация набора данных) и должны рассматриваться как отдельная
     возможность.

3. **Анонимные узлы** (Ограниченная поддержка)
   - Анонимные узлы без глобального URI
   - Поддерживаются для совместимости при загрузке внешних данных RDF
   - **Ограниченный статус**: Без гарантий стабильной идентичности после
     загрузки
   - Находите их с помощью запросов по подстановочным знакам (сопоставляйте по
     связям, а не по ID)
   - Не являются основной функцией - не полагайтесь на точную обработку
     анонимных узлов

#### Временные исправления (радикальное изменение в 2.0)

Эти функции не связаны напрямую с целями реификации, но являются ценными
улучшениями, которые следует включить при внесении радикальных изменений:

4. **Типы литералов**
   - Правильное использование поля `type` для типов данных XSD
   - Примеры: xsd:string, xsd:integer, xsd:dateTime и т.д.
   - Исправляет текущее ограничение: невозможно правильно представлять даты
     или целые числа

5. **Языковые теги**
   - Поддержка языковых атрибутов для строковых литералов (@en, @fr и т.д.)
   - Обратите внимание: у литерала либо языковой тег, ЛИБО тип данных, но не
     оба (за исключением rdf:langString)
   - Важно для сценариев использования ИИ/многоязычности

### Модели данных

#### Термин (переименование из Value)

Класс `Value` будет переименован в `Term`, чтобы лучше отражать терминологию
RDF. Это переименование имеет две цели:
1. Согласование наименований с концепциями RDF ( "Term" может быть IRI,
   литералом, анонимным узлом или цитируемой тройкой - а не просто
   "значением")
2. Вызывает проверку кода на интерфейсе радикальных изменений - любой код,
   который все еще ссылается на `Value`, явно не работает и требует
   обновления

Термин может представлять:

- **IRI/URI** - Именованный узел/ресурс
- **Анонимный узел** - Анонимный узел с локальной областью
- **Литерал** - Значение данных с одним из следующих:
  - Тип данных (тип XSD) ИЛИ
  - Языковой тег
- **Цитируемая тройка** - Тройка, используемая в качестве термина (RDF 1.2)

##### Выбранный подход: Одиночный класс с дискриминатором типа

Структура определяется требованиями сериализации - в формате передачи данных
необходим дискриминатор типа, независимо от представления на Python.
Одиночный класс с полем типа - это естественный выбор и соответствует
текущему шаблону `Value`.

Односимвольный код типа обеспечивает компактную сериализацию:

```python
from dataclasses import dataclass

# Константы типа Term
IRI = "i"      # IRI/URI узел
BLANK = "b"    # Анонимный узел
LITERAL = "l"  # Литеральное значение
TRIPLE = "t"   # Цитируемая тройка (RDF 1.2)

@dataclass
class Term:
    type: str = ""  # Один из: IRI, BLANK, LITERAL, TRIPLE

    # Для терминов IRI (type == IRI)
    iri: str = ""

    # Для анонимных узлов (type == BLANK)
    id: str = ""

    # Для литералов (type == LITERAL)
    value: str = ""
    datatype: str = ""   # URI типа данных XSD (взаимно исключающееся с language)
    language: str = ""   # Языковой тег (взаимно исключающееся с datatype)

    # Для цитируемых троек (type == TRIPLE)
    triple: "Triple | None" = None

Примеры использования:

# Термин IRI
node = Term(type=IRI, iri="http://example.org/Alice")

# Литерал с типом данных
age = Term(type=LITERAL, value="42", datatype="xsd:integer")

# Литерал с языковым тегом
label = Term(type=LITERAL, value="Hello", language="en")

# Анонимный узел
anon = Term(type=BLANK, id="_:b1")

# Цитируемая тройка (утверждение об утверждении)
inner = Triple(
    s=Term(type=IRI, iri="http://example.org/Alice"),
    p=Term(type=IRI, iri="http://example.org/knows"),
    o=Term(type=IRI, iri="http://example.org/Bob"),
)
reified = Term(type=TRIPLE, triple=inner)

Рассмотренные альтернативы

Вариант B: Объединение специализированных классов (Term = IRI | BlankNode | Literal | QuotedTriple)

• Отклонено: Сериализация все равно потребует дискриминатора типа, что увеличивает сложность

Вариант C: Базовый класс с подклассами

• Отклонено: Та же проблема с сериализацией, а также особенности наследования dataclass

Тройка / Квад

Класс Triple получает необязательное поле графа, чтобы стать квадом:

@dataclass
class Triple:
    s: Term | None = None    # Subject
    p: Term | None = None    # Predicate
    o: Term | None = None    # Object
    g: str | None = None     # Имя графа (IRI), None = граф по умолчанию

Решения в дизайне:

• Имя поля: g для согласованности с s, p, o
• Необязательно: None означает граф по умолчанию (неименованный)
• Тип: Обычная строка (IRI) вместо Term
  • Имена графов всегда являются IRI
  • Анонимные узлы в качестве имен графов не допускаются (слишком путано)
  • Нет необходимости в полной машинерии Term

Обратите внимание: Имя класса остается Triple, даже если технически это квад. Это позволяет избежать изменений и "тройка" по-прежнему является общепринятым термином. Контекст графа является метаданными о том, где находится тройка.

Шаблоны запросов

Текущий движок запросов принимает комбинации терминов S, P, O. С цитируемыми тройками сама тройка может быть допустимым термином в этих позициях. Ниже приведены примеры шаблонов запросов, поддерживающих исходные цели.

Семантика параметров графа

В соответствии с соглашениями SPARQL для обратной совместимости:

• g опущено / None: Запрос только к графу по умолчанию
• g = конкретный IRI: Запрос только к этому именованному графу
• g = подстановочный знак / *: Запрос по всем графам (эквивалентно SPARQL GRAPH ?g { ... })

Это позволяет выполнять простые запросы простыми и делает запросы именованных графов опциональными.

Запросы между графами (g=подстановочный знак) полностью поддерживаются. Схема Cassandra включает специализированные таблицы (SPOG, POSG, OSPG), где g является столбцом кластеризации, а не ключом раздела, что обеспечивает эффективные запросы по всем графам.

Временные запросы

Найти все факты, обнаруженные после определенной даты:

S: ?                                    # любая цитируемая тройка
P: <discoveredOn>
O: > "2024-01-15"^^xsd:date             # сравнение даты

Найти, когда определенный факт считался истинным:

S: << <Alice> <knows> <Bob> >>          # цитируемая тройка как субъект
P: <believedTrueFrom>
O: ?                                    # возвращает дату

Найти факты, которые были признаны ложными:

S: ?                                    # любая цитируемая тройка
P: <discoveredFalseOn>
O: ?                                    # имеет любое значение (существует)

Запросы происхождения

Найти все факты, подтвержденные определенным источником:

S: ?                                    # любая цитируемая тройка
P: <supportedBy>
O: <source:document-123>

Найти, какие источники подтверждают определенный факт:

S: << <DrugA> <treats> <DiseaseB> >>    # цитируемая тройка как субъект
P: <supportedBy>
O: ?                                    # возвращает IRI источника

Запросы достоверности

Найти утверждения, которые пользователь отметил как истинные:

S: ?                                    # любая цитируемая тройка
P: <assertedTrueBy>
O: <person:Alice>

Найти конфликтующие утверждения (один и тот же факт, разная достоверность):

# Первый запрос: факты, отмеченные как истинные
S: ?
P: <assertedTrueBy>
O: ?

# Второй запрос: факты, отмеченные как ложные
S: ?
P: <assertedFalseBy>
O: ?

# Логика приложения: найти пересечение субъектов

Найти факты со значением надежности ниже определенного значения:

• Vector store impact

S: ?
P: <value>
O: <threshold>

Граница хранилища векторов

Хранилища векторов всегда ссылаются только на IRI:

• Никогда на ребра (цитируемые тройки)
• Никогда на литеральные значения
• Никогда на анонимные узлы

Это упрощает хранилище векторов - оно обрабатывает семантическое сходство именованных сущностей. Структура графа обрабатывает отношения, реификацию и метаданные. Цитируемые тройки и именованные графы не усложняют операции с векторами.

Соображения безопасности

Именованные графы не являются функцией безопасности. Пользователи и коллекции остаются границами безопасности. Именованные графы предназначены исключительно для организации данных и поддержки реификации.

Соображения производительности

• Цитируемые тройки добавляют глубину вложенности - могут повлиять на производительность запросов
• Необходимы стратегии индексирования именованных графов для эффективных запросов, охватывающих графы
• Проект схемы Cassandra должен учитывать эффективное хранение квадов.

Vector store boundary

Vector stores always reference IRIs only:

• Never edges (quoted triples)
• Never literal values
• Never blank nodes

This keeps the vector store simple - it handles semantic similarity of named entities. The graph structure handles relationships, reification, and metadata. Quoted triples and named graphs don't complicate vector operations.

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

Используйте существующую стратегию тестирования. Поскольку это радикальное изменение, особое внимание уделяется комплексному набору тестов для проверки правильности работы новых структур во всех компонентах.

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

• 2.0 - это радикальное изменение; обратная совместимость не требуется
• Существующие данные могут потребовать миграции на новую схему (будет определено на основе окончательного проекта)
• Рассмотрите возможность использования инструментов миграции для преобразования существующих троек

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

• Анонимные узлы: Подтверждена ограниченная поддержка. Возможно, потребуется определить стратегию сколемизации (генерировать IRI при загрузке или сохранять идентификаторы анонимных узлов).
• Синтаксис запросов: Какой конкретный синтаксис используется для указания цитируемых троек в запросах? Необходимо определить API запросов.
• Словарь предикатов: Решено. Допускаются любые допустимые предикаты RDF, включая пользовательские. Минимальные предположения о валидности RDF. Очень мало жестко заданных значений (например, rdfs:label используется в некоторых местах). Стратегия: избегать фиксирования чего-либо, если это абсолютно необходимо.
• Влияние на хранилище векторов: Решено. Хранилища векторов всегда указывают только на IRI - никогда на ребра, литеральные значения или анонимные узлы. Цитируемые тройки и реификация не влияют на хранилище векторов.
• Семантика именованных графов: Решено. Запросы по умолчанию выполняются к графу по умолчанию (соответствует поведению SPARQL, обратная совместимость). Требуется явный параметр графа для запросов к именованным графам или ко всем графам.

Ссылки

• Концепции RDF 1.2
• RDF-star и SPARQL-star
• Набор данных RDF