Documentation for field_masking_span query (#20395)

* Documentation for field_masking_span query. Fixes #20293

* After review fixes

docs/reference/query-dsl/span-field-masking-query.asciidoc

@@ -0,0 +1,43 @@
+[[query-dsl-span-field-masking-query]]
+=== Span Field Masking Query
+
+Wrapper to allow span queries to participate in composite single-field span queries by 'lying' about their search field. The span field masking query maps to Lucene's `SpanFieldMaskingQuery`
+
+This can be used to support queries like `span-near` or `span-or` across different fields, which is not ordinarily permitted.
+
+Span field masking query is invaluable in conjunction with *multi-fields* when same content is indexed with multiple analyzers. For instance we could index a field with the standard analyzer which breaks text up into words, and again with the english analyzer which stems words into their root form.
+
+Example:
+
+[source,js]
+--------------------------------------------------
+GET /_search
+{
+  "query": {
+    "span_near": {
+      "clauses": [
+        {
+          "span_term": {
+            "text": "quick brown"
+          }
+        },
+        {
+          "field_masking_span": {
+            "query": {
+              "span_term": {
+                "text.stems": "fox"
+              }
+            },
+            "field": "text"
+          }
+        }
+      ],
+      "slop": 5,
+      "in_order": false
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+Note: as span field masking query returns the masked field, scoring will be done using the norms of the field name supplied. This may lead to unexpected scoring behaviour.

docs/reference/query-dsl/span-queries.asciidoc

@@ -47,6 +47,9 @@ Accepts a list of span queries, but only returns those spans which also match a
 The result from a single span query is returned as long is its span falls
 within the spans returned by a list of other span queries.
 
+<<query-dsl-span-field-masking-query,`field_masking_span` query>>::
+
+Allows queries like `span-near` or `span-or` across different fields.
 
 include::span-term-query.asciidoc[]
 
@@ -63,3 +66,5 @@ include::span-not-query.asciidoc[]
 include::span-containing-query.asciidoc[]
 
 include::span-within-query.asciidoc[]
+
+include::span-field-masking-query.asciidoc[]