C.1. Highlighting basics

To start, you’ll recreate the highlighting snippet from the introduction. In listing C.1, you’ll run a search on the get-together events for the term “elasticsearch” in the name and will highlight this term in the title and the description fields.

Note

For the listing to work, you need to download the code samples for this book by cloning the Git repository from https://github.com/dakrone/elasticsearch-in-action and running populate.sh to index the sample data.

Listing C.1. Highlighting terms in two fields

Highlighting works here because, by default, the title and description fields are included in

_source. If they had been stored individually (by setting store to true in the mapping of that field), Elasticsearch would have extracted the contents from the stored field instead of retrieving it from

_source.

Tip

Storing a field and not going through _source can be faster if you’re highlighting a single field. If you’re highlighting multiple fields, using _source is typically faster because all fields are fetched in the same trip to the disk. You can force using _source even for stored fields by setting force_source to true in your highlighting request. For most use cases, it’s best to stick with the default of using _source alone—both in the mapping and for highlighting.

Depending on your use case, the results from listing C.1 might not be what you need. Let’s look at two of the most common problems and how you can fix them.

C.1.1. What should be passed on to the user

Results from listing C.1 contain the _source field, plus the title and/or description fields if there’s something to highlight in them. Assuming you want to return the title and description fields to the user, you’ll have to implement something like this in your application:

Check if the field (title or description, in this case) is highlighted.

If it is, show the highlighted fragment. If it’s not, take the original field content from _source.

A more elegant solution is to have the highlighter return fragments of both the title and the

description fields, regardless of whether there’s something to highlight in there or not. You’ll do that in listing C.2 by setting no_match_size to the number of characters you want the fragment to have, if the field doesn’t match. The default is 0, which is why fields that don’t match don’t appear at all.

Note

Configuring the fragment size is useful when you can’t control how large fields are. If you take an event description from _source and it fills one page, for example, it will ruin the UI. We’ll discuss more about fragment sizes and other fragment options in section C.2.1.

With the highlighter returning all fields you need, the _source field from the results becomes redundant, so you can skip returning it by setting _source to false in your search request, as shown in the next listing.

Listing C.2. Forcing the highlighter to return the needed fields with no_match_size

Highlighting the same fields regardless of whether they match or not is a common use case. Next we’ll look at a different (though still common) use case.

C.1.2. Too many fields contain highlighted terms

If you pass on the highlighted results of listing C.2 to users, they might get confused by getting elasticsearch descriptions highlighted anyway because they searched only in the title field. To highlight only fields matching the query, you can set require_field_match to true, as in the following listing. Now if the query matches the title field, only the title field gets its terms highlighted.

Listing C.3. Highlighting only fields matching the query

Another method to get to the same result is to figure out that the search goes to the title field and add only title in the list of highlighted fields. This might work, but sometimes you don’t have control over which fields are searched on. For example, if you’re using the query_string query that we discussed in chapter 4, someone could introduce description:elasticsearch, even if the default searched field is something else.

require_field_match and no_match_size are just two of the available highlighting options. There are many more you may find useful, and we’ll discuss them in the next sections.