Node Types
Graphiti uses four primary node types to represent different elements in the knowledge graph. All nodes inherit from the baseNode class and share common fields for identification, grouping, and timestamps.
Base Node
The abstract base class that all node types inherit from.Unique identifier for the node. Automatically generated using UUID4 if not provided.
Name of the node.
Partition identifier for the graph. Used to organize nodes into logical groups or namespaces.
List of labels applied to the node. Default: empty list.
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 fromNode, plus:
Vector embedding of the entity name, used for semantic similarity searches. Generated using the configured embedder client.
Regional summary of surrounding edges and relationships. Default: empty string.
Additional attributes of the node. Content depends on node labels and can store custom properties extracted from episodes.
Methods
Generates and stores the name embedding for this entity.Parameters:
embedder: EmbedderClient- The embedder client to use for generating embeddings
list[float] - The generated embedding vectorLoads the name embedding from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
NodeNotFoundError if the node doesn’t existPersists the entity node to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
Retrieves a single entity node by UUID.Parameters:
driver: GraphDriveruuid: str
EntityNodeRaises: NodeNotFoundError if not foundRetrieves multiple entity nodes by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[EntityNode]Retrieves entity nodes by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_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)
list[EntityNode]EpisodicNode
Represents raw episodes (events or documents) that have been processed into the knowledge graph.Fields
Inherits all fields fromNode, plus:
The type/source of the episode. See EpisodeType for available values.
Description of the data source for this episode.
Raw episode data/content.
Timestamp of when the original document was created or when the event occurred.
List of entity edge UUIDs referenced in this episode. Default: empty list.
Methods
Persists the episodic node to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
Retrieves a single episodic node by UUID.Parameters:
driver: GraphDriveruuid: str
EpisodicNodeRaises: NodeNotFoundError if not foundRetrieves multiple episodic nodes by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[EpisodicNode]Retrieves episodic nodes by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[EpisodicNode]Retrieves all episodic nodes that mention a specific entity.Parameters:
driver: GraphDriverentity_node_uuid: str- UUID of the entity node
list[EpisodicNode]CommunityNode
Represents a community or cluster of related entities in the knowledge graph.Fields
Inherits all fields fromNode, plus:
Vector embedding of the community name, used for semantic similarity searches.
Regional summary of member nodes and their relationships. Default: empty string.
Methods
Persists the community node to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Generates and stores the name embedding for this community.Parameters:
embedder: EmbedderClient- The embedder client to use for generating embeddings
list[float] - The generated embedding vectorLoads the name embedding from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
NodeNotFoundError if the node doesn’t existClass Methods
Retrieves a single community node by UUID.Parameters:
driver: GraphDriveruuid: str
CommunityNodeRaises: NodeNotFoundError if not foundRetrieves multiple community nodes by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[CommunityNode]Retrieves community nodes by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[CommunityNode]SagaNode
Represents a saga, which is a collection of related episodes forming a narrative thread.Fields
Inherits all fields fromNode with no additional fields.
Methods
Persists the saga node to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Deletes the saga node from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
Retrieves a single saga node by UUID.Parameters:
driver: GraphDriveruuid: str
SagaNodeRaises: NodeNotFoundError if not foundRetrieves multiple saga nodes by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[SagaNode]Retrieves saga nodes by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[SagaNode]Common Node Operations
All node types support the following operations:Delete Operations
Deletes the node and its relationships from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Deletes all nodes of this type within a group.Parameters:
driver: GraphDrivergroup_id: strbatch_size: int- Number of nodes to delete per batch (default: 100)
Deletes multiple nodes by their UUIDs.Parameters:
driver: GraphDriveruuids: list[str]batch_size: int- Number of nodes to delete per batch (default: 100)
Helper Functions
Batch generates embeddings for multiple entity nodes.Parameters:
embedder: EmbedderClientnodes: list[EntityNode]
Related
- Edge Types - Learn about edge types that connect nodes
- Episodes - Learn about episode types and processing
- Search - Search across nodes in the knowledge graph