Foundatio Repositories

Exceptionless repos:

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

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.

// Cardinality
result.Aggregations.Cardinality("cardinality_stack_id").Value

// Terms
result.Aggregations.Terms<string>("terms_type").Buckets  // .Key, .Total

// Date histogram
result.Aggregations.DateHistogram("date_date").Buckets   // .Date, .Total

// Sum / Min / Max / Avg
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
var terms = result.Aggregations.Terms<string>("terms_stack_id");
foreach (var bucket in terms.Buckets)
{
    var nested = bucket.Aggregations.Cardinality("cardinality_user").Value;
}

Examples

Simple cardinality:

var result = await _eventRepository.CountAsync(q => q
    .FilterExpression($"project:{projectId}")
    .AggregationsExpression("cardinality:stack_id cardinality:id"));
long uniqueStacks = result.Aggregations.Cardinality("cardinality_stack_id").Value.GetValueOrDefault();

Date histogram + nested cardinality:

var result = await _eventRepository.CountAsync(q => q
    .FilterExpression($"project:{projectId}")
    .AggregationsExpression("date:(date cardinality:id) cardinality:id"));
var buckets = result.Aggregations.DateHistogram("date_date").Buckets;

Date histogram with monthly interval:

var result = await _eventRepository.CountAsync(q => q
    .Organization(organizationId)
    .AggregationsExpression("date:date~1M"));
foreach (var bucket in result.Aggregations.DateHistogram("date_date").Buckets)
{
    // bucket.Date, bucket.Total
}

Terms with nested min/max:

var result = await _eventRepository.CountAsync(q => q
    .AggregationsExpression($"terms:(stack_id~{stackSize} min:date max:date)"));
var buckets = result.Aggregations.Terms<string>("terms_stack_id").Buckets;
foreach (var b in buckets)
{
    DateTime first = b.Aggregations.Min<DateTime>("min_date").Value;
    DateTime last = b.Aggregations.Max<DateTime>("max_date").Value;
}

Complex multi-aggregation (DailySummaryJob):

var result = await _eventRepository.CountAsync(q => q
    .SystemFilter(systemFilter)
    .FilterExpression(filter)
    .EnforceEventStackFilter()
    .AggregationsExpression("terms:(first @include:true) terms:(stack_id~3) cardinality:stack_id sum:count~1"));
double total = result.Aggregations.Sum("sum_count")?.Value ?? result.Total;
double uniqueTotal = result.Aggregations.Cardinality("cardinality_stack_id")?.Value ?? 0;

Stack mode aggregations with sort prefix:

string aggs = mode switch
{
    "stack_recent"   => "cardinality:user sum:count~1 min:date -max:date",
    "stack_frequent" => "cardinality:user -sum:count~1 min:date max:date",
    _ => null
};
var result = await _repository.CountAsync(q => q
    .SystemFilter(systemFilter)
    .FilterExpression(filter)
    .EnforceEventStackFilter()
    .AggregationsExpression($"terms:(stack_id~{limit} {aggs})"));

FilterExpression (Lucene-style)

FilterExpression accepts Lucene query syntax parsed by Foundatio Parsers:

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

Building OR filters from collections:

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

Query Extension Methods

Custom extensions on IRepositoryQuery<T>:

Pagination

Standard do/while Pattern (preferred)

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());

While-loop Pattern (when processing before checking)

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

    if (cancellationToken.IsCancellationRequested || !await results.NextPageAsync())
        break;
}

Key rules:

• NextPageAsync() returns Task<bool> and mutates results in-place
• Never use while(true) { ... break; } — use do/while or while(condition)
• Always use SearchAfterPaging() for deep pagination (not offset-based)
• Always check CancellationToken in the loop condition

Collecting All IDs

var results = await _stackRepository.GetIdsByQueryAsync(
    q => systemFilterQuery.As<Stack>(),
    o => o.PageLimit(10000).SearchAfterPaging());

var stackIds = new List<string>();
if (results?.Hits is not null)
{
    do
    {
        stackIds.AddRange(results.Hits.Select(h => h.Id));
    } while (await results.NextPageAsync());
}

PatchAllAsync / PatchAsync

PartialPatch (field-level update)

// Suspend all tokens for an org
await _tokenRepository.PatchAllAsync(
    q => q.Organization(orgId).FieldEquals(t => t.IsSuspended, false),
    new PartialPatch(new { is_suspended = true }),
    o => o.ImmediateConsistency());

ScriptPatch (Painless script)

const string script = @"
ctx._source.total_occurrences += params.count;
ctx._source.last_occurrence = params.maxOccurrenceDateUtc;";

var patch = new ScriptPatch(script.TrimScript())
{
    Params = new Dictionary<string, object>
    {
        { "count", count },
        { "maxOccurrenceDateUtc", maxDate }
    }
};

await _stackRepository.PatchAsync(stackId, patch, o => o.Notifications(false));

PatchAsync with Array of IDs

string script = $"ctx._source.next_summary_end_of_day_ticks += {TimeSpan.TicksPerDay}L;";
await PatchAsync(projects.Select(p => p.Id).ToArray(), new ScriptPatch(script), o => o.Notifications(false));

Soft Delete

await PatchAllAsync(
    q => q.Organization(orgId).Project(projectId),
    new PartialPatch(new { is_deleted = true, updated_utc = _timeProvider.GetUtcNow().UtcDateTime }));

RemoveAllAsync

// By organization + date range
await _eventRepository.RemoveAllAsync(organizationId, clientIpAddress, utcStart, utcEnd);

// By stack IDs
await _eventRepository.RemoveAllByStackIdsAsync(stackIds);

// With inline filter
await _repository.RemoveAllAsync(q => q.Organization(orgId));

GetByIdsAsync (Batch Existence Checks)

// Batch fetch — returns only found documents
var stacks = await _stackRepository.GetByIdsAsync(stackIds);

// With cache
var users = await _userRepository.GetByIdsAsync(userIds, o => o.Cache());

// Check existence by comparing returned set
var found = (await _organizationRepository.GetByIdsAsync(orgIds)).Select(o => o.Id).ToHashSet();
var missing = orgIds.Where(id => !found.Contains(id)).ToArray();

CommandOptions

Anti-Patterns

NEVER do these:

• 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)