foundatio-repositories

name

foundatio-repositories

description

Use this skill when querying, counting, patching, or paginating data through Foundatio.Repositories Elasticsearch abstractions. Covers filter expressions, aggregation queries, partial and script patches, and search-after pagination. Apply when working with normal query/count/patch/pagination repository code; reserve raw IElasticClient for migrations or index maintenance that cannot be expressed through 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>

Interface	Entity	Index Type
IEventRepository	PersistentEvent	DailyIndex (date-partitioned)
IStackRepository	Stack	VersionedIndex (single index)
IProjectRepository	Project	VersionedIndex
IOrganizationRepository	Organization	VersionedIndex
IUserRepository	User	VersionedIndex
ITokenRepository	Token	VersionedIndex
IMigrationStateRepository	MigrationState	VersionedIndex

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

Expression	Meaning
cardinality:field	Distinct count
terms:field	Terms aggregation
terms:(field~SIZE)	Terms with bucket size limit
terms:(field~SIZE sub_agg)	Terms with nested aggregation
terms:(field @include:VALUE)	Terms with include filter
date:field	Date histogram (auto interval)
date:field~1d	Date histogram, daily interval
date:field~1M	Date histogram, monthly interval
date:(field sub_agg)	Date histogram with nested agg
sum:field~DEFAULT	Sum with default value
min:field / max:field	Min/Max aggregation
avg:field	Average aggregation
-sum:field~1	Sort descending by this agg (prefix -)

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($"project:{projectId}")
.FilterExpression($"stack:{stackId}")
.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

Method	Purpose	File
.Organization(id)	Filter by organization_id	OrganizationQuery.cs
.Organization(ids)	Filter by multiple org IDs	OrganizationQuery.cs
.Project(id)	Filter by project_id	ProjectQuery.cs
.Stack(id) / .Stack(ids)	Filter by stack_id	StackQuery.cs
.ExcludeStack(id)	Exclude stack_id	StackQuery.cs
.AppFilter(sf)	Apply app-level system filter	AppFilterQuery.cs
.SystemFilter(query)	Chain a pre-built query	Foundatio built-in
.EnforceEventStackFilter()	Resolve stack filters to event IDs	EventStackFilterQuery.cs
.DateRange(start, end, field)	Date range filter	Foundatio built-in
.Index(start, end)	Route to daily shards (events only)	Foundatio built-in
.FieldEquals(expr, value)	Exact field match	Foundatio built-in
.SortExpression(sort)	Sort expression	Foundatio built-in

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)