WARNING: Version 1.7 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Migrating to aggregations
editMigrating to aggregations
editFacets have been deprecated in favor of aggregations and as such it is recommended to migrate existing code using facets to aggregations.
It is recommended to read the documentation about aggregations before this section.
Simple cases
editIn quite a number of cases, the migration is rather straightforward as simple
facets have their direct aggregation equivalent and the only thing that is
required is to replace facets
with aggs
.
For instance:
{ "facets" : { "wow" : { "filter" : { "term" : { "tag" : "wow" } } } } }
can be translated to the following aggregation:
{ "aggs" : { "wow" : { "filter" : { "term" : { "tag" : "wow" } } } } }
We will now spend more time on facets that don’t have their direct aggregation equivalent and need more modifications.
Query facets
editThere is no query
aggregation so such facets must be migrated to the filter
aggregation.
For example:
{ "facets" : { "wow" : { "query" : { "query_string" : { "query" : "tag:wow" } } } } }
can be replaced with the following filter aggregation that uses the query filter:
{ "aggs" : { "wow" : { "filter" : { "query" : { "query_string" : { "query" : "tag:wow" } } } } } }
Term stats
editThere is no term_stats
aggregation, so you actually need to create a
terms aggregation that will
create buckets that will be processed with a
stats aggregation.
For example
{ "facets" : { "tag_price_stats" : { "terms_stats" : { "key_field" : "tag", "value_field" : "price" } } } }
can be replaced with
{ "aggs" : { "tags" : { "terms" : { "field" : "tag" }, "aggs" : { "price_stats" : { "stats" : { "field" : "price" } } } } } }
value_field
editThe histogram
, date_histogram
, range
and geo_distance
facets have a
value_field
parameter that allows to compute statistics per bucket. With
aggregations this needs to be changed to a sub
stats aggregation.
For example
{ "facets" : { "histo1" : { "date_histogram" : { "key_field" : "timestamp", "value_field" : "price", "interval" : "day" } } } }
can be replaced with
{ "aggs" : { "histo1" : { "date_histogram" : { "field" : "timestamp", "interval" : "day" }, "aggs" : { "price_stats" : { "stats" : { "field" : "price" } } } } } }
Global scope
editFacets allow to set a global scope by setting global : true
in the facet
definition. With aggregations, you will need to put your aggregation under a
global aggregation instead.
For example
{ "facets" : { "terms1" : { "terms" : { ... }, "global" : true } } }
can be replaced with
{ "aggs" : { "global_count" : { "global" : {}, "aggs" : { "terms1" : { "terms" : { ... } } } } } }
Facet filters
editFacet filters can be replaced with a filter aggregation.
For example
{ "facets" : { "<FACET NAME>" : { "<FACET TYPE>" : { ... }, "facet_filter" : { "term" : { "user" : "mvg" } } } } }
can be replaced with
{ "aggs" : { "filter1" : { "filter" : { "term" : { "user" : "mvg" } }, "aggs" : { "<AGG NAME>" : { "<AGG TYPE>" : { ... } } } } } }
Nested
editAggregations have a dedicated nested aggregation to deal with nested objects.
For example
{ "facets" : { "facet1" : { "terms" : { "field" : "name" }, "nested" : "obj1" } } }
can be replaced with
{ "aggs" : { "agg1" : { "nested" : { "path" : "obj1" }, "aggs" : { "agg1": { "terms": { "field" : "obj1.name" } } } } } }
Note how fields are identified with their full path instead of relative path.
Similarly, this more complex facet that combines nested
and facet filters:
{ "facets" : { "facet1" : { "terms" : { "field" : "name" }, "nested" : "obj1", "facet_filter" : { "term" : { "color" : "blue" } } } } }
can be replaced with the following aggregation, which puts a terms aggregation under a filter aggregation, and the filter aggregation under a nested aggregation:
{ "aggs" : { "nested_obj1" : { "nested" : { "path" : "obj1" }, "aggs" : { "color_filter" : { "filter" : { "term" : { "obj1.color" : "blue" } }, "aggs" : { "name_terms" : { "terms" : { "field" : "obj1.name" } } } } } } } }
In short, this aggregation first moves from the root documents to their nested
documents following the path obj1
. Then for each nested document, it filters
out those that are not blue, and for the remaining documents, it computes a
terms aggregation on the name
field.