
# 検索

`SearchService.search(query, language:, limit:)` は、クエリのヒットを最良のものから順に返します。ヒットは、そのドキュメント、スコア、一致した各フィールドの範囲、そして最初の一致箇所の周りのフィールドのスニペットを持ち、結果のリストにすぐ使えます。

## 使う理由

検索ボックスは最初の数文字で評価されます。`bea` から `bean` を見つけ、`contxet` を許し、なぜその結果が一致したかを示さなければなりません。サービスは一回の呼び出しでそれを行い、ヒットは結果のリストがハイライトに必要とするものを持ちます。

## 例

```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)]
}
```

## クエリ

| 書かれたもの | 意味 |
|---|---|
| `bean factory` | 両方の単語 (`operator: and`)、またはどちらか (`operator: or`) |
| `"bean factory"` | 隣り合った二つの単語、順序どおり |
| `bea` (最後の単語、後に空白なし) | 長い単語の先頭も: `bean`、`beans` |
| `contxet` | `fuzzy` が許せば、タイプミス一つの距離の単語も (`context`) |

- 最後の単語は、テキストが空白で終わらない限り前方一致です。入力に合わせた検索ボックスは、最初の数文字から結果を見つけます。
- タイプミスは、五から七文字の単語では一つ、それより長い単語では `spring.search.fuzzy` 個まで許されます。`fuzzy: 0` でタイプミスを無効にします。
- 完全一致は前方一致より上に、前方一致はタイプミスより上にランクされます。
- 空のクエリはヒットを与えません。

## ランキング

各フィールドは BM25 でスコア付けされ、`spring.search.fields` で重み付けされます。デフォルトは `title` 8、`heading` 4、`body` 1 で、指定されないフィールドは 1 です。次に `SearchRanker` Bean がスコアを変え ([アナライザーとランカー](analyzers.md) を参照)、`collapse-by` があれば、その属性の各値の最良のヒットだけが残ります (`page`: ページごとに一つのセクション)。返されるヒットは最大で `limit` 個で、デフォルトは `spring.search.max-hits` (20) です。

## ヒット

| メンバー | 意味 |
|---|---|
| `document` | 見つかったドキュメント |
| `score` | どれだけよく一致するか。高いものが先 |
| `highlights` | 各フィールドの一致箇所を順に: フィールド名ごとの `List<SearchRange>` (`start`、`end`) |
| `snippet(field, {length: 160})` | 最初の一致箇所の周りの (一致がなければ先頭からの) フィールドの約 `length` 文字。空白で区切られ、切られた場所には `…` が付き、その中の一致箇所を持つ (`SearchSnippet.text`、`SearchSnippet.ranges`) |
| `withScore(score)` | 別のスコアを持つ同じヒット (ランカー向け) |

Flutter では、範囲を `TextRange` に変え、`HighlightedText` や `ThemeText(highlights:)` で表示します ([Flutter アプリでの検索](flutter.md) を参照)。

## 言語のインデックス

`SearchService.index(language)` は、それを直接検索するアプリのために、言語の `SearchIndex` (それがなければデフォルトの言語のもの) を与えます。`invalidate()` はインデックスを忘れ、次の検索がそれらを再び組み立てます。

ドキュメントは一度だけ読まれ、言語のインデックスはその言語が初めて検索されたときに作られます。そのため検索は自分の言語のインデックスだけを待ちます。読み込みと作成は数ミリ秒ごとに間を置くので、その間もアプリはフレームを描き続けます (Web では両方が一つのスレッドで動きます)。いつ作るか:

- `spring.search.indexing: first-search` (デフォルト): 最初の検索のとき。検索を開いたときに `SearchService.prepare(language: ...)` を呼ぶと、ユーザーが入力を始める間にインデックスが作られます。最初に入力された単語は同じ作成を待ちます。
- `spring.search.indexing: start`: アプリケーションの起動中に、`searchIndexRunner` (`ApplicationRunner`) が作ります。Flutter アプリはスプラッシュの裏で作り、最初の検索ではもうできています。
- `spring.search.indexing: background`: 起動の直後、アプリが動いている間に作ります。起動は待ちません。デフォルト言語のインデックスが最初に作られるので、一秒後に開いた検索ではたいていもうできています。

言語を指定しない `prepare()` はすべてのインデックスを、デフォルト言語のものから作ります。`prepared` はドキュメントが読まれたか読まれている最中かを、`isIndexed(language)` はその言語のインデックスが作られたか作成中かを示します。

## ビルドが書くインデックス

`spring.search.markdown` のページについては、ビルドがインデックスそのものを言語ごとに 1 ファイル、`lib/resources/spring_gen/search/`（`en.json`、`ja.json`）に書きます。ページはセクションに分けられ、語は解析されて数えられています。`SearchService` はすべてのページを読んでインデックスを作る代わりに、その言語のファイルを読みます。最初の検索は、何百ものファイルと描画スレッドでの数秒の処理ではなく、1 回のダウンロードと 1 秒足らずで済みます。

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

- ビルドはこれらのファイルを埋め込みません。Flutter アプリはそのディレクトリを `flutter: assets:` に書き、ないときはビルドが警告します。VM の Dart アプリは `lib/resources/` から読みます。
- ファイルが使われるのは、アプリと同じアナライザーと同じ `spring.search.markdown` の項目で作られたときだけです。違うとき、またはその言語にアプリ自身の `SearchDocumentSource` ビーンがあるときは、これまでどおりインデックスを作ります。
- アナライザーがアプリ自身のビーンである言語（`spring.search.analyzers`）にはファイルはできません。そのアナライザーは動いているアプリにしかないからです。`resources:` 以外の場所では何も書きません。
- ファイルはビルドのたびにページから作られます。`flutter build` の前に `dart run build_runner build` を実行するなら、コミットする必要はありません（`.gitignore` に `lib/resources/spring_gen/`）。
- `spring.search.prebuilt: false` で、書くことも読むこともしません。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.search.operator` | `and`、`or` | `and` | `and`: ドキュメントはクエリのすべての単語を持つ。`or`: そのいずれか |
| `spring.search.fuzzy` | 数値 | `1` | 単語が持ちうるタイプミス: 五から七文字の単語では一つ、それより長い単語ではこの数まで。`0`: なし |
| `spring.search.fields.<field>` | 数値 | `title` 8、`heading` 4、`body` 1 | フィールドの重み。指定されないフィールドの重みは 1 |
| `spring.search.max-hits` | 数値 | `20` | 検索が与えるヒットの最大数 |
| `spring.search.collapse-by` | 属性の名前 | なし | この属性の各値の最良のヒットだけが残る |
| `spring.search.indexing` | `first-search`、`start`、`background` | `first-search` | インデックスを作るとき: 最初の検索 (または `prepare()`) のとき、アプリケーションの起動中、または起動の直後にアプリが動いている間 |
| `spring.search.prebuilt` | 真偽値 | `true` | ビルドが `spring.search.markdown` のインデックスを言語ごとに 1 ファイル書き、検索はそれを読みます（[ビルドが書くインデックス](#ビルドが書くインデックス)） |
| `spring.search.default-language` | 言語タグ | `en` | 言語を指定しない検索、またはドキュメントのない言語を指定した検索の言語 |

## 関連項目

- [ドキュメント](documents.md)
- [アナライザーとランカー](analyzers.md)
- [すべてのプロパティ](properties.md)
