koan-relationships
Entity navigation, batch loading, relationship best practices
When & Why to Use This Skill
This Claude skill provides comprehensive patterns and best practices for managing entity relationships in software development. It focuses on efficient data navigation, implementing batch loading to eliminate N+1 query performance issues, and structuring one-to-many or hierarchical relationships without the overhead of complex ORM configurations. By following these entity-first principles, developers can build high-performance, maintainable data access layers.
Use Cases
- Performance Optimization: Identifying and resolving N+1 query problems in data-driven applications by implementing efficient batch loading techniques.
- Data Modeling: Implementing robust one-to-many and hierarchical (parent-child) relationship patterns using foreign keys and navigation helpers.
- Clean Code Architecture: Designing entity-first data access layers that prioritize readability and maintainability without relying on heavy ORM mapping configurations.
- Handling Optionality: Correctly managing optional relationships and ensuring null-safe data retrieval within complex entity graphs.
- Hierarchical Data Management: Structuring parent-child entities with proper sorting and retrieval logic for complex data trees.
| name | koan-relationships |
|---|---|
| description | Entity navigation, batch loading, relationship best practices |
Koan Relationships
Core Principle
Relationships use foreign keys + navigation helpers. Batch load to prevent N+1 queries. No ORM mapping configuration needed.
Relationship Patterns
One-to-Many
public class User : Entity<User>
{
public string Name { get; set; } = "";
public Task<List<Todo>> GetTodos(CancellationToken ct = default) =>
Todo.Query(t => t.UserId == Id, ct);
}
public class Todo : Entity<Todo>
{
public string UserId { get; set; } = "";
public Task<User?> GetUser(CancellationToken ct = default) =>
User.Get(UserId, ct);
}
Preventing N+1 Queries
// ❌ WRONG: N+1 query problem
foreach (var todo in todos)
{
var user = await todo.GetUser(); // N queries!
}
// ✅ CORRECT: Batch load
var userIds = todos.Select(t => t.UserId).Distinct().ToArray();
var users = await User.Get(userIds);
var userDict = users.Where(u => u != null).ToDictionary(u => u!.Id);
foreach (var todo in todos)
{
var user = userDict[todo.UserId];
}
Optional Relationships
public class Todo : Entity<Todo>
{
public string? CategoryId { get; set; }
public Task<Category?> GetCategory(CancellationToken ct = default) =>
string.IsNullOrEmpty(CategoryId) ? Task.FromResult<Category?>(null)
: Category.Get(CategoryId, ct);
}
Hierarchical (Parent-Child)
public class TodoItem : Entity<TodoItem>
{
public string TodoId { get; set; } = "";
public int SortOrder { get; set; }
public Task<Todo?> GetParentTodo(CancellationToken ct = default) =>
Todo.Get(TodoId, ct);
}
public class Todo : Entity<Todo>
{
public Task<List<TodoItem>> GetItems(CancellationToken ct = default) =>
TodoItem.Query(i => i.TodoId == Id, ct)
.ContinueWith(t => t.Result.OrderBy(i => i.SortOrder).ToList());
}
When This Skill Applies
- ✅ Complex data relationships
- ✅ Navigation patterns
- ✅ Performance optimization (N+1)
- ✅ Hierarchical data
- ✅ Optional relationships
Reference Documentation
- Example Code:
.claude/skills/entity-first/examples/entity-relationships.cs - Sample:
samples/S1.Web/README.md(Relationship demo)