Search And FusionAuth

Overview

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

Configuration
Using the Database Search Engine
Using the Elasticsearch Search Engine
Pagination

Configuration

As of version 1.16.0, FusionAuth ships with a database search engine as the default.

By selecting the appropriate installation guide, one can easily create a configuration with Elasticsearch pre-enabled.

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 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

Reindexing is an expensive operation, especially if your system has a large number of users, so it should not be run unless necessary.

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, 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.

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
}

// process fullresults here

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 you’ll only be able to get back 10000 results no matter how you paginate. See the Known Limitations section for more and some workarounds.