
# Searching

`SearchService.search(query, language:, limit:)` returns the hits of a query, best first. A hit has its document, its score, the stretches of each field that matched, and a snippet of a field around the first match, ready for a list of results.

## Why

A search box is judged in the first few letters: it must find `bean` from `bea`, forgive `contxet`, and show why a result matched. The service does that with one call, and the hit carries what a result list needs to highlight.

## Example

```dart
final hits = await search.search('"bean factory" scop', language: 'en', limit: 10);

for (final hit in hits) {
  final snippet = hit.snippet('body', length: 140);
  print('${hit.score.toStringAsFixed(2)} ${hit.document.title}');
  print('  ${hit.document.link}');
  print('  ${snippet.text}');           // "…the bean factory creates a scoped…"
  print('  ${snippet.ranges}');         // [[4, 16), [29, 35)]
}
```

## The query

| Written | Meaning |
|---|---|
| `bean factory` | Both words (`operator: and`), or either (`operator: or`) |
| `"bean factory"` | The two words next to each other, in order |
| `bea` (the last word, no space after it) | Also the start of longer words: `bean`, `beans` |
| `contxet` | Also words one typo away (`context`), when `fuzzy` allows |

- The last word is a prefix unless the text ends with a space: a search box as you type finds results from the first letters.
- A typo is allowed for a word of five to seven letters, and up to `spring.search.fuzzy` typos for a longer one; `fuzzy: 0` turns typos off.
- Exact matches rank above prefixes, which rank above typos.
- An empty query gives no hits.

## The ranking

Each field is scored with BM25 and weighted by `spring.search.fields`: by default `title` 8, `heading` 4, `body` 1, and 1 for a field not named. Then the `SearchRanker` beans change the scores (see [Analyzers and rankers](analyzers.md)), and with `collapse-by` only the best hit of each value of that attribute stays (`page`: one section per page). At most `limit` hits are returned, `spring.search.max-hits` (20) by default.

## The hit

| Member | Meaning |
|---|---|
| `document` | The document found |
| `score` | How well it matches; higher first |
| `highlights` | The matches of each field, in order: a `List<SearchRange>` (`start`, `end`) per field name |
| `snippet(field, {length: 160})` | About `length` characters of the field around its first match (from the start when it has none), cut at spaces, `…` where cut, with the matches in it (`SearchSnippet.text`, `SearchSnippet.ranges`) |
| `withScore(score)` | The same hit with another score (for a ranker) |

In Flutter, turn the ranges into `TextRange`s and show them with `HighlightedText` or `ThemeText(highlights:)` (see [Search in a Flutter app](flutter.md)).

## The index of a language

`SearchService.index(language)` gives the `SearchIndex` of a language (or the default language's when it has none), for an app that searches it directly. `invalidate()` forgets the indexes; the next search builds them again.

The documents are read once; the index of a language is built the first time that language is searched, so a search waits for its own language's index only. Reading and building pause every few milliseconds, so an app keeps drawing its frames meanwhile (the web has one thread for both). When:

- `spring.search.indexing: first-search` (the default): at the first search. Call `SearchService.prepare(language: ...)` when the search opens, and the index builds while the user starts typing; the first word typed waits for the same build.
- `spring.search.indexing: start`: while the application starts, by the `searchIndexRunner` (an `ApplicationRunner`): a Flutter app builds them behind its splash, and its first search finds them ready.
- `spring.search.indexing: background`: right after the start, while the app runs; the start does not wait. The default language's index comes first, so a search opened a second later most likely finds it ready.

`prepare()` without a language builds every index, the default language's first. `prepared` tells whether the documents are read or being read, `isIndexed(language)` whether that index is built or being built.

## The index the build writes

For the pages of `spring.search.markdown` the build writes the index itself, a file per language in `lib/resources/spring_gen/search/` (`en.json`, `ja.json`): the pages cut into sections, their terms analyzed and counted. The `SearchService` reads the file of a language instead of reading every page and building the index, so the first search costs one download and a fraction of a second instead of hundreds of files and seconds of work on the thread that draws.

```yaml
flutter:
  assets:
    - lib/resources/spring_gen/search/
```

- The build never embeds the files; a Flutter app lists their directory under `flutter: assets:`, and the build warns when it is missing. A Dart app on the VM reads them from `lib/resources/`.
- A file is used only when it was built with the same analyzer and the same `spring.search.markdown` entries as the app has; otherwise, or when the app has `SearchDocumentSource` beans of its own for that language, the index is built as before.
- A language whose analyzer is an app's own bean (`spring.search.analyzers`) gets no file: only the running app has that analyzer. A location outside `resources:` writes none.
- The files come from the pages at every build: they need not be committed (`lib/resources/spring_gen/` in `.gitignore`), as long as the build runs `dart run build_runner build` before `flutter build`.
- `spring.search.prebuilt: false` writes and reads none.

## The properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.search.operator` | `and`, `or` | `and` | `and`: a document has every word of the query; `or`: one of them |
| `spring.search.fuzzy` | number | `1` | The typos a word may have: one for a word of five to seven letters, up to this many for a longer one; `0`: none |
| `spring.search.fields.<field>` | number | `title` 8, `heading` 4, `body` 1 | The weight of a field; a field not named weighs 1 |
| `spring.search.max-hits` | number | `20` | The most hits a search gives |
| `spring.search.collapse-by` | attribute name | none | Only the best hit of each value of this attribute stays |
| `spring.search.indexing` | `first-search`, `start`, `background` | `first-search` | When the indexes are built: at the first search (or `prepare()`), while the application starts, or right after it while the app runs |
| `spring.search.prebuilt` | boolean | `true` | The build writes the index of `spring.search.markdown`, a file per language, and the search reads it ([The index the build writes](#the-index-the-build-writes)) |
| `spring.search.default-language` | language tag | `en` | The language of a search that names none, or one without documents |

## See also

- [Documents](documents.md)
- [Analyzers and rankers](analyzers.md)
- [All properties](properties.md)
