Documents

A document is what a search finds: a page, a section of one, a product, a note. It has an id, searched fields, a language, a link and attributes shown with it. Documents come from Markdown files (spring.search.markdown) and from any bean that implements SearchDocumentSource.

Why

The search does not own your data: it reads it from where it already is. Markdown files of lib/resources/ need only a property; a repository or an API needs a small bean. The index is built from them at the first search, one per language.

SearchDocument

SearchDocument(
  id: 'book-42',
  fields: {'title': book.title, 'body': book.summary},
  link: '/books/42',
  language: 'en',
  attributes: {'price': '12.90'},
)
Field Meaning
id Unique among the documents of its language
fields The searched texts by field name: title, heading, body, or your own, weighted by spring.search.fields
language The language of the texts (en, ja); null for spring.search.default-language
link Where the document is shown: a route, a URL; null when the app finds it by id
attributes What the app shows with a hit (a section's name, a price); not searched

document.title is the title field, empty when there is none.

Markdown files

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

Each entry cuts the files of its location into one document per section: the opening text, then one per heading of level two and below (##, ###, ...):

Field or attribute Value
title (field) The page's title: the front matter's title, else its first # heading
heading (field) The section's heading; empty for the opening text
body (field) The section's text, without the Markdown's marks; code stays as written
link The page's link, then the section's GitHub anchor: /docs/core/beans#bean-factory (the opening text has none)
page (attribute) The page's link, for spring.search.collapse-by: page
section (attribute) The heading
path (attribute) The file below lib/resources/
Key Type Default Meaning
spring.search.markdown[n].location resources: or asset: pattern required The files (resources:content/**/*.md, asset:docs/**/*.md)
spring.search.markdown[n].exclude list of patterns none Files left out, relative to the location's directory
spring.search.markdown[n].link text with {path} /{path} The link of a page

A location of resources: or asset: works the same: {path}, exclude and the path attribute are relative to the location's folder. Files left out of the binary (spring.resources.embed.exclude) are found as well.

MarkdownSearchSource reads one language at a time. Its languages come from the file names, and documentsIn(language) reads only the files of that language, plus the default-language file of a page without a translation. A site whose pages are downloaded on the web (files left out of the binary) fetches only the pages of the language searched. With the index the build writes (spring.search.prebuilt, the default) it fetches none: the search reads one file per language (The index the build writes).

For another link or other fields, make a MarkdownSearchSource bean of your own.

A source of your own

Any bean that implements SearchDocumentSource gives documents. It is read when the index is built, and again when it is invalidated:

@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}',
      );
    }
  }
}

Languages

There is one index per language. A document's language is its own language, else spring.search.default-language (en). A search names its language (search(query, language: 'ja')); a language without documents searches the default language's, and pt-BR falls back to pt before that.

A source that knows its languages before it reads anything can implement LanguageSearchDocumentSource instead of SearchDocumentSource. The index of a language is built from documentsIn(language), when that language is first searched:

@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);
    }
  }
}

Rebuilding the index

The index is built at the first search. When the documents change, publish a SearchIndexInvalidatedEvent; the next search reads the sources again:

@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() does the same from code that holds the service.

See also