Notre avis

Ce pattern propose des stratégies de performance pour les opérations sur de grands ensembles de données : streaming, pagination, comptage optimisé et opérations en masse.

Points forts

Fournit des stratégies concrètes (streaming, bulk, comptage rapide)
Inclut des benchmarks chiffrés montrant des accélérations spectaculaires
Propose un pattern de pagination avec comptage pour les API web
Couvre des antipatterns courants avec des alternatives correctes

Limites

Spécifique à la librairie Koan, pas universel
Les benchmarks sont idéalisés et peuvent varier en pratique
N'aborde pas les aspects de mise en cache ou d'indexation

Quand l'utiliser

Utilisez ce pattern lorsque vous manipulez de grands ensembles de données et devez optimiser les performances des requêtes en base de données.

Quand l'éviter

Évitez ce pattern pour de petits volumes de données ou si la simplicité du code prime sur les micro-optimisations.

Exemples

Stream large dataset

How can I efficiently process 1 million records from the database without running out of memory? Show me streaming.

Fast count for pagination

I need a fast count of total records for my API pagination. How to get it in milliseconds instead of seconds?

Bulk insert 1000 items

I have 1000 todos to insert efficiently. How to bulk save them in a single operation?

name: koan-performance description: Streaming, pagination, count strategies, bulk operations

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)

// ❌ WRONG: Load everything into memory
var allTodos = await Todo.All(); // 1 million records!

// ✅ CORRECT: Stream in batches
await foreach (var todo in Todo.AllStream(batchSize: 1000))
{
    await ProcessTodo(todo);
}

Count Strategies

// Fast count (metadata estimate - 1000x+ faster)
var fast = await Todo.Count.Fast(ct); // ~5ms for 10M rows

// Exact count (guaranteed accuracy)
var exact = await Todo.Count.Exact(ct); // ~25s for 10M rows

// Optimized (framework chooses)
var 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

// Bulk create
var todos = Enumerable.Range(1, 1000)
    .Select(i => new Todo { Title = $"Task {i}" })
    .ToList();
await todos.Save(); // Single operation

// Bulk removal
await Todo.RemoveAll(RemoveStrategy.Fast); // TRUNCATE/DROP (225x faster)

Batch Retrieval

// ❌ WRONG: N queries
foreach (var id in ids)
{
    var todo = await Todo.Get(id);
}

// ✅ CORRECT: 1 query
var todos = await Todo.Get(ids);

Pagination

public async Task<IActionResult> GetTodos(
    int page = 1,
    int pageSize = 20,
    CancellationToken ct = default)
{
    var result = await Todo.QueryWithCount(
        t => !t.Completed,
        new DataQueryOptions { OrderBy = nameof(Todo.Created), Descending = true },
        ct);

    Response.Headers["X-Total-Count"] = result.TotalCount.ToString();
    return Ok(result.Items);
}

Performance Benchmarks

| Operation | Inefficient | Efficient | Speedup | |-----------|-------------|-----------|---------| | Bulk Remove (1M) | DELETE loop ~45s | TRUNCATE ~200ms | 225x | | Count (10M) | Full scan ~25s | Metadata ~5ms | 5000x | | Batch Get (100) | 100 queries | 1 query | 100x | | Stream (1M) | Load all (OOM) | Stream batches | Memory safe |

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)

Optimisation des performances Koan

Recommandé pour