Custom Entity and Edge Types
Graphiti allows you to define custom entity types and edge types to better represent your domain-specific knowledge. This enables more structured data extraction and richer semantic relationships in your knowledge graph.
Defining Custom Entity and Edge Types
Custom entity types and edge types are defined using Pydantic models. Each model represents a specific type with custom attributes.
Using Custom Entity and Edge Types
Pass your custom entity types and edge types to the add_episode method:
Searching with Custom Types
You can filter search results to specific entity types or edge types using SearchFilters:
How Custom Types Work
Entity Extraction Process
- Extraction: Graphiti extracts entities from text and classifies them using your custom types
- Validation: Each entity is validated against the appropriate Pydantic model
- Attribute Population: Custom attributes are extracted from the text and populated
- Storage: Entities are stored with their custom attributes
Edge Extraction Process
- Relationship Detection: Graphiti identifies relationships between extracted entities
- Type Classification: Based on the entity types involved and your edge_type_map, relationships are classified
- Attribute Extraction: For custom edge types, additional attributes are extracted from the context
- Validation: Edge attributes are validated against the Pydantic model
- Storage: Edges are stored with their custom attributes and relationship metadata
Edge Type Mapping
The edge_type_map parameter defines which edge types can exist between specific entity type pairs:
If an entity pair doesn’t have a defined edge type mapping, Graphiti will use default relationship types and the relationship will still be captured with a generic RELATES_TO type.
Schema Evolution
Your knowledge graph’s schema can evolve over time as your needs change. You can update entity types by adding new attributes to existing types without breaking existing nodes. When you add new attributes, existing nodes will preserve their original attributes while supporting the new ones for future updates. This flexible approach allows your knowledge graph to grow and adapt while maintaining backward compatibility with historical data.
For example, if you initially defined a “Customer” type with basic attributes like name and email, you could later add attributes like “loyalty_tier” or “acquisition_channel” without needing to modify or migrate existing customer nodes in your graph.
Best Practices
Model Design
- Clear Descriptions: Always include detailed descriptions in docstrings and Field descriptions
- Optional Fields: Make custom attributes optional to handle cases where information isn’t available
- Appropriate Types: Use specific types (datetime, int, float) rather than strings when possible
- Validation: Consider adding Pydantic validators for complex validation rules
- Atomic Attributes: Attributes should be broken down into their smallest meaningful units rather than storing compound information
Instead of compound information:
Use atomic attributes:
Naming Conventions
- Entity Types: Use PascalCase (e.g., Person, TechCompany)
- Edge Types: Use PascalCase for custom types (e.g., Employment, Partnership)
- Attributes: Use snake_case (e.g., start_date, employee_count)
- Descriptions: Be specific and actionable for the LLM
- Consistency: Maintain consistent naming conventions across related entity types
Edge Type Mapping Strategy
- Specific Mappings: Define specific entity type pairs for targeted relationships
- Fallback to Entity: Use (“Entity”, “Entity”) as a fallback for general relationships
- Balanced Scope: Don’t make edge types too specific or too general
- Domain Coverage: Ensure your edge types cover the main relationships in your domain
Entity Type Exclusion
You can exclude specific entity types from extraction using the excluded_entity_types parameter:
Migration Guide
If you’re upgrading from a previous version of Graphiti:
- You can add entity types to new episodes, even if existing episodes in the graph did not have entity types. Existing nodes will continue to work without being classified.
- To add types to previously ingested data, you need to re-ingest it with entity types set into a new graph.
Important Constraints
Protected Attribute Names
Custom entity type attributes cannot use protected names that are already used by Graphiti’s core EntityNode class:
uuid
,name
,group_id
,labels
,created_at
,summary
,attributes
,name_embedding
Custom entity types and edge types provide powerful ways to structure your knowledge graph according to your domain needs. They enable more precise extraction, better organization, and richer semantic relationships in your data.