Skip to content

Commit

Permalink
[DOCS] Correct spelling for geo terms (#76028) (#76032)
Browse files Browse the repository at this point in the history
Changes:
* Use "geopoint" when not referring to the literal field type
* Use "geoshape" when not referring to the literal field type or query type
* Use "GeoJSON" consistently
# Conflicts:
#	docs/reference/ingest/processors/enrich.asciidoc
  • Loading branch information
jrodewig authored Aug 3, 2021
1 parent a35423e commit 4d881f5
Show file tree
Hide file tree
Showing 17 changed files with 74 additions and 75 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ The specified field must be of type `geo_point` (which can only be set explicitl

* Object format: `{ "lat" : 52.3760, "lon" : 4.894 }` - this is the safest format as it is the most explicit about the `lat` & `lon` values
* String format: `"52.3760, 4.894"` - where the first number is the `lat` and the second is the `lon`
* Array format: `[4.894, 52.3760]` - which is based on the `GeoJson` standard and where the first number is the `lon` and the second one is the `lat`
* Array format: `[4.894, 52.3760]` - which is based on the GeoJSON standard where the first number is the `lon` and the second one is the `lat`

By default, the distance unit is `m` (meters) but it can also accept: `mi` (miles), `in` (inches), `yd` (yards), `km` (kilometers), `cm` (centimeters), `mm` (millimeters).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ The response for the above aggregation:
[[geocentroid-aggregation-geo-shape]]
==== Geo Centroid Aggregation on `geo_shape` fields

The centroid metric for geo-shapes is more nuanced than for points. The centroid of a specific aggregation bucket
The centroid metric for geoshapes is more nuanced than for points. The centroid of a specific aggregation bucket
containing shapes is the centroid of the highest-dimensionality shape type in the bucket. For example, if a bucket contains
shapes comprising of polygons and lines, then the lines do not contribute to the centroid metric. Each type of shape's
centroid is calculated differently. Envelopes and circles ingested via the <<ingest-circle-processor>> are treated
Expand Down Expand Up @@ -233,12 +233,12 @@ POST /places/_search?size=0
.Using `geo_centroid` as a sub-aggregation of `geohash_grid`
====
The <<search-aggregations-bucket-geohashgrid-aggregation,`geohash_grid`>>
aggregation places documents, not individual geo-points, into buckets. If a
aggregation places documents, not individual geopoints, into buckets. If a
document's `geo_point` field contains <<array,multiple values>>, the document
could be assigned to multiple buckets, even if one or more of its geo-points are
could be assigned to multiple buckets, even if one or more of its geopoints are
outside the bucket boundaries.
If a `geocentroid` sub-aggregation is also used, each centroid is calculated
using all geo-points in a bucket, including those outside the bucket boundaries.
using all geopoints in a bucket, including those outside the bucket boundaries.
This can result in centroids outside of bucket boundaries.
====
2 changes: 1 addition & 1 deletion docs/reference/indices/index-mgmt.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ image::images/index-mgmt/management_index_component_template.png[Component templ
section blank.

. Define a mapping that contains an <<object,object>> field named `geo` with a
child <<geo-point,geo-point>> field named `coordinates`:
child <<geo-point,`geo_point`>> field named `coordinates`:
+
[role="screenshot"]
image::images/index-mgmt/management-index-templates-mappings.png[Mapped fields page]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,13 @@ pipeline. In the pipeline, add an <<enrich-processor,enrich processor>> that
includes:

* Your enrich policy.
* The `field` of incoming documents used to match the geo_shape of documents
* The `field` of incoming documents used to match the geoshape of documents
from the enrich index.
* The `target_field` used to store appended enrich data for incoming documents.
This field contains the `match_field` and `enrich_fields` specified in your
enrich policy.
* The `shape_relation`, which indicates how the processor matches geo_shapes in
incoming documents to geo_shapes in documents from the enrich index. See
* The `shape_relation`, which indicates how the processor matches geoshapes in
incoming documents to geoshapes in documents from the enrich index. See
<<_spatial_relations>> for valid options and more information.

[source,console]
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/ingest/processors/enrich.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ See <<ingest-enriching-data,enrich data>> section for more information about how
| `ignore_missing` | no | false | If `true` and `field` does not exist, the processor quietly exits without modifying the document
| `override` | no | true | If processor will update fields with pre-existing non-null-valued field. When set to `false`, such fields will not be touched.
| `max_matches` | no | 1 | The maximum number of matched documents to include under the configured target field. The `target_field` will be turned into a json array if `max_matches` is higher than 1, otherwise `target_field` will become a json object. In order to avoid documents getting too large, the maximum allowed value is 128.
| `shape_relation` | no | `INTERSECTS` | A spatial relation operator used to match the <<geo-shape,geo_shape>> of incoming documents to documents in the enrich index. This option is only used for `geo_match` enrich policy types. The <<spatial-strategy, geo_shape strategy>> mapping parameter determines which spatial relation operators are available. See <<_spatial_relations>> for operators and more information.
| `shape_relation` | no | `INTERSECTS` | A spatial relation operator used to match the <<geo-shape,geoshape>> of incoming documents to documents in the enrich index. This option is only used for `geo_match` enrich policy types. The <<spatial-strategy,geoshape strategy>> mapping parameter determines which spatial relation operators are available. See <<_spatial_relations>> for operators and more information.

include::common-options.asciidoc[]
|======
50 changes: 25 additions & 25 deletions docs/reference/mapping/types/geo-point.asciidoc
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
[[geo-point]]
=== Geo-point field type
=== Geopoint field type
++++
<titleabbrev>Geo-point</titleabbrev>
<titleabbrev>Geopoint</titleabbrev>
++++

Fields of type `geo_point` accept latitude-longitude pairs, which can be used:

* to find geo-points within a <<query-dsl-geo-bounding-box-query,bounding box>>,
* 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>>.
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.
* to integrate distance into a document's <<query-dsl-function-score-query,relevance score>>.
* to <<geo-sorting,sort>> documents by distance.

There are five ways that a geo-point may be specified, as demonstrated below:
There are five ways that a geopoint may be specified, as demonstrated below:

[source,console]
--------------------------------------------------
Expand All @@ -31,7 +31,7 @@ PUT my-index-000001
PUT my-index-000001/_doc/1
{
"text": "Geo-point as an object",
"text": "Geopoint as an object",
"location": { <1>
"lat": 41.12,
"lon": -71.34
Expand All @@ -40,25 +40,25 @@ PUT my-index-000001/_doc/1
PUT my-index-000001/_doc/2
{
"text": "Geo-point as a string",
"text": "Geopoint as a string",
"location": "41.12,-71.34" <2>
}
PUT my-index-000001/_doc/3
{
"text": "Geo-point as a geohash",
"text": "Geopoint as a geohash",
"location": "drm3btev3e86" <3>
}
PUT my-index-000001/_doc/4
{
"text": "Geo-point as an array",
"text": "Geopoint as an array",
"location": [ -71.34, 41.12 ] <4>
}
PUT my-index-000001/_doc/5
{
"text": "Geo-point as a WKT POINT primitive",
"text": "Geopoint as a WKT POINT primitive",
"location" : "POINT (-71.34 41.12)" <5>
}
Expand All @@ -81,20 +81,20 @@ GET my-index-000001/_search
}
--------------------------------------------------

<1> Geo-point expressed as an object, with `lat` and `lon` keys.
<2> Geo-point expressed as a string with the format: `"lat,lon"`.
<3> Geo-point expressed as a geohash.
<4> Geo-point expressed as an array with the format: [ `lon`, `lat`]
<5> Geo-point expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
<1> Geopoint expressed as an object, with `lat` and `lon` keys.
<2> Geopoint expressed as a string with the format: `"lat,lon"`.
<3> Geopoint expressed as a geohash.
<4> Geopoint expressed as an array with the format: [ `lon`, `lat`]
<5> Geopoint expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
POINT with the format: `"POINT(lon lat)"`
<6> A geo-bounding box query which finds all geo-points that fall inside the box.
<6> A geo-bounding box query which finds all geopoints that fall inside the box.

[IMPORTANT]
.Geo-points expressed as an array or string
.Geopoints expressed as an array or string
==================================================
Please note that string geo-points are ordered as `lat,lon`, while array
geo-points are ordered as the reverse: `lon,lat`.
Please note that string geopoints are ordered as `lat,lon`, while array
geopoints are ordered as the reverse: `lon,lat`.
Originally, `lat,lon` was used for both array and string, but the array
format was changed early on to conform to the format used by GeoJSON.
Expand All @@ -121,17 +121,17 @@ The following parameters are accepted by `geo_point` fields:

<<ignore-malformed,`ignore_malformed`>>::

If `true`, malformed geo-points are ignored. If `false` (default),
malformed geo-points throw an exception and reject the whole document.
A geo-point is considered malformed if its latitude is outside the range
If `true`, malformed geopoints are ignored. If `false` (default),
malformed geopoints throw an exception and reject the whole document.
A geopoint is considered malformed if its latitude is outside the range
-90 <= latitude <= 90, or if its longitude is outside the range -180 <= longitude <= 180.
Note that this cannot be set if the `script` parameter is used.

`ignore_z_value`::

If `true` (default) three dimension points will be accepted (stored in source)
but only latitude and longitude values will be indexed; the third dimension is
ignored. If `false`, geo-points containing any more than latitude and longitude
ignored. If `false`, geopoints containing any more than latitude and longitude
(two dimensions) values throw an exception and reject the whole document. Note
that this cannot be set if the `script` parameter is used.

Expand Down Expand Up @@ -165,9 +165,9 @@ The following parameters are accepted by `geo_point` fields:
<<runtime-mapping-fields,runtime equivalent>>, and should emit points
as a pair of (lat, lon) double values.

==== Using geo-points in scripts
==== Using geopoints in scripts

When accessing the value of a geo-point in a script, the value is returned as
When accessing the value of a geopoint in a script, the value is returned as
a `GeoPoint` object, which allows access to the `.lat` and `.lon` values
respectively:

Expand Down
26 changes: 13 additions & 13 deletions docs/reference/mapping/types/geo-shape.asciidoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[geo-shape]]
=== Geo-shape field type
=== Geoshape field type
++++
<titleabbrev>Geo-shape</titleabbrev>
<titleabbrev>Geoshape</titleabbrev>
++++

The `geo_shape` data type facilitates the indexing of and searching
Expand All @@ -10,14 +10,14 @@ used when either the data being indexed or the queries being executed
contain shapes other than just points.

You can query documents using this type using
<<query-dsl-geo-shape-query,geo_shape Query>>.
a <<query-dsl-geo-shape-query,`geo_shape` query>>.

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

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

[cols="<,<,<",options="header",]
Expand Down Expand Up @@ -122,7 +122,7 @@ entire document.

|`ignore_z_value` |If `true` (default) three dimension points will be accepted (stored in source)
but only latitude and longitude values will be indexed; the third dimension is ignored. If `false`,
geo-points containing any more than latitude and longitude (two dimensions) values throw an exception
geopoints containing any more than latitude and longitude (two dimensions) values throw an exception
and reject the whole document.
| `true`

Expand Down Expand Up @@ -462,8 +462,8 @@ POST /example/_doc
--------------------------------------------------
// TEST[catch:/mapper_parsing_exception/]

An `orientation` parameter can be defined when setting the geo_shape mapping (see <<geo-shape-mapping-options>>). This will define vertex
order for the coordinate list on the mapped geo_shape field. It can also be overridden on each document. The following is an example for
An `orientation` parameter can be defined when setting the `geo_shape` mapping (see <<geo-shape-mapping-options>>). This will define vertex
order for the coordinate list on the mapped `geo_shape` field. It can also be overridden on each document. The following is an example for
overriding the orientation on a document:

[source,console]
Expand All @@ -484,7 +484,7 @@ POST /example/_doc
[[geo-multipoint]]
===== http://geojson.org/geojson-spec.html#id5[MultiPoint]

The following is an example of a list of geojson points:
The following is an example of a list of GeoJSON points:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -513,7 +513,7 @@ POST /example/_doc
[[geo-multilinestring]]
===== http://geojson.org/geojson-spec.html#id6[MultiLineString]

The following is an example of a list of geojson linestrings:
The following is an example of a list of GeoJSON linestrings:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -544,7 +544,7 @@ POST /example/_doc
[[geo-multipolygon]]
===== http://geojson.org/geojson-spec.html#id7[MultiPolygon]

The following is an example of a list of geojson polygons (second polygon contains a hole):
The following is an example of a list of GeoJSON polygons (second polygon contains a hole):

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -575,7 +575,7 @@ POST /example/_doc
[[geo-geometry_collection]]
===== http://geojson.org/geojson-spec.html#geometrycollection[Geometry Collection]

The following is an example of a collection of geojson geometry objects:
The following is an example of a collection of GeoJSON geometry objects:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -693,5 +693,5 @@ the units of the `radius` will default to `METERS`.

Due to the complex input structure and index representation of shapes,
it is not currently possible to sort shapes or retrieve their fields
directly. The geo_shape value is only retrievable through the `_source`
directly. The `geo_shape` value is only retrievable through the `_source`
field.
16 changes: 8 additions & 8 deletions docs/reference/mapping/types/shape.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ You can query documents using this type using
[discrete]
==== Mapping Options

Like the <<geo-shape, geo_shape>> field type, the `shape` field mapping maps
Like the <<geo-shape,`geo_shape`>> field type, the `shape` field mapping maps
http://geojson.org[GeoJSON] or https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
(WKT) geometry objects to the shape type. To enable it, users must explicitly map
fields to the shape type.
Expand All @@ -34,8 +34,8 @@ different ways. 1. Right-hand rule: `right`, `ccw`, `counterclockwise`,
2. Left-hand rule: `left`, `cw`, `clockwise`. The default orientation
(`counterclockwise`) complies with the OGC standard which defines
outer ring vertices in counterclockwise order with inner ring(s) vertices (holes)
in clockwise order. Setting this parameter in the geo_shape mapping explicitly
sets vertex order for the coordinate list of a geo_shape field but can be
in clockwise order. Setting this parameter in the `geo_shape` mapping explicitly
sets vertex order for the coordinate list of a `geo_shape` field but can be
overridden in each individual GeoJSON or WKT document.
| `ccw`

Expand All @@ -46,7 +46,7 @@ entire document.

|`ignore_z_value` |If `true` (default) three dimension points will be accepted (stored in source)
but only latitude and longitude values will be indexed; the third dimension is ignored. If `false`,
geo-points containing any more than latitude and longitude (two dimensions) values throw an exception
geopoints containing any more than latitude and longitude (two dimensions) values throw an exception
and reject the whole document.
| `true`

Expand Down Expand Up @@ -279,7 +279,7 @@ POST /example/_doc
[[multipoint]]
===== http://geojson.org/geojson-spec.html#id5[MultiPoint]

The following is an example of a list of geojson points:
The following is an example of a list of GeoJSON points:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -308,7 +308,7 @@ POST /example/_doc
[[multilinestring]]
===== http://geojson.org/geojson-spec.html#id6[MultiLineString]

The following is an example of a list of geojson linestrings:
The following is an example of a list of GeoJSON linestrings:

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -339,7 +339,7 @@ POST /example/_doc
[[multipolygon]]
===== http://geojson.org/geojson-spec.html#id7[MultiPolygon]

The following is an example of a list of geojson polygons (second polygon contains a hole):
The following is an example of a list of GeoJSON polygons (second polygon contains a hole):

[source,console]
--------------------------------------------------
Expand Down Expand Up @@ -370,7 +370,7 @@ POST /example/_doc
[[geometry_collection]]
===== http://geojson.org/geojson-spec.html#geometrycollection[Geometry Collection]

The following is an example of a collection of geojson geometry objects:
The following is an example of a collection of GeoJSON geometry objects:

[source,console]
--------------------------------------------------
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ For example, JSON data might contain the following transaction coordinates:
// NOTCONSOLE

In {es}, location data is likely to be stored in `geo_point` fields. For more
information, see {ref}/geo-point.html[Geo-point data type]. This data type is
information, see {ref}/geo-point.html[`geo_point` data type]. This data type is
supported natively in {ml-features}. Specifically, {dfeed} when pulling data from
a `geo_point` field, will transform the data into the appropriate `lat,lon` string
format before sending to the {anomaly-job}.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -421,7 +421,7 @@ The preview {dfeed} API returns the following results, which show that


[[ml-configuring-transform8]]
.Example 8: Transforming geo_point data
.Example 8: Transforming geopoint data

[source,console]
--------------------------------------------------
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/query-dsl/function-score-query.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,7 @@ decay function is specified as
--------------------------------------------------
// NOTCONSOLE
<1> The `DECAY_FUNCTION` should be one of `linear`, `exp`, or `gauss`.
<2> The specified field must be a numeric, date, or geo-point field.
<2> The specified field must be a numeric, date, or geopoint field.

In the above example, the field is a <<geo-point,`geo_point`>> and origin can
be provided in geo format. `scale` and `offset` must be given with a unit in
Expand Down Expand Up @@ -656,7 +656,7 @@ image::https://f.cloud.github.com/assets/4320215/768165/19d8b1aa-e899-11e2-91bc-

==== Supported fields for decay functions

Only numeric, date, and geo-point fields are supported.
Only numeric, date, and geopoint fields are supported.

==== What if a field is missing?

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/query-dsl/geo-bounding-box-query.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ query.
[discrete]
==== Accepted Formats

In much the same way the geo_point type can accept different
In much the same way the `geo_point` type can accept different
representations of the geo point, the filter can accept it as well:

[discrete]
Expand Down
Loading

0 comments on commit 4d881f5

Please sign in to comment.