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

---
layout: default
title: "Техническая спецификация контекстов графов"
parent: "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
```

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

```python
# Термин 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` получает необязательное поле графа, чтобы стать квадом:

```python
@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](https://www.w3.org/TR/rdf12-concepts/)
- [RDF-star и SPARQL-star](https://w3c.github.io/rdf-star/)
- [Набор данных RDF](https://www.w3.org/TR/rdf11-concepts/#section-dataset)
```