Foundatio.Repositories.Elasticsearch

Foundatio.Repositories

A production-grade repository pattern library for .NET with Elasticsearch implementation. Built on Foundatio building blocks, it provides a clean abstraction over data access with powerful features like caching, messaging, soft deletes, and versioning.

📖 Full Documentation

Installation

dotnet add package Foundatio.Repositories.Elasticsearch

Quick Start

1. Define Your Entity

using Foundatio.Repositories.Models;

public class Employee : IIdentity, IHaveDates, ISupportSoftDeletes
{
    public string Id { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public int Age { get; set; }
    public DateTime CreatedUtc { get; set; }
    public DateTime UpdatedUtc { get; set; }
    public bool IsDeleted { get; set; }
}

2. Create Index Configuration

using Foundatio.Repositories.Elasticsearch.Configuration;

public sealed class EmployeeIndex : VersionedIndex<Employee>
{
    public EmployeeIndex(IElasticConfiguration configuration) 
        : base(configuration, "employees", version: 1) { }

    public override TypeMappingDescriptor<Employee> ConfigureIndexMapping(
        TypeMappingDescriptor<Employee> map)
    {
        return map
            .Dynamic(false)
            .Properties(p => p
                .SetupDefaults()
                .Text(f => f.Name(e => e.Name).AddKeywordAndSortFields())
                .Text(f => f.Name(e => e.Email).AddKeywordAndSortFields())
                .Number(f => f.Name(e => e.Age).Type(NumberType.Integer))
            );
    }
}

3. Create Repository

using Foundatio.Repositories;
using Foundatio.Repositories.Elasticsearch;

public interface IEmployeeRepository : ISearchableRepository<Employee> { }

public class EmployeeRepository : ElasticRepositoryBase<Employee>, IEmployeeRepository
{
    public EmployeeRepository(MyElasticConfiguration configuration) 
        : base(configuration.Employees) { }
}

4. Use the Repository

// Add
var employee = await repository.AddAsync(new Employee 
{ 
    Name = "John Doe", 
    Email = "[email protected]",
    Age = 30 
});

// Query
var results = await repository.FindAsync(q => q
    .FilterExpression("age:>=25")
    .SortExpression("name"));

// Update
employee.Age = 31;
await repository.SaveAsync(employee);

// Soft delete
employee.IsDeleted = true;
await repository.SaveAsync(employee);

// Hard delete
await repository.RemoveAsync(employee);

Features

Repository Pattern

• IReadOnlyRepository<T> - Read operations (Get, Find, Count, Exists)
• IRepository<T> - Write operations (Add, Save, Remove, Patch)
• ISearchableRepository<T> - Dynamic querying with filters, sorting, and aggregations

Patch Operations

• JSON Patch - RFC 6902 compliant patch operations
• Partial Patch - Update specific fields without loading the full document
• Script Patch - Elasticsearch Painless scripts for complex updates
• Bulk Patching - Apply patches to multiple documents via query

Caching

• Built-in distributed caching with automatic invalidation
• Real-time cache consistency via message bus
• Configurable cache expiration and custom cache keys

Message Bus

• Entity change notifications (EntityChanged messages)
• Real-time updates for event-driven architectures
• Soft delete transition detection (ChangeType.Removed)

Soft Deletes

• Automatic query filtering based on IsDeleted
• Three query modes: ActiveOnly, DeletedOnly, All
• Restore capability for soft-deleted documents

Document Versioning

• Optimistic concurrency control
• Automatic version conflict detection
• Retry patterns for conflict resolution

Index Management

• Index<T> - Basic index configuration
• VersionedIndex<T> - Schema versioning with migrations
• DailyIndex<T> - Time-series with daily partitioning
• MonthlyIndex<T> - Time-series with monthly partitioning

Event System

• DocumentsAdding / DocumentsAdded
• DocumentsSaving / DocumentsSaved
• DocumentsRemoving / DocumentsRemoved
• DocumentsChanging / DocumentsChanged
• BeforeQuery - Query interception
• BeforePublishEntityChanged - Notification interception

Additional Features

• Document validation with custom validators
• Migrations for data schema evolution
• Jobs for index maintenance, snapshots, and cleanup
• Custom fields for tenant-specific data
• Parent-child document relationships
• Aggregations and analytics

Documentation

Visit the full documentation for detailed guides:

• Getting Started
• Repository Pattern
• Elasticsearch Setup
• CRUD Operations
• Querying
• Configuration
• Validation
• Caching
• Message Bus
• Patch Operations
• Soft Deletes
• Versioning
• Index Management
• Migrations
• Jobs
• Custom Fields

Sample Application

See the sample Blazor application for a complete working example.

Related Projects

• Foundatio - Core building blocks (caching, messaging, queues, jobs)
• Foundatio.Parsers - Query parsing for dynamic filtering

Contributing

We welcome contributions! Please see our contributing guidelines for details.

License

Licensed under the Apache License, Version 2.0. See LICENSE.txt for details.