SplatDev.Search 1.0.2

SplatDev.Search

Provider-agnostic search abstractions for SplatDev packages — contracts for indexing documents, running queries, faceting, and autocomplete across Elasticsearch, OpenSearch, Meilisearch, and other backends.

Compatibility

Positioning

SplatDev.Search is the out-of-process domain search layer. It is designed for cross-site aggregate data, product catalogs, user records, and analytics — any data that lives outside the CMS content tree.

SplatDev.Umbraco.Examine remains the in-process Lucene-based search for CMS content. Both packages coexist and serve different purposes:

Installation

dotnet add package SplatDev.Search

Interfaces

ISearchIndex<TDoc>

Index management for typed documents:

public interface ISearchIndex<TDoc> where TDoc : class
{
    Task IndexAsync(TDoc doc, CancellationToken ct = default);
    Task IndexManyAsync(IEnumerable<TDoc> docs, CancellationToken ct = default);
    Task DeleteAsync(string id, CancellationToken ct = default);
    Task DeleteByQueryAsync(SearchQuery query, CancellationToken ct = default);
    Task<RefreshResult> RefreshAsync(CancellationToken ct = default);
}

ISearchProvider<TDoc>

Query and analysis operations:

public interface ISearchProvider<TDoc> where TDoc : class
{
    Task<SearchResult<TDoc>> SearchAsync(SearchQuery query, CancellationToken ct = default);
    Task<AutocompleteResult> AutocompleteAsync(string prefix, AutocompleteOptions? opts = null, CancellationToken ct = default);
    Task<IReadOnlyList<Facet>> FacetsAsync(SearchQuery query, IEnumerable<string> fields, CancellationToken ct = default);
}

ISearchMigration

Index lifecycle management:

public interface ISearchMigration
{
    Task EnsureIndexAsync(IndexDefinition definition, CancellationToken ct = default);
    Task DropIndexAsync(string indexName, CancellationToken ct = default);
}

ISearchSerializer

Pluggable document serialization:

public interface ISearchSerializer
{
    string? Serialize<T>(T? value);
    T? Deserialize<T>(string? json);
}

Models

SearchQuery — Fluent Builder

var query = new SearchQuery()
    .WithText("running shoes")
    .Where("brand").Eq("adidas")
    .Where("category").In(["footwear", "athletic"])
    .Where("price").Range(50, 150)
    .OrderBy("rating", SortDirection.Desc)
    .Page(0, 20)
    .WithHighlight(new HighlightOptions { Fields = ["name", "description"] })
    .WithRefresh(RefreshPolicy.None);

SearchResult<TDoc>

public sealed class SearchResult<TDoc> where TDoc : class
{
    public IReadOnlyList<TDoc> Documents { get; init; }
    public long Total { get; init; }
    public int From { get; init; }
    public int Size { get; init; }
    public IReadOnlyList<Facet> Facets { get; init; }
    public IReadOnlyDictionary<string, IReadOnlyList<string>>? Highlights { get; init; }
    public long TookMs { get; init; }
}

IndexDefinition — Attribute-Driven Mapping

Annotate your POCO and derive the mapping automatically:

public class Product
{
    [SearchField(Type = FieldType.Keyword)]
    public string Id { get; set; }

    [SearchField(Type = FieldType.Text, Analyzer = "standard")]
    public string Name { get; set; }

    [SearchField(Type = FieldType.Double, Sortable = true, Facetable = true)]
    public double Price { get; set; }

    [SearchField(Type = FieldType.Keyword, Facetable = true)]
    public string Category { get; set; }
}

var def = IndexDefinition.FromType<Product>();

SearchOptions

public class SearchOptions
{
    public string IndexPrefix { get; set; } = "splatdev";
    public string KeySeparator { get; set; } = "-";
    public RefreshPolicy DefaultRefresh { get; set; } = RefreshPolicy.None;
    public bool ThrowOnEmptyIndex { get; set; }
    public int BulkChunkSize { get; set; } = 500;
}

Enums

Dependency Injection

services.AddSplatDevSearchAbstractions(configuration);

Binds SearchOptions from "SplatDev:Search" config section and registers:

• SearchOptions (singleton)
• ISearchSerializer → SystemTextJsonSearchSerializer (singleton)

Note: ISearchProvider<TDoc> and ISearchIndex<TDoc> are NOT registered — you must add a provider package (e.g. SplatDev.Search.Elastic).

Configuration

{
  "SplatDev": {
    "Search": {
      "IndexPrefix": "myapp",
      "KeySeparator": "-",
      "DefaultRefresh": "None",
      "BulkChunkSize": 500
    }
  }
}

Available provider implementations

Design decisions

• Single-index v1: Multi-index cross-search deferred to v2.
• Refresh default: None with per-call override via SearchQuery.WithRefresh().
• Vector/kNN: Deferred to v2 (SplatDev.Search.Vector.*).
• Highlighting: Common HighlightOptions DTO with provider-specific escape hatch.
• Bulk chunking: Foundation BulkChunkSize = 500, honored by adapters.
• Attribute-driven mapping: Default approach with explicit IndexDefinition override supported.

Dependencies

• Microsoft.Extensions.DependencyInjection.Abstractions
• Microsoft.Extensions.Configuration.Abstractions
• Microsoft.Extensions.Configuration.Binder

SplatDev.Search — part of the SplatDev.Umbraco.Plugins suite. Licensed under MIT. © SplatDev Ltda.

Changelog

1.0.2 — 2026-08-24

Removes a dashboard screenshot that showed an error toast. It was captured against a site where this plugin's API was unreachable, so it advertised a broken dashboard. No screenshot is better than a misleading one; a replacement will be taken against a working install.

1.0.1 — 2026-08-24

Package metadata only: the listing now carries an icon and search tags, and the project and repository links point at the organisation that actually hosts this code. No code changes.

1.0.0 — 2026-08-24

This package now keeps a changelog. Earlier releases predate it and are not reconstructed here — consult the repository history for those. From this version on, every release records what changed for someone using it.