Documentation for field_masking_span query

[russcam]

It looks like field_masking_span query has been supported for a long time but remains undocumented.

It should be included in the documentation for the latest 1.x, 2.x and 5.x releases.

[russcam]

See elastic/elasticsearch-net#2231

[clintongormley]

I'm actually wondering if we should remove the field_masking_span query, which seems like it is a poor man's nested, but relying on term positions in different fields (see https://lucene.apache.org/core/2_9_4/api/core/org/apache/lucene/search/spans/FieldMaskingSpanQuery.html)

[yevhen]

@clintongormley could you please elaborate more on this? We are using 2 separate fields to analyze the same content with morphology and exact. The positions are completely equal in both fields so we can safely use FieldMaskngQuery, and we don't need scoring at this point. How would nested help us in this case? Thanks!

[clintongormley]

@yevhen ok i may have misunderstood the use cases. my understanding was that it was a workaround for multiple corresponding values in each field, eg:

{
  "users": [ 
   { "first_name": "john", "last_name": "smith" },
   { "first_name": "jack", "last_name": "white" },
  ]
}

which ends up being indexed as:

users.first_name: john, jack
users.last_name: smith, white

Nested solves this use case in a much better way.

If field_masking_span query has other use cases, then I'm happy to leave it there.

Given that you're using it, any chance you could send a PR adding the docs? (as I clearly don't understand the use case properly)

[yevhen]

@clintongormley sure, no problem. Where to add docs? I'm new to repo structure ...

[yevhen]

@clintongormley ping :)

[russcam]

@yevhen The documentation is built with the asciidoc build process in the docs repo. The source for the master branch of the elasticsearch docs is in
https://github.com/elastic/elasticsearch/tree/master/docs/reference, with the span queries living in https://github.com/elastic/elasticsearch/tree/master/docs/reference/query-dsl.

Once an asciidoc file is added for field_masking_span in the query-dsl directory, a link to it should be added to the span-queries.asciidoc file.

[yevhen]

@russcam done

[clintongormley]

@yevhen i don't see a pull request for this in our repo? Did you create one?