diff --git a/site/docs/src/json/users/search-queryString-complex-request.json b/site/docs/src/json/users/search-queryString-complex-request.json new file mode 100644 index 0000000000..61abb4770f --- /dev/null +++ b/site/docs/src/json/users/search-queryString-complex-request.json @@ -0,0 +1,14 @@ +{ + "search": { + "numberOfResults": 25, + "queryString": "email:/.*example.com/ AND active:true AND !(_exists_:twoFactor)", + "sortFields": [ + { + "missing": "_first", + "name": "email", + "order": "asc" + } + ], + "startRow": 0 + } +} diff --git a/site/docs/v1/tech/apis/_user-search-request-body-elasticsearch-examples.adoc b/site/docs/v1/tech/apis/_user-search-request-body-elasticsearch-examples.adoc index 27f8860373..65e9f5099b 100644 --- a/site/docs/v1/tech/apis/_user-search-request-body-elasticsearch-examples.adoc +++ b/site/docs/v1/tech/apis/_user-search-request-body-elasticsearch-examples.adoc @@ -1,71 +1,105 @@ + +====== Search Using Ids + [source,json] .Example Request JSON searching by [field]#ids# ---- include::../../../src/json/users/search-ids-request.json[] ---- +====== Search Using A Query String + [source,json] -.Example JSON for the `query` parameter to search for users with unverified registrations to a specific application +.Example Request JSON searching by [field]#queryString# for users with an email address matching a pattern ---- -include::../../../src/json/users/unverified-registrations-query.json[] +include::../../../src/json/users/search-queryString-email-request.json[] ---- [source,json] -.Example Request JSON searching by [field]#query# for users with unverified registrations to a specific application +.Example Request JSON searching by [field]#queryString# for users belonging to a specific group ---- -include::../../../src/json/users/search-query-request.json[] +include::../../../src/json/users/search-queryString-group-request.json[] ---- [source,json] -.Example JSON for the `query` parameter to search for users with a specific role +.Example Request JSON searching by [field]#queryString# for users of a specific tenant. A global API key must be used, and you may not use the `X-FusionAuth-TenantId` header when the search parameters include `tenantId` ---- -include::../../../src/json/users/role-query.json[] +include::../../../src/json/users/search-queryString-tenant-request.json[] ---- [source,json] -.Example JSON searching by `query` for users with with a specific role +.Example Request JSON searching by [field]#queryString# for active users with a certain email address without MFA enabled ---- -include::../../../src/json/users/search-role-query-request.json[] +include::../../../src/json/users/search-queryString-complex-request.json[] ---- +====== Search Using A Query + +Searches using `query` have two parts. You must build the JSON [field]#query# parameter, then escape it and include it in a request. + +A request includes not only a query, but also additional search parameters, such as sorting or pagination. For more, see the link:/docs/v1/tech/guides/user-search-with-elasticsearch[Searching Users With Elasticsearch] guide. + +====== Unverified Registrations + +To search for users with unverified Registrations for a specific Application, you'd use this JSON for the query: + [source,json] -.Example JSON searching by `query` for users with a given email address +.Query JSON ---- -include::../../../src/json/users/search-email-address-query-request.json[] +include::../../../src/json/users/unverified-registrations-query.json[] ---- +And then escape and include it in this request JSON: + [source,json] -.Example JSON searching by `query` for users with custom user data of dataMigrated equal to true +.Request JSON ---- -include::../../../src/json/users/search-user-data-query-request.json[] +include::../../../src/json/users/search-query-request.json[] ---- +====== Specific Role + +To search for users with a Role in an Application, you'd use this JSON for the query: + [source,json] -.Example JSON for the `query` parameter to search for users with a price range in their registration data +.Query JSON ---- -include::../../../src/json/users/search-registration-data-range-query.json[] +include::../../../src/json/users/role-query.json[] ---- +And then escape and include it in this request JSON: + [source,json] -.Example JSON for the `query` parameter to search for users with any value for `userMigrated` +.Request JSON ---- -include::../../../src/json/users/search-data-exists-query.json[] +include::../../../src/json/users/search-role-query-request.json[] ---- +====== Additional Query Examples + +Below are additional [field]#query# examples. The request JSON, in which the [field]#query# must be escaped and included, is omitted. + [source,json] -.Example Request JSON searching by [field]#queryString# for users with an email address matching a pattern +.Example JSON searching by [field]#query# for users with a given email address ---- -include::../../../src/json/users/search-queryString-email-request.json[] +include::../../../src/json/users/search-email-address-query-request.json[] ---- [source,json] -.Example Request JSON searching by [field]#queryString# for users belonging to a specific group +.Example JSON searching by [field]#query# for users with custom user data of dataMigrated equal to true ---- -include::../../../src/json/users/search-queryString-group-request.json[] +include::../../../src/json/users/search-user-data-query-request.json[] ---- [source,json] -.Example Request JSON searching by `queryString` for users of a specific tenant. A global API key must be used, and you may not use the `X-FusionAuth-TenantId` header when the search parameters include `tenantId` +.Example JSON for the [field]#query# parameter to search for users with a price range in their registration data ---- -include::../../../src/json/users/search-queryString-tenant-request.json[] +include::../../../src/json/users/search-registration-data-range-query.json[] ---- + +[source,json] +.Example JSON for the [field]#query# parameter to search for users with any value for `userMigrated` +---- +include::../../../src/json/users/search-data-exists-query.json[] +---- +