Aggregations

class elasticmagic.agg.Min(field=None, script=None, **kwargs)

A single-value metric aggregation that returns the minimum value among all extracted numeric values. See min agg.

search_query = search_query.aggs({
    'min_price': agg.Min(SaleDocument.price)
})
assert search_query.to_dict() == {
    'aggregations': {
        'min_price': {'min': {'field': 'price'}}}}
min_price_agg = search_query.get_result().get_aggregation('min_price')
print(min_price_agg.value)
print(min_price_agg.value_as_string)

10.0
10.0

class elasticmagic.agg.Max(field=None, script=None, **kwargs)

A single-value metric aggregation that returns the maximum value among all extracted numeric values. See max agg.

class elasticmagic.agg.Sum(field=None, script=None, **kwargs)

A single-value metric aggregation that sums up all extracted numeric values. See sum agg.

search_query = search_query.aggs({
    'prices': agg.Sum(SaleDocument.price)
})
assert search_query.to_dict() == {
    'aggregations': {
        'prices': {'sum': {'field': 'price'}}}}
prices_agg = search_query.get_result().get_aggregation('prices')
print(prices_agg.value)
print(prices_agg.value_as_string)

450.0
450.0

class elasticmagic.agg.Avg(field=None, script=None, **kwargs)

A single-value metric aggregation that computes average of all extracted numeric values. See avg agg.

class elasticmagic.agg.ValueCount(field=None, script=None, **kwargs)

A single-value metric aggregation that counts the number of all extracted values. See value_count agg.

from elasticmagic import Script

search_query = search_query.aggs({
    'types_count': agg.ValueCount(script=Script(
        inline='doc[params.field].value',
        params={'field': SaleDocument.type}
    ))
})
assert search_query.to_dict() == {
    'aggregations': {
        'types_count': {
            'value_count': {
                'script': {
                    'inline': 'doc[params.field].value',
                    'params': {'field': 'type'}}}}}}
print(search_query.get_result().get_aggregation('types_count').value)

7

class elasticmagic.agg.TopHits(size=None, from_=None, sort=None, _source=None, instance_mapper=None, **kwargs)

A top_hits metric aggregation that groups result set by certain fields via a bucket aggregator. See top_hits agg.

search_query = search_query.aggs({
    'top_tags': agg.Terms(
        SaleDocument.type, size=3,
        aggs={'top_sales_hits': agg.TopHits(
            size=1,
            sort=SaleDocument.date.desc(),
            _source={
                'includes': [SaleDocument.date, SaleDocument.price]
            }
        )}
    )
})
assert search_query.to_dict() == {
    'aggregations': {
        'top_tags': {
            'terms': {'field': 'type', 'size': 3},
            'aggregations': {
                'top_sales_hits': {
                    'top_hits': {
                        'size': 1,
                        'sort': {'date': 'desc'},
                        '_source': {'includes': ['date', 'price']}}}}}}}
top_tags = search_query.get_result().get_aggregation('top_tags')
for tag_bucket in top_tags.buckets:
    top_hit = tag_bucket.get_aggregation('top_sales_hits').hits[0]
    print(
        '{0.key} ({0.doc_count}) - {1.price}'.format(
            tag_bucket, top_hit
        )
    )

hat (3) - 200
t-shirt (3) - 175
bag (1) - 150

class elasticmagic.agg.Stats(field=None, script=None, **kwargs)

A multi-value metrics aggregation that computes stats over all extracted numeric values. See stats agg.

search_query = search_query.aggs({
    'grades_stats': agg.Stats(GradeDocument.grade)
})
assert search_query.to_dict() == {
    'aggregations': {
        'grades_stats': {'stats': {'field': 'grade'}}}}
grades_stats = search_query.get_result().get_aggregation('grades_stats')
print('count:', grades_stats.count)
print('min:', grades_stats.min)
print('max:', grades_stats.max)
print('avg:', grades_stats.avg)
print('sum:', grades_stats.sum)

count: 6
min: 60
max: 98
avg: 78.5
sum: 471

class elasticmagic.agg.ExtendedStats(field=None, script=None, **kwargs)

A multi-value metrics aggregation that computes stats over all extracted numeric values. See extended_stats agg.

This aggregation is an extended version of the Stats aggregation. There are some additional metrics: sum_of_squares, variance, std_deviation.

class elasticmagic.agg.Percentiles(field=None, script=None, percents=None, compression=None, **kwargs)

A multi-value metrics aggregation that calculates percentiles over all extracted numeric values. See percentiles agg.

Note

Percentiles are usually calculated approximately. Elasticsearch calculates them using TDigest algotighm.

search_query = search_query.aggs(
    load_time_outlier=agg.Percentiles(field=PageLoadDoc.load_time)
)
assert search_query.to_dict() == {
    'aggregations': {
        'load_time_outlier': {
            'percentiles': {'field': 'load_time'}}}}
load_time_agg = search_query.get_result()            .get_aggregation('load_time_outlier')
for p, v in load_time_agg.values[:-1]:
    print('{:<4} - {}'.format(p, v))
print('99 percentile is: {}'.format(load_time_agg.get_value(99)))

1.0  - 15.0
5.0  - 20.0
25.0 - 23.0
50.0 - 25.0
75.0 - 29.0
95.0 - 60.0
99 percentile is: 150.0

class elasticmagic.agg.PercentileRanks(field=None, script=None, values=None, compression=None, **kwargs)

A multi-value metrics aggregation that calculates percentile ranks over all extracted numeric values. See percentile_ranks agg.

search_query = search_query.aggs(
    load_time_outlier=agg.PercentileRanks(
        field=PageLoadDoc.load_time,
        values=[15, 30],
    )
)
assert search_query.to_dict() == {
    'aggregations': {
        'load_time_outlier': {
            'percentile_ranks': {
                'field': 'load_time',
                'values': [15, 30]}}}}
load_time_agg = search_query.get_result()            .get_aggregation('load_time_outlier')
for v, p in load_time_agg.values:
    print('{:<4} - {}'.format(v, p))
print(
    '{}% of values are below 15'.format(load_time_agg.get_percent(15))
)

15.0 - 92.0
30.0 - 100.0
92.0% of values are below 15

class elasticmagic.agg.Cardinality(field=None, script=None, precision_threshold=None, rehash=None, **kwargs)

A single-value metrics aggregation that calculates an approximate count of distinct values. See cardinality agg.