NAME

App::ElasticSearch::Utilities::Aggregations - Code to simplify creating and working with Elasticsearch aggregations

VERSION

version 8.7

FUNCTIONS

is_single_stat()

Returns true if an aggregation returns a single value.

expand_aggregate_string( token )

Takes a simplified aggregation grammar and expands it the full aggregation hash.

Simple Terms:

field_name

To

{
    field_name => {
        terms => {
            field => 'field_name',
            size  => 20,
        }
    }
}

Alias expansion:

alias=field_name

To

{
    alias => {
        terms => {
            field => 'field_name',
            size  => 20,
        }
    }
}

Parameters:

alias=field_name:10

To

{
    alias => {
        terms => {
            field => 'field_name',
            size  => 10,
        }
    }
}

Parameters, k/v:

alias=field_name:size=13

To

{
    alias => {
        terms => {
            field => 'field_name',
            size  => 13,
        }
    }
}

es_flatten_aggregations()

Takes the aggregations section of the query result and parses it into a flat structure so each row contains all the sub aggregation information.

It returns an array reference, containing arrray references. The individual rows of the array are ordered in a depth first fashion. The array does include a key for every value, so the array can be cast to a hash safely.

Aggregations

List of supported aggregations. Other aggregation may work, but these have defined behavior.

Bucket Aggregations

These aggregations will support sub aggregations.

terms

The default aggregation if none is specified.

field_name
terms:field_name

Results in

{
    "field_name": {
        "terms": {
            "field": "field_name"
        }
    }
}

Supports a positional parameter: size

field_name:20
terms:field_name:20

Results in

{
    "field_name": {
        "terms": {
            "field": "field_name",
            "size": 20
        }
    }
}

significant_terms

Same as terms.

significant_terms:field_name:10

Results in:

{
    "rare_terms.field_name": {
        "terms": {
            "field": "field_name",
            "size": 10
        }
    }
}

rare_terms

Same as terms but the positional parameter is the max_doc_count.

rare_terms:field_name:10

Results in:

{
    "rare_terms.field_name": {
        "terms": {
            "field": "field_name",
            "max_doc_count": 10
        }
    }
}

histogram

Creates a histogram for numeric fields. Positional parameter is the interval.

histogram:field_name:10

Results in:

{
    "histogram.field_name": {
        "histogram": {
            "field": "field_name",
            "interval": 10
        }
    }
}

date_histogram

Creates a histogram for date fields. Positional parameter is the calendar_interval.

date_histogram:field_name:1h

Results in:

{
    "histogram.field_name": {
        "histogram": {
            "field": "field_name",
            "calendar_interval": "1h"
        }
    }
}

geohash_grid

Creates a geohash grid bucket aggregation. Positional parameter is the precision.

geohash_grid:field_name:6

Results in:

{
    "geohash_grid.field_name": {
        "geohash_grid": {
            "field": "field_name",
            "precision": 6
        }
    }
}

missing

Creates a bucket for documents missing the field. No positional parameters.

missing:field_name

Results in:

{
    "missing.field_name": {
        "missing": {
            "field": "field_name"
        }
    }
}

Metric Aggregations

Aggregations that generate metrics from enclosing buckets.

avg, max, min, sum

Single stat metric aggregations to generate the various single statistics over the enclosing bucket.

sum:field_name

Results in

{
    "sum.field_names": {
        "sum": {
            "field": "field_name"
        }
    }
}

cardinality

Computes the unique count of terms in a field.

cardinality:field_name

Results in

{
    "cardinality.field_names": {
        "cardinality": {
            "field": "field_name"
        }
    }
}

stats

Runs the stats aggregation that returns min, max, avg, sum, and count.

stats:field_name

Results in

{
    "stats.field_names": {
        "stats": {
            "field": "field_name"
        }
    }
}

extended_stats

Runs the stats aggregation that returns the same data as the sum aggregation plus variance, sum of squares, and standard deviation.

extended_stats:field_name

Results in

{
    "extended_stats.field_names": {
        "extended_stats": {
            "field": "field_name"
        }
    }
}

percentiles

Computes percentiles for the enclosing bucket. The positional parameter is interpretted at the percents computed. If ommitted, the percentiles computed will be: 25, 50, 75, 90.

percentiles:field_name:75,95,99

Results in

{
    "percentiles.field_names": {
        "percentiles": {
            "field": "field_name",
            "percents": [ 75, 95, 99 ]
        }
    }
}

geo_centroid

Computes center of a group of geo points. No positional parameters supported.

geo_centroid:field_name

Results in

{
    "geo_centroid.field_names": {
        "geo_centroid": {
            "field": "field_name"
        }
    }
}

AUTHOR

Brad Lhotsky <brad@divisionbyzero.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023 by Brad Lhotsky.

This is free software, licensed under:

The (three-clause) BSD License

cpanm App::ElasticSearch::Utilities

perl -MCPAN -e shell
install App::ElasticSearch::Utilities