Skip to main content

​
Overview

The Relationship class represents an edge in the knowledge graph, connecting two entities. Relationships are extracted from documents and describe how entities are related to each other. Each relationship has a source entity, target entity, and optional weight indicating the strength of the connection. Relationships inherit from the Identified base class, which provides id and short_id fields.

​
Schema

​
Core fields

​
id
string
required
Unique identifier for the relationship.
​
short_id
string | null
Human-readable ID used to refer to this relationship in prompts or texts displayed to users.
​
source
string
required
The source entity name. This is the entity from which the relationship originates.
​
target
string
required
The target entity name. This is the entity to which the relationship points.
​
weight
float
The edge weight indicating the strength or importance of the relationship. Higher values indicate stronger connections.
​
description
string | null
A textual description of the relationship explaining the nature of the connection between source and target entities.

​
Embeddings

​
description_embedding
float[]
The semantic embedding vector for the relationship description. Used for similarity search and semantic queries.

​
Relationships

​
text_unit_ids
string[]
List of text unit IDs in which the relationship appears. Links the relationship back to its source text chunks.

​
Metadata

​
rank
integer
default:1
Rank of the relationship, used for sorting and prioritization. Higher rank indicates more important relationship. This can be based on centrality or other metrics.
​
attributes
object
Additional attributes associated with the relationship. These attributes are included in search prompts and can contain custom metadata.

​
Example

{
  "id": "r1234567-89ab-cdef-0123-456789abcdef",
  "short_id": "0",
  "source": "Microsoft Corporation",
  "target": "Satya Nadella",
  "weight": 0.95,
  "description": "Satya Nadella is the CEO of Microsoft Corporation",
  "description_embedding": [0.123, -0.456, 0.789, ...],
  "text_unit_ids": ["t1", "t2"],
  "rank": 5,
  "attributes": {
    "relationship_type": "leadership",
    "start_date": "2014"
  }
}

​
Creating from dictionary

The Relationship class provides a from_dict() class method to create instances from dictionary data: 
relationship = Relationship.from_dict({
    "id": "r1234567-89ab-cdef-0123-456789abcdef",
    "source": "Microsoft Corporation",
    "target": "Satya Nadella",
    "weight": 0.95,
    "description": "Satya Nadella is the CEO of Microsoft Corporation",
    "rank": 5,
    "text_unit_ids": ["t1", "t2"],
    "attributes": {"relationship_type": "leadership"}
})

​
Use cases

Relationships are used throughout GraphRAG for:
  • Graph traversal: Following connections between entities during search
  • Community detection: Identifying clusters of related entities
  • Importance ranking: Using edge weights to prioritize relevant information
  • Context retrieval: Accessing source text through text_unit_ids

Build docs developers (and LLMs) love

Get started for freeTalk to us