Ferret.Core 0.1.4

Ferret

Postgres-first paging, filtering, sorting, and pluggable search for .NET. A drop-in alternative to Typesense / Meilisearch / Elastic for projects that already run PostgreSQL.

Status: 0.1 — early pre-1.0. All backends are implemented and the core is exercised by a live origin project, but the library is not yet broadly battle-tested. The public API may change before 1.0.0. See VERSIONING.md for the pre-1.0 policy and road to 1.0.

Features

• Pagination, filtering, sorting wired through a single query model.
• Trigram fuzzy search (pg_trgm GiST), full-text (tsvector / GIN), and pgvector ANN (HNSW) — opt-in, mix-and-match.
• Hybrid scoring (weighted RRF) across backends.
• Configurable embeddings — OpenAI-compatible, Ollama, or any Microsoft.Extensions.AI generator.
• Schema is generated for you from [Searchable] attributes via EF Core migrations (Ferret.Migrations) — or hand-roll it if you prefer.
• ORM-agnostic. EF Core or Dapper adapters ship in the box; bring your own session for any other stack.
• Attribute-driven entity discovery; pluggable naming strategy (snake_case / identity).
• ASP.NET Core model binders + one-line MapFerret endpoints with OpenAPI.

Packages

Install

dotnet add package Ferret.Core
dotnet add package Ferret.EntityFrameworkCore   # or: Ferret.Hydration.Dapper

Quickstart — EF Core

Annotate the entity:

using Ferret.Abstractions;

[SearchableEntity]
public sealed class Product : ISearchableEntity<Guid>
{
    public Guid Id { get; init; }

    [Searchable, Filterable, Sortable]
    public string Name { get; init; } = "";

    [Searchable(Weight = 2.0f)]
    public string Sku { get; init; } = "";
}

Wire up DI:

services.AddDbContext<AppDbContext>(o => o.UseNpgsql(connectionString));
services.AddFerret(opts => opts
    .ScanAssembly(typeof(Product).Assembly)
    .UseTrigramSearch());

Generate the schema (Ferret.Migrations — see docs/migrations.md), then search:

var page = await dbContext.SearchOffsetAsync<Product, Guid>(serviceProvider,
    new PagedQuery<Product, Guid>
    {
        Mode = PaginationMode.Offset,
        Search = "blue widge",
        Limit = 25,
        Page = 0,
        Sort = [new SortClause { Field = "Name", Direction = SortDirection.Ascending }],
    });

Cursor mode is available via dbContext.SearchCursorAsync<...> returning CursorResult<T>.

Quickstart — Dapper

services.AddFerret(opts => opts
    .ScanAssembly(typeof(Product).Assembly)
    .UseTrigramSearch()
    .UseDapperHydration());

await using var session = new DapperSession(
    ct => Task.FromResult<DbConnection>(new NpgsqlConnection(connectionString)),
    sp.GetRequiredService<ISqlDialect>());

var page = await sp.GetRequiredService<IFerretEngine>()
    .SearchOffsetAsync<Product, Guid>(session,
        new PagedQuery<Product, Guid> { Mode = PaginationMode.Offset, Search = "widge", Limit = 25 });

Documentation

• Setup & integration modes — EF Core, Dapper, or bring-your-own-session.
• Schema & migrations — generated schema, reindex modes, the reindex worker/CLI, and the manual-SQL reference.
• Full-text search — groups, weights, hybrid.
• Vector search & embeddings — connectors, version transitions.
• ASP.NET Core — query shapes, MapFerret, legacy wire shape.

Compatibility

• .NET 10 SDK
• EF Core 10 (when using Ferret.EntityFrameworkCore / Ferret.Migrations)
• PostgreSQL 15, 16, 17 — CI matrix runs all three
• Extensions: trigram needs pg_trgm; full-text needs none; vector needs vector (pgvector)
• Ferret.Migrations builds on EntityFrameworkCore.ExtensibleMigrations (source)

License

MIT.