ドキュメント
ドキュメントとは、検索が見つけるものです。ページ、その一つのセクション、商品、メモです。id、検索される fields、language、link、そしてそれとともに表示される attributes を持ちます。ドキュメントは、Markdown ファイル (spring.search.markdown) と、SearchDocumentSource を実装する任意の Bean から来ます。
使う理由
検索は自分のデータを所有しません。それがすでにある場所から読みます。lib/resources/ の Markdown ファイルにはプロパティが一つあればよく、リポジトリや API には小さな Bean が必要です。インデックスは、最初の検索のときに、言語ごとに一つずつ、それらから組み立てられます。
SearchDocument
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 ファイル
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 ファイルを読みます (ビルドが書くインデックス)。
別のリンクや別のフィールドが必要な場合は、独自の MarkdownSearchSource Bean を作ってください。
独自のソース
SearchDocumentSource を実装する任意の Bean がドキュメントを与えます。インデックスが組み立てられるとき、そして無効化されたときに再び読まれます。
@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) から組み立てられます。
@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 を発行してください。次の検索がソースを再び読みます。
@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() は、サービスを保持するコードから同じことを行います。