Orm Guide

ORM Structure Guide

This skill provides context about the ORM structure in narrativegraphs/db/.

Core Concepts

The data model supports two graph paradigms:

Annotation Types (have doc_id directly)

TripletOrm (triplets.py)

• Represents a subject-predicate-object extraction from text
• Has: doc_id, subject_id, predicate_id, object_id, relation_id, cooccurrence_id
• Stores span positions and text for subject, predicate, and object
• Mixes in AnnotationMixin (provides doc_id, timestamp, document relationship)

TupletOrm (tuplets.py)

• Represents an entity-entity cooccurrence extraction
• Has: doc_id, entity_one_id, entity_two_id, cooccurrence_id
• Stores span positions and text for both entities
• Mixes in AnnotationMixin

EntityOccurrenceOrm (entityoccurrences.py)

• Represents a single entity mention/occurrence in text
• Has: doc_id, entity_id, span_start, span_end, span_text
• Relationships: entity (→ EntityOrm), document (→ DocumentOrm)
• Mixes in AnnotationMixin
• Used by EntityOrm to derive alt_labels (alternative surface forms)

Higher-Level ORMs (backed by annotations)

All these mix in AnnotationBackedTextStatsMixin which provides:

• Stats columns: frequency, doc_frequency, spread, adjusted_tf_idf, first_occurrence, last_occurrence
• _annotations property (abstract, returns backing triplets/tuplets)
• doc_ids property (derived from _annotations)

EntityOrm (entities.py)

• Canonical entity (e.g., "Microsoft", "Satya Nadella")
• Relationships:
  • occurrences → EntityOccurrenceOrm (all mentions of this entity)
  • subject_triplets / object_triplets → triplets property
  • _entity_one_tuplets / _entity_two_tuplets → tuplets property
  • subject_relations / object_relations → relations property
  • _entity_one_cooccurrences / _entity_two_cooccurrences → cooccurrences property
• _annotations returns triplets + tuplets (union for both graph types)
• Has alt_labels hybrid property (derived from occurrences span texts)

PredicateOrm (predicates.py)

• Canonical predicate/verb (e.g., "acquired", "announced")
• Relationships: triplets, relations
• _annotations returns triplets
• Has alt_labels hybrid property

RelationOrm (relations.py)

• Canonical relation tuple: (subject_entity, predicate, object_entity)
• Has: subject_id, predicate_id, object_id, significance
• Relationships: subject, predicate, object, triplets
• _annotations returns triplets
• Has alt_labels hybrid property

CooccurrenceOrm (cooccurrences.py)

• Canonical cooccurrence: (entity_one, entity_two) where entity_one_id <= entity_two_id
• Has: entity_one_id, entity_two_id, pmi
• Relationships: entity_one, entity_two, tuplets
• _annotations returns tuplets

DocumentOrm (documents.py)

• Source document with text, str_id, timestamp
• Relationships: triplets, tuplets, entity_occurrences
• Has categories via CategorizableMixin

Mixins (common.py, documents.py)

• CategorizableMixin: Provides category support
• CategoryMixin: Base for category tables (e.g., EntityCategory)
• HasAltLabels: For ORMs with alternative surface forms
• AnnotationMixin: For triplets/tuplets (provides doc_id, document relationship)
• AnnotationBackedTextStatsMixin: For higher-level ORMs (stats + doc_ids)

Relationship Diagram

DocumentOrm
    │
    ├── triplets ──────────► TripletOrm ◄── subject/object ── EntityOrm
    │                            │                              │
    │                            ├── predicate ── PredicateOrm  │
    │                            │                    │         │
    │                            └── relation ─── RelationOrm ◄─┘
    │                                                │
    ├── tuplets ────────────► TupletOrm ◄────────────┼── entity_one/two ── EntityOrm
    │                            │                   │
    │                            └── cooccurrence ── CooccurrenceOrm
    │
    └── entity_occurrences ─► EntityOccurrenceOrm ◄── entity ── EntityOrm

Converted and distributed by TomeVault — claim your Tome and manage your conversions.