kibana/docs/maps/maps-aggregations.asciidoc

[role="xpack"]
[[maps-aggregations]]
== Plot big data without plotting too much data

The Maps application uses {ref}/search-aggregations.html[aggregations] to plot large data sets without overwhemling your network or your browser.

Aggregations group your documents into buckets and calculate metrics for each bucket.
Your documents stay in Elasticsearch and only the metrics for each group are returned to your computer.


[float]
[[maps-grid-aggregation]]
=== Grid aggregation

The *Grid aggregation* source uses {ref}/search-aggregations-bucket-geotilegrid-aggregation.html[GeoTile grid aggregation] to group your documents into grids. You can calculate metrics for each gridded cell.

You can symbolize grid aggregation metrics as:

*Points*:: Creates a <<vector-layer, vector layer>> with a point for each gridded cell.
The point location is the weighted centroid for all geo-points in the gridded cell.

*Grid rectangles*:: Creates a <<vector-layer, vector layer>> with a bounding box polygon for each gridded cell.

*Heat map*:: Creates a <<heatmap-layer, heat map layer>> that clusters the weighted centroids for each gridded cell.


[float]
[[maps-top-hits-aggregation]]
=== Most recent entities

Most recent entities uses {es} {ref}/search-aggregations-bucket-terms-aggregation.html[terms aggregation] to group your documents by entity.
Then, {ref}/search-aggregations-metrics-top-hits-aggregation.html[top hits metric aggregation] accumulates the most recent documents for each entry.

Most recent entities is only available for vector layers with *Documents* source.
To enable most recent entities, click "Show most recent documents by entity" and configure the following:

. Set *Entity* to the field that identifies entities in your documents.
This field will be used in the terms aggregation to group your documents into entity buckets.
. Set *Time* to the date field that puts your documents in chronological order.
This field will be used to sort your documents in the top hits aggregation.
. Set *Documents per entity* to configure the maximum number of documents accumulated per entity.


[float]
[[terms-join]]
=== Terms join

Terms joins use a shared key to combine the results of an {es} 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 https://www.elastic.co/elastic-maps-service[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[]