[DOCS] Rewrite nested query to use new format (#44130)

docs/reference/query-dsl/nested-query.asciidoc

@@ -1,15 +1,23 @@
 [[query-dsl-nested-query]]
 === Nested Query
 
-Nested query allows to query nested objects / docs (see
-<<nested,nested mapping>>). The
-query is executed against the nested objects / docs as if they were
-indexed as separate docs (they are, internally) and resulting in the
-root parent doc (or parent nested mapping). Here is a sample mapping we
-will work with:
+Wraps another query to search <<nested,nested>> fields.
+
+The `nested` query searches nested field objects as if they were indexed as
+separate documents. If an object matches the search, the `nested` query returns
+the root parent document.
+
+[[nested-query-ex-request]]
+==== Example request
+
+[[nested-query-index-setup]]
+===== Index setup
+
+To use the `nested` query, your index must include a <<nested,nested>> field
+mapping. For example:
 
 [source,js]
---------------------------------------------------
+----
 PUT /my_index
 {
     "mappings": {
@@ -21,20 +29,20 @@ PUT /my_index
     }
 }
 
---------------------------------------------------
+----
 // CONSOLE
 // TESTSETUP
 
-And here is a sample nested query usage:
+[[nested-query-ex-query]]
+===== Example query
 
 [source,js]
---------------------------------------------------
-GET /_search
+----
+GET /my_index/_search
 {
     "query": {
         "nested" : {
             "path" : "obj1",
-            "score_mode" : "avg",
             "query" : {
                 "bool" : {
                     "must" : [
@@ -42,29 +50,65 @@ GET /_search
                     { "range" : {"obj1.count" : {"gt" : 5}} }
                     ]
                 }
-            }
+            },
+            "score_mode" : "avg"
         }
     }
 }
---------------------------------------------------
+----
 // CONSOLE
 
-The query `path` points to the nested object path, and the `query`
-includes the query that will run on the nested docs matching the
-direct path, and joining with the root parent docs. Note that any
-fields referenced inside the query must use the complete path (fully
-qualified).
+[[nested-top-level-params]]
+==== Top-level parameters for `nested`
 
-The `score_mode` allows to set how inner children matching affects
-scoring of parent. It defaults to `avg`, but can be `sum`, `min`,
-`max` and `none`.
+`path` (Required)::
+(string) Path to the nested object you wish to search.
 
-There is also an `ignore_unmapped` option which, when set to `true` will
-ignore an unmapped `path` and will not match any documents for this query.
-This can be useful when querying multiple indexes which might have different
-mappings. When set to `false` (the default value) the query will throw an
-exception if the `path` is not mapped.
+`query` (Required)::
++
+--
+(query object) Query you wish to run on nested objects in the `path`. If an
+object matches the search, the `nested` query returns the root parent document.
 
-Multi level nesting is automatically supported, and detected, resulting
-in an inner nested query to automatically match the relevant nesting
-level (and not root) if it exists within another nested query.
+You can search nested fields using dot notation that includes the complete path,
+such as `obj1.name`.
+
+Multi-level nesting is automatically supported, and detected, resulting in an
+inner nested query to automatically match the relevant nesting level, rather
+than root, if it exists within another nested query.
+--
+
+`score_mode` (Optional)::
++
+--
+(string) Indicates how scores for matching child objects affect the root
+parent document's <<query-filter-context,relevance score>>. Valid values are:
+
+`avg` (Default)::
+Use the mean relevance score of all matching child objects.
+
+`max`::
+Uses the highest relevance score of all matching child objects.
+
+`min`::
+Uses the lowest relevance score of all matching child objects.
+
+`none`::
+Do not use the relevance scores of matching child objects. The query assigns
+parent documents a score of `0`.
+
+`sum`::
+Add together the relevance scores of all matching child objects.
+--
+
+`ignore_unmapped` (Optional)::
++
+--
+(boolean) Indicates whether to ignore an unmapped `path` and not return any
+documents instead of an error. Defaults to `false`.
+
+If `true`, {es} returns an error if the `path` is not a mapped field.
+
+You can use this parameter to query multiple indices that may not contain the
+field `path`.
+--