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
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
. 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
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.
// 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.
Feedback
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.