Skip to content

Refine geo-point and geo-shape docs #90913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 26, 2022
Merged

Refine geo-point and geo-shape docs #90913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6ade09d
Refine geo-point and geo-shape docs
craigtaverner Oct 14, 2022
e72a204
Update docs/reference/mapping/types/geo-point.asciidoc
craigtaverner Oct 26, 2022
14b2431
Update docs/reference/mapping/types/geo-shape.asciidoc
craigtaverner Oct 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs/reference/mapping/types/geo-point.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,12 @@ Fields of type `geo_point` accept latitude-longitude pairs, which can be used:

* to find geopoints within a <<query-dsl-geo-bounding-box-query,bounding box>>,
within a certain <<query-dsl-geo-distance-query,distance>> of a central point,
or within a <<query-dsl-geo-polygon-query,polygon>> or within a <<query-dsl-geo-shape-query,`geo_shape` query>>.
* to aggregate documents <<search-aggregations-bucket-geohashgrid-aggregation,geographically>>
or by <<search-aggregations-bucket-geodistance-aggregation,distance>> from a central point.
or within a <<query-dsl-geo-shape-query,`geo_shape` query>> (for example, points in a polygon).
* to aggregate documents by <<search-aggregations-bucket-geodistance-aggregation,distance>> from a central point
* to aggregate documents by geographic grids: either
<<search-aggregations-bucket-geohashgrid-aggregation,`geo_hash`>>,
<<search-aggregations-bucket-geotilegrid-aggregation,`geo_tile`>> or
<<search-aggregations-bucket-geohexgrid-aggregation,`geo_hex`>>.
* to integrate distance into a document's <<query-dsl-function-score-query,relevance score>>.
* to <<geo-sorting,sort>> documents by distance.

Expand Down
24 changes: 17 additions & 7 deletions docs/reference/mapping/types/geo-shape.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,28 @@
++++

The `geo_shape` data type facilitates the indexing of and searching
with arbitrary geoshapes such as rectangles and polygons. It should be
used when either the data being indexed or the queries being executed
contain shapes other than just points.
with arbitrary geoshapes such as rectangles, lines and polygons. If the data being
indexed contains shapes other than just points, it is necessary to use this mapping.
If the data contains only points, it can be indexed as either
<<geo-point,`geo_point`>> or `geo_shape`.

You can query documents using this type using
a <<query-dsl-geo-shape-query,`geo_shape` query>>.
Documents using this type can be used:

* to find geoshapes within:
** a <<query-dsl-geo-bounding-box-query,bounding box>>
** a certain <<query-dsl-geo-distance-query,distance>> of a central point
** a <<query-dsl-geo-shape-query,`geo_shape` query>> (for example, intersecting polygons).
* to aggregate documents by geographic grids:
** either <<search-aggregations-bucket-geohashgrid-aggregation,`geo_hash`>>
** or <<search-aggregations-bucket-geotilegrid-aggregation,`geo_tile`>>.

Grid aggregations over `geo_hex` grids are not supported for `geo_shape` fields.

[[geo-shape-mapping-options]]
[discrete]
==== Mapping Options

The `geo_shape` mapping maps GeoJSON geometry objects to the `geo_shape`
The `geo_shape` mapping maps GeoJSON or WKT geometry objects to the `geo_shape`
type. To enable it, users must explicitly map fields to the `geo_shape`
type.

Expand Down Expand Up @@ -258,7 +268,7 @@ POST /example/_doc

A polygon's orientation indicates the order of its vertices: `RIGHT`
(counterclockwise) or `LEFT` (clockwise). {es} uses a polygon’s orientation to
determine if it crosses the international dateline (+/-180° longitude).
determine if it crosses the international dateline (+/-180° longitude).

You can set a default orientation for WKT polygons using the
<<geo-shape-mapping-options,`orientation` mapping parameter>>. This is because
Expand Down
15 changes: 7 additions & 8 deletions docs/reference/query-dsl/geo-shape-query.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,14 @@
<titleabbrev>Geoshape</titleabbrev>
++++

Filter documents indexed using the `geo_shape` or `geo_point` type.
Filter documents indexed using either the <<geo-shape,`geo_shape`>> or the
<<geo-point,`geo_point`>> type.

Requires the <<geo-shape,`geo_shape` mapping>> or the
<<geo-point,`geo_point` mapping>>.

The `geo_shape` query uses the same grid square representation as the
`geo_shape` mapping to find documents that have a shape that is related
to the query shape, using a specified spatial relationship: either intersects,
The `geo_shape` query uses the same <<geoshape-indexing-approach, index>> as
the `geo_shape` or `geo_point` mapping to find documents that have a shape that
is related to the query shape, using a specified
<<geo-shape-spatial-relations, spatial relationship>>: either intersects,
contained, within or disjoint.
It will also use the same Prefix Tree configuration as defined for the field mapping.

The query supports two ways of defining the query shape, either by
providing a whole shape definition, or by referencing the name of a shape
Expand Down Expand Up @@ -229,6 +227,7 @@ GET /example/_search
--------------------------------------------------


[[geo-shape-spatial-relations]]
==== Spatial relations

The following is a complete list of spatial relation operators available when
Expand Down