Search And FusionAuth

Overview

FusionAuth ships with two options for search: a simple search via the database search engine and the Elasticsearch search engine.

Configuration

Configuration Reference

The relevant properties which control the configuration of the search engine include search.type which specifies the search engine type.

For the database search engine, there is no other configuration needed.

All other settings referencing search apply to the Elasticsearch search engine only. Please see the Configuration Reference for more details.

Switch Engine Types

FusionAuth supports two different search engines. If you begin with one, you can change to the other if your needs change.

This tutorial walks through how to switch between the different search engines.

Docker

If you are running FusionAuth in a Docker environment, see the Using FusionAuth on Docker documentation for an example configuring Elasticsearch as the user search engine.

View Current Configuration

You may view the configured search engine type in the FusionAuth admin UI by navigating to System -> About. As you can see below, this system is configured to use the database search engine.

Using the Database Search Engine

This configuration is lightweight, simplifies installation and system complexity, but comes with the trade offs of limited search capabilities and performance implications.

The database search engine is appropriate for systems that are not dependent on the FusionAuth APIs, are not expected to have a large number of search results, or are running in an embedded environment.

If you don’t need advanced searching capabilities, you may be able to use the database search engine for large installations. This is not a use case FusionAuth tests, so ensure you provision your database with enough resources and benchmark your typical use cases.

Limitations

You may add a * character to wildcard match any character, including none. So *piedpiper will match piedpiper and thepiedpiper. You may put the wildcard at any location in a search string.

All search terms are converted to lowercase and compared with lowercase values. In other words, all database searches are case-insensitive.

Regular expressions, ranges, and other complicated queries can not be used.

Using the Elasticsearch Search Engine

Leveraging Elasticsearch enables advanced search capabilities on more numerous and granular data. It also provides a performance improvement.

The Elasticsearch search engine is appropriate for systems that are dependent on the FusionAuth APIs (such as user search), are expected to have a large number of results, or require more granularity in search than is provided by the standard database search engine.

Reindexing Elasticsearch

It is possible, though rare, for an Elasticsearch index to become out of sync with the database. If you stand up FusionAuth with a database dump and restore or import users using the User Import API, you may need to run this operation. You may also be instructed to do so by FusionAuth support.

In general, even if a temporary outage occurs with Elasticsearch, the index will be sync up automatically.

If you do need to run this, navigate to System -> Reindex in the FusionAuth admin UI to initiate a reindex of all users. This navigation item will only be displayed when the search engine is Elasticsearch.

Optionally, you can also reindex via API.

• Rebuild Index API
• Index Status API

Pagination

You often need to paginate the results when running a query that matches many users or entities.

You can use the numberOfResults and startRow parameters to do so.

Pagination pseudocode to retrieve search results

{/*  this is pseudo code and won't work out of the box */}
{/*  adapt for whichever client and programming language you are using */}

startRow = 0
numberOfResults = 25
fullresults = [] // new array
results = client.search(query, startRow, numberOfResults)
count = results.length
fullresults.append(results)

while (count > 0) {
  startRow = startRow + count 
  results = client.search(query, startRow, numberOfResults)
  fullresults.append(results)
  count = results.length
}

You may also set numberOfResults to a higher number (500 or 5000, for example) to retrieve more results. However, processing results 25 or 50 at a time has less impact on the FusionAuth system.

Note that prior to version 1.48.0 you’ll only be able to get back 10,000 results no matter how you paginate. See the Known Limitations section for more and some workarounds.

As of version 1.48.0, FusionAuth you can use a nextResults token to page past the 10,000 results limitation when using the Elasticsearch engine.

See the Extended Pagination section for more details.

Extended Pagination

Starting in version 1.48.0 of FusionAuth every search using the Elasticsearch engine will return a nextResults token in the response. You may use this token on subsequent calls to continue paging forward in the result set and go past the 10,000 results limit with Elasticsearch. Every search request made using a nextResults token will return a page of results and another nextResults token that can be used to retrieve the next page. These calls can be made indefinitely until the number of returned results is 0.

Internally FusionAuth uses this token to make a search_after parameter on the request to Elasticsearch. See the Elasticsearch documentation for more information.

For more detail on extended pagination see the Searching Users With Elasticsearch guide.