Lucene Query Syntax and Examples for Auth0 User Search

When listing users, you can filter results with search queries in Lucene query syntax. The Lucene query syntax reference is the authoritative reference, but at a high level, the query string is parsed into a series of terms and boolean operators.

Terms

Terms define strings to search for. Terms support fields, wildcards, and ranges.

Fields

Fields define where to search for the given string. The full list of user profile attributes indicates which fields are searchable.

All search values are case sensitive except for search values for normalized user profile fields (email, name, given_name, family_name, and nickname), which are case insensitive.
You can search app_metadata and user_metadata fields with a data type of boolean, integer, double, text, object, or array.
You cannot search metadata fields that contain an empty array, empty object, or null value because those values are not indexed.
Terms without field names do not match user_metadata.

Search criteria	Example query
Users whose name is exactly “eugenio”	`name:"eugenio"`
Users whose email domain is `example.com`	`email.domain:"example.com"`
Users from a specific connection	`identities.connection:"google-oauth2"`

When searching metadata, you can search nested values using the path to the field. If the field is nested in an array, you can ignore the array level. For example, with the following user_metadata structure:

{
  "full_name": "Example Name",
  "display": {
    "preferredLanguage": "en",
    "fontSize": 13
  },
  "addresses":{
    "cities": [ "Paris", "Seattle" ]
  }
}

Search criteria	Example query
Users whose full name is “Example Name”	`user_metadata.full_name:"Example Name"`
Users who have set a preferred language	`q: _exists_:user_metadata.display.preferredLanguage`
Users whose font size is set to 13	`q: user_metadata.display.fontSize:13`
Users whose cities contain Paris	`q: user_metadata.addresses.cities:"Paris"`

Wildcards

Wildcards match multiple characters using the syntax *.

For suffix matching, literals must have 3 characters or more. For example, name:*abc is allowed, but name:*ab is not.
You cannot search user_metadata with wildcards.

Search criteria	Example query
Users whose name contains “example”	`name:example`
Users whose email starts with “test”	`email:test*`

Ranges

Ranges match values between the specified upper and lower bound.

You cannot search user_metadata with ranges.

Search criteria	Example query
Users with 9 or fewer logins	`logins_count:[* TO 10}`
Users with 10 to 99 logins	`logins_count:[10 TO 100}`
Users with 100 or more logins	`logins_count:[100 TO *]`
Users who last logged in before 2025	`last_login:[* TO 2024-12-31]`
Users whose last login was in December 2025	`last_login:[2025-12-01 TO 2025-12-31]`

Boolean operators

Boolean operators logically combine terms. Boolean operators work on all normalized user profile fields and root metadata fields.

Search criteria	Example query
Users whose name is exactly “example name” or “test user”	`name:("example name" OR "test user")`
Users without a verified email	`NOT _exists_:email_verified OR email_verified:false`
Users who have never logged in	`NOT _exists_:logins_count OR logins_count:0`

Manage Users

Manage Access

Lucene Query Syntax and Examples for Auth0 User Search

Terms

Fields

Wildcards

Ranges

Boolean operators

​Terms

​Fields

​Wildcards

​Ranges

​Boolean operators

Terms

Fields

Wildcards

Ranges

Boolean operators