foundatio-repositories

Foundatio Repositories

Foundatio.Repositories provides a high-level Elasticsearch abstraction. Use repository methods for normal query, count, patch, and pagination work. Reserve raw IElasticClient for migrations or index maintenance that cannot be expressed through repositories.

Documentation: https://repositories.foundatio.dev / https://parsers.foundatio.dev

Repository Hierarchy

IRepository<T>                             — CRUD, Patch, Remove
  └─ ISearchableRepository<T>              — FindAsync, CountAsync, aggregations
       └─ IRepositoryOwnedByOrganization<T>
            └─ IRepositoryOwnedByProject<T>
                 └─ IRepositoryOwnedByOrganizationAndProject<T>

Important: .Index(start, end) only routes to correct daily shards for DailyIndex (events). It is a no-op for VersionedIndex.

CountAsync + AggregationsExpression

CountAsync returns a CountResult with .Total (long) and .Aggregations (AggregationsHelper).

AggregationsExpression DSL

Multiple aggregations are space-separated: "cardinality:stack_id terms:type sum:count~1"

Accessing Aggregation Results

Naming convention: {type}_{field} — the aggregation type prefix + underscore + field name.

result.Aggregations.Cardinality("cardinality_stack_id").Value
result.Aggregations.Terms<string>("terms_type").Buckets       // .Key, .Total
result.Aggregations.DateHistogram("date_date").Buckets        // .Date, .Total
result.Aggregations.Sum("sum_count").Value
result.Aggregations.Min<DateTime>("min_date").Value
result.Aggregations.Max<DateTime>("max_date").Value
result.Aggregations.Average("avg_value").Value

// Nested aggs inside buckets
foreach (var bucket in result.Aggregations.Terms<string>("terms_stack_id").Buckets)
    bucket.Aggregations.Cardinality("cardinality_user").Value;

FilterExpression (Lucene-style)

FilterExpression accepts Lucene query syntax parsed by Foundatio Parsers:

.FilterExpression("type:error (status:open OR status:regressed)")
.FilterExpression(
quot;project:{projectId}")
.FilterExpression(
quot;stack:{stackId}")
.FilterExpression(
quot;signature_hash:{signature}")
.FilterExpression("is_deleted:false")

Building OR filters from collections:

string filter = String.Join(" OR ", stackIds.Select(id => 
quot;stack:{id}"));

Query Extension Methods

Pagination

Use SearchAfterPaging() for deep pagination (never offset-based). NextPageAsync() returns Task<bool> and mutates results in-place.

var results = await _repository.GetAllAsync(o => o.SearchAfterPaging().PageLimit(500));
do
{
    foreach (var doc in results.Documents)
    {
        // process document
    }
} while (!cancellationToken.IsCancellationRequested && await results.NextPageAsync());

Key rules:

• Never use while(true) { ... break; } — use do/while or while(condition)
• Always check CancellationToken in the loop condition

PatchAllAsync / PatchAsync

Use PartialPatch for field-level updates, ScriptPatch for Painless scripts. Pass o => o.ImmediateConsistency() when write-then-read consistency is needed (tests). Use o => o.Notifications(false) to suppress change notifications.

await _tokenRepository.PatchAllAsync(
    q => q.Organization(orgId).FieldEquals(t => t.IsSuspended, false),
    new PartialPatch(new { is_suspended = true }),
    o => o.ImmediateConsistency());

Anti-Patterns

Avoid these in normal repository/query work:

• Use _elasticClient.SearchAsync<T>(...) — use CountAsync or FindAsync
• Use _elasticClient.MultiGetAsync(...) — use GetByIdsAsync
• Use _elasticClient.DeleteByQueryAsync<T>(...) — use RemoveAllAsync
• Use _elasticClient.UpdateByQueryAsync<T>(...) — use PatchAllAsync
• Use _elasticClient.Indices.RefreshAsync(...) — use o => o.ImmediateConsistency()
• Use while(true) { ... break; } for pagination — use do/while or while(condition)