From 7301ebdee08e9ae9884be9e927b4c557a810d54a Mon Sep 17 00:00:00 2001 From: Kaarina Tungseth Date: Thu, 16 Jan 2020 13:58:10 -0600 Subject: [PATCH] [DOCS] Adds geocentroid note to coordinate map (#54389) (#55098) * [DOCS] Added note to coordinate map for geocentroid * Minor changes * Comments from Gail --- docs/visualize/tilemap.asciidoc | 129 ++++++++++++-------------------- 1 file changed, 48 insertions(+), 81 deletions(-) diff --git a/docs/visualize/tilemap.asciidoc b/docs/visualize/tilemap.asciidoc index a4d995982bdc7..2b499d098a956 100644 --- a/docs/visualize/tilemap.asciidoc +++ b/docs/visualize/tilemap.asciidoc @@ -1,105 +1,72 @@ [[tilemap]] -== Coordinate Maps +== Coordinate map -A coordinate map displays a geographic area overlaid with circles keyed to the data determined by the buckets you specify. +Coordinate maps display geographic areas overlaid with circles keyed to the data determined by the buckets you specify. To use coordinate maps, you plot latitude and longitude coordinates. -Kibana’s out-of-the-box settings do not show a coordinate map in the New Visualization menu. Use <> instead, which offers more functionality and is easier to use. -If you want to create new coordinate map visualizations, set `xpack.maps.showMapVisualizationTypes` to `true`. +NOTE: Coordinate maps have been replaced with <>, which offers more functionality and is easier to use. -Kibana uses the https://www.elastic.co/elastic-maps-service[Elastic Maps Service] -to display map tiles. To use other tile service providers, configure the <> +To create coordinate maps in Visualize: + +* Set `xpack.maps.showMapVisualizationTypes` to `true`. + +* To display map tiles, {kib} uses the https://www.elastic.co/elastic-maps-service[Elastic Maps Service]. +To use other tile service providers, configure the <> in `kibana.yml`. [float] -[[tilemap-configuration]] -=== Configuration +[[coordinate-map-aggregation]] +=== Supported aggregations -[float] -==== Data +Coordinate maps support the metric and bucket aggregations. [float] -===== Metrics - -The default _metrics_ aggregation for a coordinate map is the *Count* aggregation. You can select any of the following -aggregations as the metrics aggregation: - -*Count*:: The {ref}/search-aggregations-metrics-valuecount-aggregation.html[_count_] aggregation returns a raw count of -the elements in the selected index pattern. -*Average*:: This aggregation returns the {ref}/search-aggregations-metrics-avg-aggregation.html[_average_] of a numeric -field. Select a field from the drop-down. -*Sum*:: The {ref}/search-aggregations-metrics-sum-aggregation.html[_sum_] aggregation returns the total sum of a numeric -field. Select a field from the drop-down. -*Min*:: The {ref}/search-aggregations-metrics-min-aggregation.html[_min_] aggregation returns the minimum value of a -numeric field. Select a field from the drop-down. -*Max*:: The {ref}/search-aggregations-metrics-max-aggregation.html[_max_] aggregation returns the maximum value of a -numeric field. Select a field from the drop-down. -*Unique Count*:: The {ref}/search-aggregations-metrics-cardinality-aggregation.html[_cardinality_] aggregation returns -the number of unique values in a field. Select a field from the drop-down. - -Enter a string in the *Custom Label* field to change the display label. +===== Metric aggregations -[float] -===== Buckets +The following metric aggregations are supported: -Coordinate maps use the {ref}/search-aggregations-bucket-geohashgrid-aggregation.html[_geohash_] aggregation. Select a field, typically coordinates, from the -drop-down. +{ref}/search-aggregations-metrics-valuecount-aggregation.html[Count]:: Returns a raw count of +the elements in the index pattern. The default metrics aggregation for a coordinate map is *Count*. -- The _Change precision on map zoom_ box is checked by default. Uncheck the box to disable this behavior. -The _Precision_ slider determines the granularity of the results displayed on the map. See the documentation -for the {ref}/search-aggregations-bucket-geohashgrid-aggregation.html#_cell_dimensions_at_the_equator[geohash grid] -aggregation for details on the area specified by each precision level. +{ref}/search-aggregations-metrics-avg-aggregation.html[Average]:: Returns the average of a numeric +field. -NOTE: Higher precisions increase memory usage for the browser displaying Kibana as well as for the underlying -Elasticsearch cluster. +{ref}/search-aggregations-metrics-sum-aggregation.html[Sum]:: Returns the total sum of a numeric +field. -- The _place markers off grid (use {ref}/search-aggregations-metrics-geocentroid-aggregation.html[geocentroid])_ box is checked by default. When this box is checked, the markers are -placed in the center of all the documents in that bucket. When unchecked, the markers are placed in the center -of the geohash grid cell. Leaving this checked generally results in a more accurate visualization. +{ref}/search-aggregations-metrics-min-aggregation.html[Min]:: Returns the minimum value of a +numeric field. +{ref}/search-aggregations-metrics-max-aggregation.html[Max]:: Returns the maximum value of a +numeric field. -Enter a string in the *Custom Label* field to change the display label. +{ref}/search-aggregations-metrics-cardinality-aggregation.html[Unique Count]:: Returns +the number of unique values in a field. [float] -==== Options - -*Map type*:: Select one of the following options from the drop-down. -*_Scaled Circle Markers_*:: Scale the size of the markers based on the metric aggregation's value. -*_Shaded Circle Markers_*:: Displays the markers with different shades based on the metric aggregation's value. -*_Shaded Geohash Grid_*:: Displays the rectangular cells of the geohash grid instead of circular markers, with different -shades based on the metric aggregation's value. -*_Heatmap_*:: A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. -Heatmaps have the following options: - -* *Cluster size*: Adjust the size of the heatmap clustering. -* *Show Tooltip*: Check this box to have a tooltip with the values for a given dot when the cursor is on that dot. - -*Desaturate map tiles*:: Desaturate the map's color in order to make the markers stand out more clearly. -*WMS compliant map server*:: Check this box to enable the use of a third-party mapping service that complies with the Web -Map Service (WMS) standard. Specify the following elements: - -* *WMS url*: The URL for the WMS map service. -* *WMS layers*: A comma-separated list of the layers to use in this visualization. Each map server provides its own list of -layers. -* *WMS version*: The WMS version used by this map service. -* *WMS format*: The image format used by this map service. The two most common formats are `image/png` and `image/jpeg`. -* *WMS attribution*: An optional, user-defined string that identifies the map source. Maps display the attribution string -in the lower right corner. -* *WMS styles*: A comma-separated list of the styles to use in this visualization. Each map server provides its own styling -options. - -After changing options, click the *Apply changes* button to update your visualization, or the grey *Discard -changes* button to keep your visualization in its current state. +[[coordinate-bucket-aggregation]] +===== Bucket aggregation + +Coordinate maps support the {ref}/search-aggregations-bucket-geohashgrid-aggregation.html[_geohash_] bucket aggregation. + +When you deselect *Change precision on map zoom*, the *Precision* slider appears. The *Precision* slider determines the granularity of the results displayed on the map. For details on the area specified by each precision level, refer to {ref}/search-aggregations-bucket-geohashgrid-aggregation.html#_cell_dimensions_at_the_equator[geohash grid]. + +NOTE: Higher precisions increase memory usage for the browser that displays {kib} and the underlying +{es} cluster. + +When you select *Place markers off grid (use {ref}/search-aggregations-metrics-geocentroid-aggregation.html[geocentroid])*, the markers are +placed in the center of all documents in the bucket, and a more accurate visualization is created. +NOTE: When you have multiple values in the geo_point, the coordinate map is unable to accurately calculate the geo_centroid. + +When you deselect *Place markers off grid (use {ref}/search-aggregations-metrics-geocentroid-aggregation.html[geocentroid])*, the markers are placed in the center +of the geohash grid cell. [float] [[navigate-map]] -=== Navigating the Map +=== Navigate the coordinate map -Once your tilemap visualization is ready, you can explore the map in several ways: +Use the following navigation options: -* Click and hold anywhere on the map and move the cursor to move the map center. Hold Shift and drag a bounding box -across the map to zoom in on the selection. -* Click the *Zoom In/Out* image:images/viz-zoom.png[] buttons to change the zoom level manually. -* Click the *Fit Data Bounds* image:images/viz-fit-bounds.png[] button to automatically crop the map boundaries to the -geohash buckets that have at least one result. -* Click the *Latitude/Longitude Filter* image:images/viz-lat-long-filter.png[] button, then drag a bounding box across the -map, to create a filter for the box coordinates. +* To move the map center, click and hold anywhere on the map and move the cursor. +* To change the zoom level, click *Zoom In* or *Zoom out* image:images/viz-zoom.png[]. +* To automatically crop the map boundaries to the +geohash buckets that have at least one result, click *Fit Data Bounds* image:images/viz-fit-bounds.png[].