Mooreds/add query string example (FusionAuth#2226)

* added complex queryString query
* reworked example section to make it easier to understand
* linked to guide

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

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[]
+----
+