[Maps] docs (#32130) (#32416)

* [Maps] docs

* unique ids

* use hyphen instead of underscore in file names

* get everything working

* add screen shots of layer types

* add sources to layer documentation

* terms join example

* vector styling

* clean up

* link to geo_point for grid agg source

* minor clean up

* review feedback

* Update docs/maps/index.asciidoc

Co-Authored-By: nreese <reese.nathan@gmail.com>

* Update docs/maps/heatmap-layer.asciidoc

Co-Authored-By: nreese <reese.nathan@gmail.com>

* Update docs/maps/heatmap-layer.asciidoc

Co-Authored-By: nreese <reese.nathan@gmail.com>

* Update docs/maps/heatmap-layer.asciidoc

Co-Authored-By: nreese <reese.nathan@gmail.com>

* rest of changes suggested by gchaps

* update terms join intro

docs/index.asciidoc

@@ -44,6 +44,8 @@ include::canvas.asciidoc[]
 
 include::ml/index.asciidoc[]
 
+include::maps/index.asciidoc[]
+
 include::infrastructure/index.asciidoc[]
 
 include::logs/index.asciidoc[]
@@ -84,4 +86,4 @@ include::migration.asciidoc[]
 
 include::CHANGELOG.asciidoc[]
 
-include::redirects.asciidoc[]
+include::redirects.asciidoc[]

docs/maps/heatmap-layer.asciidoc

@@ -0,0 +1,17 @@
+[[heatmap-layer]]
+== Heat map layer
+
+In the heat map layer, point data is clustered to show locations with higher densities.
+
+[role="screenshot"]
+image::maps/images/heatmap_layer.png[]
+
+You can create a heat map layer from the following data source:
+
+*Grid aggregation*:: Geospatial data grouped in grids with metrics for each gridded cell.
+Set *Show as* to *heat map*.
+The index must contain at least one field mapped as {ref}/geo-point.html[geo_point].
+
+NOTE: Only count and sum metric aggregations are available with the grid aggregation source and heat map layers.
+Mean, median, min, and max are turned off because the heat map will blend nearby values.
+Blending two average values would make the cluster more prominent, even though it just might literally mean that these nearby areas are average.

docs/maps/index.asciidoc

@@ -0,0 +1,18 @@
+[[maps]]
+= Maps
+
+[partintro]
+--
+
+beta[]
+
+The **Maps** application enables you to parse through your geographical data at scale, with speed, and in real time. With features like multiple layers and indices in a map, plotting of raw documents, dynamic client-side styling, and global search across multiple layers, you can understand and monitor your data with ease.
+
+[role="screenshot"]
+image::maps/images/sample_data_ecommerce.png[]
+
+--
+
+include::heatmap-layer.asciidoc[]
+include::tile-layer.asciidoc[]
+include::vector-layer.asciidoc[]

docs/maps/terms-join.asciidoc

@@ -0,0 +1,94 @@
+[[terms-join]]
+=== Terms join
+
+Terms joins use a shared key to combine the results of an Elasticsearch terms aggregation and vector features.
+You can augment vector features with property values that symbolize features and provide richer tooltip content.
+
+[role="screenshot"]
+image::maps/images/terms_join.png[]
+
+Follow the example below to understand how *Terms joins* work.
+This example uses Elastic Maps Service(EMS) World Countries as the vector source and
+the Kibana sample data set "Sample web logs" as the Elasticsearch index.
+
+Example feature from World Countries:
+--------------------------------------------------
+{
+  geometry: {
+    coordinates: [...],
+    type: "Polygon"
+  },
+  properties: {
+    name: "Sweden",
+    iso2: "SE",
+    iso3: "SWE"
+  },
+  type: "Feature"
+}
+--------------------------------------------------
+
+Example documents from Sample web logs:
+--------------------------------------------------
+{
+  bytes: 1837,
+  geo: {
+    src: "SE"
+  },
+  timestamp: "Feb 28, 2019 @ 07:23:08.754"
+},
+{
+  bytes: 971,
+  geo: {
+    src: "SE"
+  },
+  timestamp: "Feb 27, 2019 @ 08:10:45.205"
+},
+{
+  bytes: 4277,
+  geo: {
+    src: "SE"
+  },
+  timestamp: "Feb 21, 2019 @ 05:24:33.945"
+},
+{
+  bytes: 5624,
+  geo: {
+    src: "SE"
+  },
+  timestamp: "Feb 21, 2019 @ 04:57:05.921"
+}
+--------------------------------------------------
+
+The JOIN configuration links the vector source "World Countries" to the Elasticsearch index "kibana_sample_data_logs"
+on the shared key *iso2 = geo.src*.
+[role="screenshot"]
+image::maps/images/terms_join_shared_key_config.png[]
+
+The METRICS configuration defines two metric aggregations:
+the count of all documents in the terms bucket and
+the average of the field "bytes" for all documents in the terms bucket.
+[role="screenshot"]
+image::maps/images/terms_join_metric_config.png[]
+
+Example terms aggregation response:
+--------------------------------------------------
+{
+  aggregations: {
+    join: {
+      buckets: [
+        {
+          doc_count: 4,
+          key: "SE",
+          avg_of_bytes: {
+            value: 3177.25
+          }
+        }
+      ]
+    }
+  }
+}
+--------------------------------------------------
+
+Finally, the terms aggregation response is joined with the vector features.
+[role="screenshot"]
+image::maps/images/terms_join_tooltip.png[]

docs/maps/tile-layer.asciidoc

@@ -0,0 +1,18 @@
+[[tile-layer]]
+== Tile layer
+
+The tile layer displays image tiles served from a tile server.
+
+[role="screenshot"]
+image::maps/images/tile_layer.png[]
+
+You can create a tile layer from the following data sources:
+
+*Custom Tile Map Service*:: Map tiles configured in kibana.yml.
+See map.tilemap.url in <<settings>> for details.
+
+*Tiles*:: Map tiles from https://www.elastic.co/elastic-maps-service[Elastic Maps Service].
+
+*Tile Map Service from URL*:: Map tiles from a URL that includes the XYZ coordinates.
+
+*Web Map Service*:: Maps from OGC Standard WMS.

docs/maps/vector-layer.asciidoc

@@ -0,0 +1,24 @@
+[[vector-layer]]
+== Vector layer
+
+The vector layer displays points, lines, and polygons.
+
+[role="screenshot"]
+image::maps/images/vector_layer.png[]
+
+You can create a vector layer from the following sources:
+
+*Custom vector shapes*:: Vector shapes from static files configured in kibana.yml.
+See map.regionmap.* in <<settings>> for details.
+
+*Documents*:: Geospatial data from a Kibana index pattern.
+The index must contain at least one field mapped as {ref}/geo-point.html[geo_point] or {ref}/geo-shape.html[geo_shape].
+
+*Grid aggregation*:: Geospatial data grouped in grids with metrics for each gridded cell.
+Set *Show as* to *grid rectangles* or *points*.
+The index must contain at least one field mapped as {ref}/geo-point.html[geo_point].
+
+*Vector shapes*:: Vector shapes of administrative boundaries from https://www.elastic.co/elastic-maps-service[Elastic Maps Service].
+
+include::terms-join.asciidoc[]
+include::vector-style.asciidoc[]

docs/maps/vector-style.asciidoc

@@ -0,0 +1,20 @@
+[[vector-style]]
+=== Vector style
+
+*Border color*:: Defines the border color of the vector features.
+
+*Border width*:: Defines the border width of the vector features.
+
+*Fill color*:: Defines the fill color of the vector features.
+
+*Symbol size*:: Defines the symbol size of point features.
+
+Click the *link* button to toggle between static styling and data-driven styling.
+
+[role="screenshot"]
+image::maps/images/vector_style_static.png[]
+
+[role="screenshot"]
+image::maps/images/vector_style_dynamic.png[]
+
+NOTE: The *link* button is only available when your vector features contain numeric properties.