Koan Performance

Core Principle

Optimize for scale from day one. Use streaming for large datasets, batch operations for bulk changes, fast counts for UI, and pagination for web APIs.

Performance Patterns

Streaming (Large Datasets)

csharp
1// ❌ WRONG: Load everything into memory
2var allTodos = await Todo.All(); // 1 million records!
3
4// ✅ CORRECT: Stream in batches
5await foreach (var todo in Todo.AllStream(batchSize: 1000))
6{
7    await ProcessTodo(todo);
8}

Count Strategies

csharp
1// Fast count (metadata estimate - 1000x+ faster)
2var fast = await Todo.Count.Fast(ct); // ~5ms for 10M rows
3
4// Exact count (guaranteed accuracy)
5var exact = await Todo.Count.Exact(ct); // ~25s for 10M rows
6
7// Optimized (framework chooses)
8var optimized = await Todo.Count; // Uses Fast if available

Use Fast for: Pagination UI, dashboards, estimates Use Exact for: Critical business logic, reports, inventory

Bulk Operations

csharp
1// Bulk create
2var todos = Enumerable.Range(1, 1000)
3    .Select(i => new Todo { Title = $"Task {i}" })
4    .ToList();
5await todos.Save(); // Single operation
6
7// Bulk removal
8await Todo.RemoveAll(RemoveStrategy.Fast); // TRUNCATE/DROP (225x faster)

Batch Retrieval

csharp
1// ❌ WRONG: N queries
2foreach (var id in ids)
3{
4    var todo = await Todo.Get(id);
5}
6
7// ✅ CORRECT: 1 query
8var todos = await Todo.Get(ids);

Pagination

csharp
1public async Task<IActionResult> GetTodos(
2    int page = 1,
3    int pageSize = 20,
4    CancellationToken ct = default)
5{
6    var result = await Todo.QueryWithCount(
7        t => !t.Completed,
8        new DataQueryOptions { OrderBy = nameof(Todo.Created), Descending = true },
9        ct);
10
11    Response.Headers["X-Total-Count"] = result.TotalCount.ToString();
12    return Ok(result.Items);
13}

Performance Benchmarks

When This Skill Applies

• ✅ Performance tuning
• ✅ Large datasets
• ✅ Optimization
• ✅ Production readiness
• ✅ Memory issues
• ✅ Query optimization

Reference Documentation

• Example Code: .claude/skills/entity-first/examples/batch-operations.cs
• Guide: docs/guides/performance.md
• Sample: samples/S14.AdapterBench/ (Performance benchmarks)