# Umbraco

`WarpSearch.Umbraco.Search` is a provider for [Umbraco Search](https://docs.umbraco.com/umbraco-search). It stores your content, media and member indexes in WarpSearch and answers searches from there, so you do not keep Examine (Lucene) indexes on your web servers. It is on [NuGet](https://www.nuget.org/packages/WarpSearch.Umbraco.Search) and the [Umbraco Marketplace](https://marketplace.umbraco.com/package/warpsearch.umbraco.search).

It supports:

- Full-text search with Umbraco's relevance tiers (`TextsR1` to `TextsR3`) and prefix matching as you type
- Keyword, integer, decimal and date filters, exact and range
- Exact and range facets with multi-select counts
- Sorting by score, text, keyword, number and date, and paging
- Culture and segment variants, and protected content by member and member group
- The backoffice index overview, health, rebuild and test search work as with any provider
- Load-balanced sites: every server reads the same collection, and only the server where a change happens writes it

## Requirements

Umbraco 18 with Umbraco Search (`Umbraco.Cms.Search.Core` 18.2 or later), and a WarpSearch collection and writer key from the [shared setup](integrations.md).

## Install

```bash
dotnet add package WarpSearch.Umbraco.Search
```

Register the provider in `Program.cs`, after Umbraco Search:

```csharp
using Umbraco.Cms.Search.Core.DependencyInjection;
using WarpSearch.Umbraco.Search.DependencyInjection;

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddSearchCore()
    .AddWarpSearchProvider()
    .Build();
```

Add the collection and key to `appsettings.json`. Keep the key in user secrets or the environment variable `WarpSearch__ApiKey`:

```json
{
  "WarpSearch": {
    "ApiKey": "ws_...",
    "Collection": "mysite_prod"
  }
}
```

Start the site and rebuild the indexes from **Settings > Search** in the backoffice. From then on, content is indexed as editors save and publish it, and is searchable within a second.

## Configuration

All settings live under `WarpSearch`:

| Setting | Default | Description |
|---|---|---|
| `ApiKey` | | Writer-role key. Required. |
| `Collection` | `umbraco` | The collection for this site's indexes. Create it first. |
| `TextAnalysis` | `Standard` | `Standard` works for every language. `English` adds accent folding and stemming. Rebuild after changing it. |
| `RequestTimeout` | `00:00:30` | Timeout of a single request. |
| `Indexer:BatchSize` | `100` | Documents per write request during a rebuild. |
| `Indexer:DeleteLookupPageSize` | `50` | Page size when finding documents to delete. |
| `Indexer:RebuildIdleFlush` | `00:00:10` | A rebuild that writes nothing for this long is treated as finished. |
| `Searcher:MaxFacetValues` | `100` | Values returned per exact facet. |
| `Searcher:BoostFactorTextR1` to `R3` | `6`, `4`, `2` | Weight of each relevance tier. |

## Good to know

- Each culture of a content item is one document, so the backoffice document count counts cultures.
- A rebuild deletes and rewrites an index, so results are incomplete until it finishes.
- WarpSearch field names allow letters, digits and single underscores, so other characters in Umbraco field names are replaced.
- Suggestions and highlighting are not supported yet.