Implementation:Run llama Llama index GraphStore Types
| Knowledge Sources | |
|---|---|
| Domains | Knowledge Graphs, Graph Storage, Type System |
| Last Updated | 2026-02-11 19:00 GMT |
Overview
This module defines the core type system and abstract base classes for graph stores in LlamaIndex, providing data models for graph nodes, relations, triplets, and two graph store protocols (GraphStore and PropertyGraphStore).
Description
The graph_stores/types.py module establishes the foundational type hierarchy for representing and storing knowledge graph data within LlamaIndex. It defines several Pydantic data models and abstract protocols:
LabelledNode is the abstract base model for all graph nodes, providing fields for label, embedding, and properties. Two concrete subclasses are provided: EntityNode (representing named entities with a default label of "entity") and ChunkNode (representing text chunks with a default label of "text_chunk"). Each node subclass implements its own id property and __str__ method.
Relation models a directed edge between two nodes, carrying a label, source_id, target_id, and arbitrary properties. The Triplet type alias represents a tuple of (LabelledNode, Relation, LabelledNode).
LabelledPropertyGraph is an in-memory graph structure that stores nodes and relations in dictionaries keyed by their IDs, with a set of triplet tuples for fast lookup. It provides methods for adding, retrieving, and deleting nodes, relations, and triplets.
GraphStore is a runtime-checkable Protocol class defining the interface for simple triplet-based graph stores. It declares methods such as get, get_rel_map, upsert_triplet, delete, persist, get_schema, and query.
PropertyGraphStore is an ABC (Abstract Base Class) providing a richer interface for labelled property graph stores. It declares abstract methods for get, get_triplets, get_rel_map, upsert_nodes, upsert_relations, delete, structured_query, and vector_query. It also provides concrete helper methods like get_llama_nodes, upsert_llama_nodes, and delete_llama_nodes for converting between LlamaIndex BaseNode objects and graph nodes. Additionally, it includes full async counterparts for all abstract methods that default to calling their synchronous equivalents.
Key constants defined include TRIPLET_SOURCE_KEY, VECTOR_SOURCE_KEY, KG_NODES_KEY, KG_RELATIONS_KEY, and KG_SOURCE_REL for metadata keys used across the graph store system.
Usage
Use these types when building or integrating a knowledge graph store backend with LlamaIndex. Subclass PropertyGraphStore to implement a custom graph database connector (e.g., Neo4j, Neptune). Use GraphStore protocol for simpler triplet-based graph implementations. Use EntityNode, ChunkNode, and Relation to model graph data programmatically.
Code Reference
Source Location
- Repository: Run_llama_Llama_index
- File: llama-index-core/llama_index/core/graph_stores/types.py
- Lines: 1-528
Signature
class LabelledNode(BaseModel):
label: str = Field(default="node", description="The label of the node.")
embedding: Optional[List[float]] = Field(default=None, description="The embeddings of the node.")
properties: Dict[str, Any] = Field(default_factory=dict)
class EntityNode(LabelledNode):
name: str = Field(description="The name of the entity.")
label: str = Field(default="entity", description="The label of the node.")
class ChunkNode(LabelledNode):
text: str = Field(description="The text content of the chunk.")
id_: Optional[str] = Field(default=None, description="The id of the node.")
label: str = Field(default="text_chunk", description="The label of the node.")
class Relation(BaseModel):
label: str
source_id: str
target_id: str
properties: Dict[str, Any] = Field(default_factory=dict)
Triplet = Tuple[LabelledNode, Relation, LabelledNode]
class LabelledPropertyGraph(BaseModel):
nodes: SerializeAsAny[Dict[str, LabelledNode]] = Field(default_factory=dict)
relations: SerializeAsAny[Dict[str, Relation]] = Field(default_factory=dict)
triplets: Set[Tuple[str, str, str]] = Field(default_factory=set)
@runtime_checkable
class GraphStore(Protocol):
schema: str = ""
class PropertyGraphStore(ABC):
supports_structured_queries: bool = False
supports_vector_queries: bool = False
text_to_cypher_template: PromptTemplate = DEFAULT_CYPHER_TEMPALTE
Import
from llama_index.core.graph_stores.types import (
LabelledNode,
EntityNode,
ChunkNode,
Relation,
Triplet,
LabelledPropertyGraph,
GraphStore,
PropertyGraphStore,
)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| label | str | No | The label for a node or relation (defaults vary by subclass) |
| name | str | Yes (EntityNode) | The name of the entity node |
| text | str | Yes (ChunkNode) | The text content of the chunk node |
| source_id | str | Yes (Relation) | The ID of the source node in a relation |
| target_id | str | Yes (Relation) | The ID of the target node in a relation |
| properties | Dict[str, Any] | No | Arbitrary key-value metadata for nodes and relations |
| embedding | Optional[List[float]] | No | Embedding vector for a labelled node |
| ids | Optional[List[str]] | No | Node IDs for filtering in PropertyGraphStore.get |
| entity_names | Optional[List[str]] | No | Entity names for filtering in get_triplets and delete |
| relation_names | Optional[List[str]] | No | Relation names for filtering in get_triplets and delete |
| depth | int | No | Traversal depth for get_rel_map (default 2) |
| limit | int | No | Maximum number of results for get_rel_map (default 30) |
| query | str or VectorStoreQuery | Yes (query methods) | Cypher query string or vector query object |
Outputs
| Name | Type | Description |
|---|---|---|
| nodes | List[LabelledNode] | Retrieved graph nodes matching filter criteria |
| triplets | List[Triplet] | Retrieved triplets as (subject_node, relation, object_node) |
| rel_map | List[Triplet] or Dict[str, List[List[str]]] | Relationship maps at specified depth |
| schema | str or Any | The graph store schema representation |
| vector_results | Tuple[List[LabelledNode], List[float]] | Nodes and scores from vector queries |
Usage Examples
Basic Usage
from llama_index.core.graph_stores.types import (
EntityNode,
ChunkNode,
Relation,
LabelledPropertyGraph,
)
# Create entity nodes
node_a = EntityNode(name="Python", properties={"type": "language"})
node_b = EntityNode(name="LlamaIndex", properties={"type": "framework"})
# Create a relation
rel = Relation(label="USED_BY", source_id=node_a.id, target_id=node_b.id)
# Build an in-memory property graph
graph = LabelledPropertyGraph()
graph.add_triplet((node_a, rel, node_b))
# Retrieve all triplets
triplets = graph.get_triplets()
for subj, relation, obj in triplets:
print(f"{subj} --{relation}--> {obj}")
# Create a chunk node
chunk = ChunkNode(text="LlamaIndex is a data framework for LLMs.", id_="chunk_001")
graph.add_node(chunk)
Implementing a Custom PropertyGraphStore
from llama_index.core.graph_stores.types import (
PropertyGraphStore,
LabelledNode,
Relation,
Triplet,
)
from llama_index.core.vector_stores.types import VectorStoreQuery
from typing import Any, Dict, List, Optional, Sequence, Tuple
class MyGraphStore(PropertyGraphStore):
supports_structured_queries = True
def get(self, properties=None, ids=None) -> List[LabelledNode]:
# Implement retrieval logic
...
def get_triplets(self, entity_names=None, relation_names=None,
properties=None, ids=None) -> List[Triplet]:
...
def get_rel_map(self, graph_nodes, depth=2, limit=30,
ignore_rels=None) -> List[Triplet]:
...
def upsert_nodes(self, nodes: Sequence[LabelledNode]) -> None:
...
def upsert_relations(self, relations: List[Relation]) -> None:
...
def delete(self, entity_names=None, relation_names=None,
properties=None, ids=None) -> None:
...
def structured_query(self, query, param_map=None) -> Any:
...
def vector_query(self, query, **kwargs) -> Tuple[List[LabelledNode], List[float]]:
...