geo_distance query options mismatch

[craigtaverner]

The documentation for the geo_distance query claims it supports the following options:

• distance: examples all show strings with units, like "12km"
• distance_type: ARC or PLANE
• _name: Optional name field to identify the query (what does this mean)?
• validation_method: IGNORE_MALFORMED, COERCE or STRICT (default)

Looking at the code there is parsing support for much more, so we did a code review to see what actually happens for the features that are documented and for undocumented, but coded options as well:

field	docs	parsing	lucene query
_name	"Optional name field to identify the query"	Parsed as queryName	distance query gets wrapped by NamedQuery
_boost	N/A	Parsed as boost	distance query gets wrapped by a BoostQuery
distance	"12km" - link to units docs	parsed as float or string, within the specified units (default meters), and then converted to the unit specified below (default meters)	assumes distance in meters
unit	N/A	parsed according to unit docs, and used to convert distance value	Invalid, if we specify anything other than meters (default)
distance_type	Described as arc (default) or plane	parsed as arc or plane	Completely unused in Lucene query, and lucene Circle2D uses haversine distance internally, which is what arc implies
validation_method	IGNORE_MALFORMED, COERCE or STRICT (default)	Parsed as described	If NOT IGNORE_MALFORMED, then exception is thrown on malformed center point, if COERCE, then point is normalized before passing to Lucene
ignore_unmapped	N/A	Parsed as true/false (default false)	If true and field is not mapped, use MatchNoDocsQuery, else throw exception

From this analysis it would seem we should:

• Remove support and documentation for:
  • distance_type (silently ignored, will be arc no matter what the user puts here)
  • unit (will result in incorrect answers for anything other than meters)
• Add documentation for:
  • ignore_unmapped
  • boost

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticsearchmachine]

Pinging @elastic/es-analytical-engine (Team:Analytics)