
# ドキュメント

ドキュメントとは、検索が見つけるものです。ページ、その一つのセクション、商品、メモです。`id`、検索される `fields`、`language`、`link`、そしてそれとともに表示される `attributes` を持ちます。ドキュメントは、Markdown ファイル (`spring.search.markdown`) と、`SearchDocumentSource` を実装する任意の Bean から来ます。

## 使う理由

検索は自分のデータを所有しません。それがすでにある場所から読みます。`lib/resources/` の Markdown ファイルにはプロパティが一つあればよく、リポジトリや API には小さな Bean が必要です。インデックスは、最初の検索のときに、言語ごとに一つずつ、それらから組み立てられます。

## SearchDocument

```dart
SearchDocument(
  id: 'book-42',
  fields: {'title': book.title, 'body': book.summary},
  link: '/books/42',
  language: 'en',
  attributes: {'price': '12.90'},
)
```

| フィールド | 意味 |
|---|---|
| `id` | その言語のドキュメントの中で一意 |
| `fields` | フィールド名ごとの検索されるテキスト: `title`、`heading`、`body`、または独自のもの。`spring.search.fields` で重み付けされる |
| `language` | テキストの言語 (`en`、`ja`)。`null` なら `spring.search.default-language` |
| `link` | ドキュメントが表示される場所: ルート、URL。アプリが `id` でそれを見つける場合は `null` |
| `attributes` | アプリがヒットとともに表示するもの (セクションの名前、価格)。検索されない |

`document.title` は `title` フィールドで、それがなければ空です。

## Markdown ファイル

```yaml
spring:
  search:
    markdown:
      - location: resources:content/docs/**/*.md
        exclude: ['**/contents*.md', '**/_*.md']
        link: /docs/{path}
      - location: resources:content/blog/*.md
        link: /blog/{path}
```

各エントリーは、その場所のファイルを、セクションごとに一つのドキュメントに区切ります。冒頭のテキスト、次にレベル二以下の見出し (`##`、`###` など) ごとに一つです。

| フィールドまたは属性 | 値 |
|---|---|
| `title` (フィールド) | ページのタイトル: フロントマターの `title`、なければ最初の `#` の見出し |
| `heading` (フィールド) | セクションの見出し。冒頭のテキストでは空 |
| `body` (フィールド) | Markdown の記号を除いたセクションのテキスト。コードは書かれたまま |
| `link` | ページのリンク、続いてセクションの GitHub のアンカー: `/docs/core/beans#bean-factory` (冒頭のテキストにはない) |
| `page` (属性) | `spring.search.collapse-by: page` のための、ページのリンク |
| `section` (属性) | 見出し |
| `path` (属性) | `lib/resources/` の下のファイル |

- `link` の中の `{path}` は、その場所のディレクトリからのファイルのパスで、`.md`、その言語、最後の `index` を除いたものです。`content/docs/core/beans.md` は `/docs/core/beans`、`content/docs/guides/index.md` は `/docs/guides` です。
- `name.ja.md` は `name.md` の日本語版で、同じリンクにあります。翻訳のないページは、他の言語でも、それ自身の言語で検索されます。
- `exclude` のパターンは、その場所のディレクトリからの相対です。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.search.markdown[n].location` | `resources:` または `asset:` のパターン | 必須 | ファイル (`resources:content/**/*.md`、`asset:docs/**/*.md`) |
| `spring.search.markdown[n].exclude` | パターンのリスト | なし | 除外されるファイル。その場所のディレクトリからの相対 |
| `spring.search.markdown[n].link` | `{path}` を含むテキスト | `/{path}` | ページのリンク |

`resources:` と `asset:` の場所は同じように動きます。`{path}`、`exclude`、`path` 属性は、その場所のフォルダーからの相対です。バイナリーから外されたファイル (`spring.resources.embed.exclude`) も見つかります。

`MarkdownSearchSource` は一度に一つの言語を読みます。`languages` はファイル名から決まり、`documentsIn(language)` はその言語のファイルと、翻訳のないページのデフォルト言語のファイルだけを読みます。ページがダウンロードされる Web のサイト (バイナリーから外したファイル) では、検索された言語のページだけを取得します。 ビルドが書くインデックス (`spring.search.prebuilt`、デフォルト) があれば、ページは一つもダウンロードしません。検索は言語ごとに 1 ファイルを読みます ([ビルドが書くインデックス](searching.md#ビルドが書くインデックス))。

別のリンクや別のフィールドが必要な場合は、独自の `MarkdownSearchSource` Bean を作ってください。

## 独自のソース

`SearchDocumentSource` を実装する任意の Bean がドキュメントを与えます。インデックスが組み立てられるとき、そして無効化されたときに再び読まれます。

```dart
@Component()
class BookDocuments implements SearchDocumentSource {
  BookDocuments(this.books);

  final BookRepository books;

  @override
  Stream<SearchDocument> documents() async* {
    for (final book in await books.findAll()) {
      yield SearchDocument(
        id: 'book-${book.id}',
        fields: {'title': book.title, 'body': book.summary},
        link: '/books/${book.id}',
      );
    }
  }
}
```

## 言語

言語ごとに一つのインデックスがあります。ドキュメントの言語は、それ自身の `language`、なければ `spring.search.default-language` (`en`) です。検索はその言語を指定します (`search(query, language: 'ja')`)。ドキュメントのない言語はデフォルトの言語のものを検索し、`pt-BR` はその前に `pt` にフォールバックします。

読み込む前に自分の言語を知っているソースは、`SearchDocumentSource` の代わりに `LanguageSearchDocumentSource` を実装できます。ある言語のインデックスは、その言語が最初に検索されるときに `documentsIn(language)` から組み立てられます。

```dart
@Component()
class ManualDocuments implements LanguageSearchDocumentSource {
  @override
  Set<String> get languages => {'en', 'ja'};

  @override
  Stream<SearchDocument> documentsIn(String language) => /* ... */;

  @override
  Stream<SearchDocument> documents() async* {
    for (final language in languages) {
      yield* documentsIn(language);
    }
  }
}
```

## インデックスを再構築する

インデックスは最初の検索のときに組み立てられます。ドキュメントが変わったら、`SearchIndexInvalidatedEvent` を発行してください。次の検索がソースを再び読みます。

```dart
@Service()
class BookAdmin {
  BookAdmin(this.books, this.events);

  final BookRepository books;
  final ApplicationEventPublisher events;

  Future<void> add(Book book) async {
    await books.save(book);
    events.publishEvent(SearchIndexInvalidatedEvent(this));
  }
}
```

`SearchService.invalidate()` は、サービスを保持するコードから同じことを行います。

## 関連項目

- [検索](searching.md)
- [アナライザーとランカー](analyzers.md)
- [すべてのプロパティ](properties.md)
