Skip to main content

​
Overview

The Entity class represents a node in the knowledge graph. Entities are extracted from documents and represent real-world objects, concepts, or actors mentioned in the text. Each entity can be associated with multiple communities, text units, and has optional embeddings for semantic search. Entities inherit from the Named base class, which provides id, short_id, and title fields.

​
Schema

​
Core fields

​
id
string
required
Unique identifier for the entity.
​
short_id
string | null
Human-readable ID used to refer to this entity in prompts or texts displayed to users, such as in a report text.
​
title
string
required
The name/title of the entity.
​
type
string | null
Type of the entity. Can be any string representing the entity category (e.g., “Person”, “Organization”, “Location”).
​
description
string | null
Textual description of the entity explaining its role, characteristics, or context.

​
Embeddings

​
description_embedding
float[]
The semantic (text) embedding vector of the entity’s description. Used for similarity search and semantic queries.
​
name_embedding
float[]
The semantic (text) embedding vector of the entity’s name. Used for entity matching and retrieval.

​
Relationships

​
community_ids
string[]
List of community IDs that this entity belongs to. Entities can be members of multiple communities at different hierarchical levels.
​
text_unit_ids
string[]
List of text unit IDs in which the entity appears. Links the entity back to its source text chunks.

​
Metadata

​
rank
integer
default:1
Rank of the entity, used for sorting and prioritization. Higher rank indicates more important entity. This can be based on centrality metrics or other importance measures.
​
attributes
object
Additional attributes associated with the entity (e.g., start time, end time, custom metadata). These attributes are included in search prompts.

​
Example

{
  "id": "e1234567-89ab-cdef-0123-456789abcdef",
  "short_id": "0",
  "title": "Microsoft Corporation",
  "type": "Organization",
  "description": "A multinational technology company that develops software, hardware, and cloud services",
  "description_embedding": [0.123, -0.456, 0.789, ...],
  "name_embedding": [0.234, -0.567, 0.890, ...],
  "community_ids": ["c1", "c2"],
  "text_unit_ids": ["t1", "t2", "t3"],
  "rank": 10,
  "attributes": {
    "founded": "1975",
    "industry": "Technology"
  }
}

​
Creating from dictionary

The Entity class provides a from_dict() class method to create instances from dictionary data: 
entity = Entity.from_dict({
    "id": "e1234567-89ab-cdef-0123-456789abcdef",
    "title": "Microsoft Corporation",
    "type": "Organization",
    "description": "A multinational technology company",
    "degree": 10,  # Maps to rank
    "community": ["c1", "c2"],  # Maps to community_ids
    "text_unit_ids": ["t1", "t2"],
    "attributes": {"founded": "1975"}
})

Build docs developers (and LLMs) love

Get started for freeTalk to us