ドキュメント

ドキュメントとは、検索が見つけるものです。ページ、その一つのセクション、商品、メモです。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/ の下のファイル
キー 型 デフォルト 意味
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() は、サービスを保持するコードから同じことを行います。

関連項目