Skip to main content

​
Node Types

Graphiti uses four primary node types to represent different elements in the knowledge graph. All nodes inherit from the base Node class and share common fields for identification, grouping, and timestamps.

​
Base Node

The abstract base class that all node types inherit from.
​
str
required
Unique identifier for the node. Automatically generated using UUID4 if not provided.
​
str
required
Name of the node.
​
str
required
Partition identifier for the graph. Used to organize nodes into logical groups or namespaces.
​
list[str]
List of labels applied to the node. Default: empty list.
​
datetime
Timestamp of when the node was created. Automatically set to current UTC time if not provided.

​
EntityNode

Represents entities extracted from episodes, such as people, places, organizations, or concepts.

​
Fields

Inherits all fields from Node, plus:
​
list[float] | None
Vector embedding of the entity name, used for semantic similarity searches. Generated using the configured embedder client.
​
str
Regional summary of surrounding edges and relationships. Default: empty string.
​
dict[str, Any]
Additional attributes of the node. Content depends on node labels and can store custom properties extracted from episodes.

​
Methods

​
async method
Generates and stores the name embedding for this entity.Parameters:
  • embedder: EmbedderClient - The embedder client to use for generating embeddings
Returns: list[float] - The generated embedding vector
​
async method
Loads the name embedding from the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance
Raises: NodeNotFoundError if the node doesn’t exist
​
async method
Persists the entity node to the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance

​
Class Methods

​
async classmethod
Retrieves a single entity node by UUID.Parameters:
  • driver: GraphDriver
  • uuid: str
Returns: EntityNodeRaises: NodeNotFoundError if not found
​
async classmethod
Retrieves multiple entity nodes by UUIDs.Parameters:
  • driver: GraphDriver
  • uuids: list[str]
Returns: list[EntityNode]
​
async classmethod
Retrieves entity nodes by group IDs with optional pagination.Parameters:
  • driver: GraphDriver
  • group_ids: list[str]
  • limit: int | None - Maximum number of results (optional)
  • uuid_cursor: str | None - UUID cursor for pagination (optional)
  • with_embeddings: bool - Whether to include embeddings (default: False)
Returns: list[EntityNode]

​
EpisodicNode

Represents raw episodes (events or documents) that have been processed into the knowledge graph.

​
Fields

Inherits all fields from Node, plus:
​
EpisodeType
required
The type/source of the episode. See EpisodeType for available values.
​
str
required
Description of the data source for this episode.
​
str
required
Raw episode data/content.
​
datetime
required
Timestamp of when the original document was created or when the event occurred.
​
list[str]
List of entity edge UUIDs referenced in this episode. Default: empty list.

​
Methods

​
async method
Persists the episodic node to the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance

​
Class Methods

​
async classmethod
Retrieves a single episodic node by UUID.Parameters:
  • driver: GraphDriver
  • uuid: str
Returns: EpisodicNodeRaises: NodeNotFoundError if not found
​
async classmethod
Retrieves multiple episodic nodes by UUIDs.Parameters:
  • driver: GraphDriver
  • uuids: list[str]
Returns: list[EpisodicNode]
​
async classmethod
Retrieves episodic nodes by group IDs with optional pagination.Parameters:
  • driver: GraphDriver
  • group_ids: list[str]
  • limit: int | None - Maximum number of results (optional)
  • uuid_cursor: str | None - UUID cursor for pagination (optional)
Returns: list[EpisodicNode]
​
async classmethod
Retrieves all episodic nodes that mention a specific entity.Parameters:
  • driver: GraphDriver
  • entity_node_uuid: str - UUID of the entity node
Returns: list[EpisodicNode]

​
CommunityNode

Represents a community or cluster of related entities in the knowledge graph.

​
Fields

Inherits all fields from Node, plus:
​
list[float] | None
Vector embedding of the community name, used for semantic similarity searches.
​
str
Regional summary of member nodes and their relationships. Default: empty string.

​
Methods

​
async method
Persists the community node to the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance
​
async method
Generates and stores the name embedding for this community.Parameters:
  • embedder: EmbedderClient - The embedder client to use for generating embeddings
Returns: list[float] - The generated embedding vector
​
async method
Loads the name embedding from the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance
Raises: NodeNotFoundError if the node doesn’t exist

​
Class Methods

​
async classmethod
Retrieves a single community node by UUID.Parameters:
  • driver: GraphDriver
  • uuid: str
Returns: CommunityNodeRaises: NodeNotFoundError if not found
​
async classmethod
Retrieves multiple community nodes by UUIDs.Parameters:
  • driver: GraphDriver
  • uuids: list[str]
Returns: list[CommunityNode]
​
async classmethod
Retrieves community nodes by group IDs with optional pagination.Parameters:
  • driver: GraphDriver
  • group_ids: list[str]
  • limit: int | None - Maximum number of results (optional)
  • uuid_cursor: str | None - UUID cursor for pagination (optional)
Returns: list[CommunityNode]

​
SagaNode

Represents a saga, which is a collection of related episodes forming a narrative thread.

​
Fields

Inherits all fields from Node with no additional fields.

​
Methods

​
async method
Persists the saga node to the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance
​
async method
Deletes the saga node from the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance

​
Class Methods

​
async classmethod
Retrieves a single saga node by UUID.Parameters:
  • driver: GraphDriver
  • uuid: str
Returns: SagaNodeRaises: NodeNotFoundError if not found
​
async classmethod
Retrieves multiple saga nodes by UUIDs.Parameters:
  • driver: GraphDriver
  • uuids: list[str]
Returns: list[SagaNode]
​
async classmethod
Retrieves saga nodes by group IDs with optional pagination.Parameters:
  • driver: GraphDriver
  • group_ids: list[str]
  • limit: int | None - Maximum number of results (optional)
  • uuid_cursor: str | None - UUID cursor for pagination (optional)
Returns: list[SagaNode]

​
Common Node Operations

All node types support the following operations:

​
Delete Operations

​
async method
Deletes the node and its relationships from the graph database.Parameters:
  • driver: GraphDriver - The graph driver instance
​
async classmethod
Deletes all nodes of this type within a group.Parameters:
  • driver: GraphDriver
  • group_id: str
  • batch_size: int - Number of nodes to delete per batch (default: 100)
​
async classmethod
Deletes multiple nodes by their UUIDs.Parameters:
  • driver: GraphDriver
  • uuids: list[str]
  • batch_size: int - Number of nodes to delete per batch (default: 100)

​
Helper Functions

​
async function
Batch generates embeddings for multiple entity nodes.Parameters:
  • embedder: EmbedderClient
  • nodes: list[EntityNode]
Filters out nodes with empty names and generates embeddings for the remaining nodes in batch.
  • Edge Types - Learn about edge types that connect nodes
  • Episodes - Learn about episode types and processing
  • Search - Search across nodes in the knowledge graph