WARNING: Version 1.5 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

edit

Migrating to aggregations

edit

Facets 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

edit

In 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

edit

There 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

edit

There 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

edit

The 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

edit

Facets 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

edit

Facet 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

edit

Aggregations 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.

« Geo Distance Facets Suggesters »