Kjac.SearchProvider.Typesense 18.0.0-rc.1

Umbraco search provider for Typesense

This repo contains an alternative search provider for Umbraco search, based on Typesense.

Prerequisites

An Typesense engine must be available and running 😛

Installation

The package is installed from NuGet:

dotnet add package Kjac.SearchProvider.Typesense

Once installed, add the search provider to Umbraco by means of composition:

using Kjac.SearchProvider.Typesense.DependencyInjection;
using Umbraco.Cms.Core.Composing;

namespace My.Site;

public class SiteComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.AddTypesenseSearchProvider();
}

Connecting to Typesense

You'll need to configure the search provider, so it can connect to your Typesense engine. This is done via appsettings.json:

{
  "TypesenseSearchProvider": {
    "Client": {
      "Host": "[your Typesense host]",
      "Authentication": {
        "ApiKey": "[your Typesense API key]"
      }
    }
  }
}

Hosting multiple environments on a single Typesense engine

You can use an Environment discriminator to host multiple environments on the same Typesense engine. In essence, this creates environment specific indexes by post-fixing the value of Environment to each index alias.

This is also configured via appsettings.json:

{
  "TypesenseSearchProvider": {
    "Client": {
      "Environment": "[your environment alias ('dev', 'test' etc.)]"
    }
  }
}

Custom content indexes

If you need custom content indexes, register them with the RegisterTypesenseContentIndex extension method from the IndexOptionsExtensions. This ensures correct registration, specially in load balanced setups:

namespace My.Site;

public class AdditionalIndexesComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<IndexOptions>(options
            => options.RegisterTypesenseContentIndex<IPublishedContentChangeStrategy>(
                "MyPublishedContentIndex",
                UmbracoObjectTypes.Document
            )
        );
}

Extendability

Generally, you should look to Umbraco search for extension points. There are however a few notable extension points in this search provider as well.

Tweaking score boosting for textual relevance

Umbraco search allows for multiple textual relevance options within a single field. You can change the boost factors of the search provider by configuring the SearcherOptions:

builder.Services.Configure<SearcherOptions>(options =>
{
    // boost the highest relevance text by a factor 100 (default is 6)
    options.BoostFactorTextR1 = 100;
    // boost the second-highest relevance text by a factor 10 (default is 4)
    options.BoostFactorTextR2 = 10;
    // do not boost the third-highest relevance text at all (default is 2)
    options.BoostFactorTextR3 = 1;
});

Allowing for more facet values

By default, the search provider allows for a maximum of 100 facet values returned per facet in a search result. You can change that - also using SearcherOptions:

builder.Services.Configure<SearcherOptions>(options =>
{
    // allow fetching 200 facet values per facet
    options.MaxFacetValues = 200;[README.md](src/Kjac.SearchProvider.Typesense.Tests/README.md)
});

Optimizing server resources

The default Examine indexes from Umbraco CMS are no longer in use, if this search provider powers all things search - that is:

• Frontend search.
• Backoffice search.
• The Delivery API (if applicable on your site).

However, Umbraco CMS continues to keep them up-to-date with content changes. Since this is a waste of server resources, the default Examine indexes can be explicitly disabled by means of composition:

using Umbraco.Cms.Core.Composing;
using Kjac.SearchProvider.Typesense.DependencyInjection;

namespace My.Site;

public class DisableDefaultIndexesComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.DisableDefaultExamineIndexes();
}

Contributing

Yes, please ❤️

When raising an issue, please make sure to include plenty of context, steps to reproduce and any other relevant information in the issue description 🥺

If you're submitting a PR, please:

1. Also include plenty of context and steps to reproduce.
2. Make sure your code follows the provided editor configuration.
3. If at all possible, create tests that prove the issue has been fixed.
   • You'll find instructions on running the tests here.