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/ |
{path}inlinkis the file's path from the location's directory, without.md, its language and a lastindex:content/docs/core/beans.mdis/docs/core/beans,content/docs/guides/index.mdis/docs/guides.name.ja.mdis the Japanese ofname.md, at the same link. A page without a translation is also searched in the other languages, in its own.excludepatterns are relative to the location's directory.
| 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.