Agregações

As agregações otimizam a realização de buscas complexas, tornando-as mais rápidas e fáceis. Várias buscas podem ser agregadas, sendo realizadas e exibidas como uma única requisição e resultado final. Isso aumenta a performance e melhora a experiência do usuário. Em comparação com buscas (queries), agregações consomem mais CPU e memória.

Toda agregação é uma combinação de um ou mais buckets e zero ou mais metrics.

Por exemplo, na query

SELECT COUNT(status_code)
FROM table
GROUP BY status_code

COUNT(status_code) equivale a uma metric e
GROUP BY status_code equivale a um bucket.

A seguir, veja mais sobre:

Buckets

Buckets criam grupos de documentos com base em um determinado critério, dependendo do tipo de agregação. O conceito vem da ideia de agrupar os documentos em baldes (tradução de buckets). Buckets não calculam métricas, como fazem as metrics.

Como exemplos de agrupamento em buckets: a data 2022-12-19 estaria no bucket (balde) de December (dezembro) e a cidade de Campinas, no bucket do estado de São Paulo.

Buckets podem estar contidos dentro de outros buckets. Por exemplo, Campinas entraria no bucket do estado de São Paulo e todo o bucket de São Paulo estaria no bucket do Brasil.

Veja na tabela a seguir a descrição dos principais tipos de buckets. A imagem abaixo mostra uma parte da tela Visualize com a lista para escolher o tipo de bucket. Veja também como criar uma nova visualização e saiba como chegar nesta tela para escolha do tipo de bucket.

detalhe da tela de visualize com os tipos de buckets


Principais tipos de buckets

Tipo

Definição

Parâmetros

Histogram (histograma)

Agrupa os documentos em buckets dinamicamente, com base em intervalos específicos (valores numéricos ou intervalos numéricos). Similar à agregação por range; porém, ao invés de determinar cada intervalo especificamente, você pode ativar a opção use auto interval (use intervalo automático) ou informar um número para o intervalo mínimo. Exemplo de uso: exibir a quantidade de um evento (e.g., número de respostas com erro 400) que ocorre a cada mês.

Minimum interval: selecione Use auto interval ou especifique o intervalo mínimo.

Date histogram (histograma de datas)

Semelhante ao histograma simples, porém, usado apenas com valores de datas ou intervalo de datas.
A diferença para o histograma simples é que date histogram entende os conceitos de um calendário (e.g., sabe que dezembro tem mais dias que fevereiro, diferencia fusos horários). Histograma simples interpreta datas como números.

Minimum interval: especifique o intevalo mínimo de arredondamento. Por padrão, Auto vem selecionado. Outras unidades aceitas: milisegundo, segundo, minuto, hora, dia, semana, mês e ano.

Range (intervalo)

Define um conjuto de intervalos, cada um representando um bucket. Cada documento é verificado de acordo com a faixa de variação do seu intervalo e agrupado conforme sua relevância ou correspondência a essa faixa, que pode ser numérica, de datas ou de endereço de IP. Exemplo de uso: na busca por determinado tipo de produto em uma loja online, range pode exiber a faixa de preços mais popular para aquele tipo de produto.

_>=_: informe o valor do início do intervalo
_<__: informe o valor do fim do intervalo

Date range (intervalo de datas)

Agregação de range (intevalo) específico para datas.

Acceptable date formats: determine o início e fim do intevalo.
Exemplo:
from: now-1w/w < agora menos 1 semana, arredondado para o início da semana.
to:now >= agora menos 1 semana, arredondado para o início da semana.

Filters (filtros)

Agregação na qual cada bucket contém documentos que correspondem a uma busca. É possível definir mais de um filtro.

Filter: forneça a expressão de busca. Pode ser escrita em DQL ou Lucene. Clique em + Add filter para adicionar mais outro filtro.

NOTE: Selecione Lucene ou DQL e utilize a sintaxe correspondente. Para que uma query escrita em Lucene seja interpretada corretamente, é necessário selecionar Lucene. O mesmo é válido para DQL.

Terms (termos)

Agrupa por categorias e recupera o total de documentos de cada categoria. Ou seja, terms informa o número de vezes que determinado termo aparece nos seus documentos.

Order by define o tipo de ordenação com base na métrica (metrics) selecionada, podendo ser:
Custom metric: métrica customizada ou
Alphabetical: alfabética.

Significant terms (termos importantes)

Retorna ocorrências de termos interessantes ou incomuns. O resultado mostrado é a diferença entre a ocorrência de um termo em todo índice e a ocorrência do mesmo termo nos resultados das suas buscas (queries), destacando os termos que são relevantes dentro de cada contexto de busca. Por exemplo, o termo "sensedia" seria relevante no contexto de "apis".

Size: defina quantos term buckets devem ser retornados da lista total de terms.

Parâmetros avançados

Tanto as agregações metrics como buckets permitem que você adicione parâmetros avançados.

Para acessar os parâmetros avançados, clique no ícone para expandir/recolher ao lado de Advanced (imagem abaixo).

Dependendo do tipo ou campo selecionado para a agregação, além do campo para inserção em formato JSON, diferentes opções podem estar disponíveis para entrada ou seleção de dados.

animação evidenciando o campo JSON input


Veja na tabela abaixo definições e exemplos de uso para os principais parâmetros avançados de agregações bucket.

As definições de cada tipo de agregação bucket e seus parâmetros básicos estão na tabela anterior.

Tipo

Parâmetros avançados

Date histogram

  • calendar_interval especifica intevalos do calendário usando o nome (e.g., month (mês)) ou unidade (e.g., 1M). Quantidades como 2M não são suportadas. 1M e +month são equivalentes. Unidades aceitas: minute ou 1m, hour ou 1h, day ou 1d, week ou 1w, month ou 1M, quarter ou 1q, year ou 1y.
    Exemplo: calendar_interval: "1M"

  • fixed_interval estabelece intervalos fixos, independente do calendário. Permite expressar múltiplos de uma unidade. Meses e trimestres não podem ser definidos como intevalos fixos por variarem. Unidades aceitas: milisegundos ms, segundos s, minutos m, horas h, dias d.
    Exemplo: "fixed_interval": "30d".

  • keys Timestamps que representam data são retornados em buckets de keys.

  • key_as_string mesmo timestamp, convertido para uma data em forma de string, cujo formato é especificado no parâmetro format.
    Exemplo: "key_as_string": "2022-12-19"

  • time-zone usado para indicar um fuso horário diferente do padrão. O fuso horário padrão usado para armazenamento é UTC.
    Exemplo: "time_zone": "-01:00"

  • offset estabelece outros intevalos dentro de uma unidade. Por exemplo, cada bucket com o intevalo day vai da meia-noite até meia-noite. Ajustando o offset para +6h, cada bucket passa a ir de 6am até 6pm.
    Exemplo: "offset": "+6h"

  • keyed quando habilitado, associa uma única string key com cada bucket e retorna os intevalos como hash, ao invés de array.
    Exemplo: "keyed": true

  • order estabelece a forma de ordenação dos resultados. Exemplos: "order": { "_key": "asc" }

  • min_doc_count define a quantidade mínima de buckets da resposta. Por padrão, o histograma retorna buckets mesmo quando a contagem é zero.

  • extended_bounds estende os limites, forçando a exibição de buckets mesmo que eles caiam antes do valor mínimo ou depois do valor máximo. min_doc_count retorna buckets vazios, porém, por padrão, retorna apenas buckets que estejam entre os valores mínimo e máximo.

Range e Date range

  • missing define como tratar valores faltantes. O padrão é ignorar tais valores. No exemplo abaixo, documentos que não possuam um valor no campo date serão adicionados ao bucket "Older" como se tivessem o valor "1976/11/30".
    Exemplo:

"missing": "1976/11/30",
"ranges":[
    {
        "key": "Older",
        "to": "2015/01/01"
    },
]

  • keyed quando habilitado, associa uma única string key com cada bucket e retorna os intevalos como hash, ao invés de array.
    Exemplo: "keyed": true

Filters

  • other_bucket adiciona um bucket à resposta, agrupando todos os documentos que não corresponderem a determinados filters. Os valores podem ser:
    false não adiciona o other (outro) bucket,
    true retorna o bucket com nome other (caso filtros com nome estejam sendo utilizados) ou como o último bucket (caso filtros anôminos estejam sendo usados).

  • other_bucket_key usado para definir outro valor para a chave other (outro) bucket, diferente do padrão other.
    Exemplo: "other_bucket_key": "other_messages"

Histogram

  • missing define como tratar valores faltantes. O padrão é ignorar tais valores. No exemplo abaixo, documentos que não possuam um valor no campo quantity serão adicionados ao mesmo bucket de documentos que possuam o valor 0.
    Exemplo:

"histogram": {
        "field": "quantity",
        "interval": 10,
        "missing": 0
      }

  • min_doc_count define a quantidade mínima de buckets da resposta. Por padrão, o histograma retorna buckets mesmo quando a contagem é zero.
    Exemplo: "min_doc_count": 1

  • extended_bounds estende os limites, forçando a exibição de buckets mesmo que eles caiam antes do valor mínimo ou depois do valor máximo. min_doc_count retorna buckets vazios, porém, por padrão, retorna apenas buckets que estejam entre os valores mínimo e máximo.
    Exemplo:

"extended_bounds" : {
                "min" : "2014-01-01",
                "max" : "2014-12-31"
            }

  • order estabelece a forma de ordenação dos resultados.
    Exemplos: "order": { "_key": "asc" }

Terms e Significant terms

  • include e exclude filtram valores para os quais os buckets serão criados. include determina quais valores são "permitidos" na agregração e exclude determina quais os valores que não entrarão na agregação. include precede exclude.

  • min_doc_count define o número mínimo de resultados retornados com as principas ocorrências. Por padrão, está configurado como 3. É recomendado não configurar como 1.
    Exemplo: "min_doc_count": 10

  • size estabelece a quantidade retornada. Por padrão, são retornados os primeiros 10 termos ou termos significativos, de acordo com a ordem selecionada. Você pode alterar o size para 0, para obter todos os termos (observe, porém, que o resultado pode ser grande, impactando CPU e rede).

  • shard_size define quantos documentos, no máximo, devem ser coletados de cada shard. Por padrão (-1), essa quantidade é estimada automaticamente, com base no número de shards e no parâmetro size. shard_size não pode ser menor que size.
    Exemplo: "shard_size": 1000

Metric aggregations

Agregações do tipo Metrics extraem estatísticas a partir de documentos agrupados em um ou mais buckets, ou de buckets vindos de outras agregações. Em linhas gerais, metrics geram um ou mais números que descrevem os documentos agrupados.

Metrics podem ser do tipo:

  • Single-value: retorna apenas uma métrica.

  • Multi-value: retorna mais de uma métrica.

Veja na tabela a seguir uma breve descrição de cada agregação metrics. A imagem abaixo mostra a parte da tela Visualize onde é feita a escolha da agregação metrics.

"detalhe da tela de visualize mostrando a seleção de metrics


Principais agregações de metrics

Metrics

Descrição

Average (média)

Agregação de métrica do tipo single-value que calcula a média para valores numéricos dos documentos contidos nos buckets. Os valores podem vir de campos de histogramas ou outros campos numéricos.

Count (contagem)

Esta métrica conta os documentos presentes em cada um dos buckets selecionados.

Sum (soma)

Agregação de métrica do tipo single-value que soma os valores numéricos dos documentos presentes nos buckets.

Max

Agregação do tipo single-value que traz o valor máximo de valores numéricos de documentos presentes nos buckets.

Median (mediana)

Agregação do tipo single-value que calcula a mediana de valores numéricos. A mediana é indicada para que valores extremamente altos ou baixos (valores atípicos) não influenciem o resultado, como acontece com a média (average).

Min

Agregação de métrica do tipo single-value que retorna o valor mínimo de valores numéricos de documentos presentes nos buckets.

Percentiles (percentis)

Agregação de métrica do tipo multi-value que calcula um ou mais percentis de valores numéricos de documentos presentes nos buckets. Percentil é a porcentagem de dados que são iguais ou menores que um determinado valor dentro uma distribuição de frequência. A distribuição padrão é [1, 5, 25, 50, 75, 95, 99]. Alternativamente, é possível escolher valores diferentes, de 0 a 100. Comumente usado para encontrar valores discrepantes. Esta métrica é uma aproximação. Exemplo de uso: em relação aos acessos à sua página, exibir o delay mais comum e quão demorados são os maiores tempos de resposta.

Percentile ranks

Agregação de metrics do tipo multi-value que calcula um ou mais percentile ranks sobre valores numéricos de documentos presentes nos buckets. O percentile rank de um dado valor é o percentil de valores iguais ou menores que um limite agrupado por um determinado valor. Por exemplo, se um valor é maior ou igual a 80% dos valores, seu percentile rank é de 80%. Útil, por exemplo, para uso em visualizações que monitorem o Service Level Agreement (SLA).

Standard deviation (desvio padrão)

Representa a variação de um grupo de valores em torno da média. Um baixo desvio padrão indica que os valores tendem a estar próximos da média ou do valor esperado.

Top hits

Agregação de metrics do tipo multi-value que ranqueia os dados mais relevantes. Recomenda-se o uso como subagregador, de modo que os documentos mais relevantes possam ser agrupados por buckets. Configurações:
- Size: defina o número máximo de top hits por bucket.
- Aggregate with: caso o size escolhido seja maior que 1, defina aqui como os resultados serão agrupados.
- Sort on: estabeleça como os top hits devem ser ordenados.

Unique count

Agregação de metrics do tipo single-value que apresenta a contagem aproximada de valores distintos em um campo. Pode ser usado, por exemplo, para visualizar o número de endereços de IP únicos que acessam seu serviço.


Pipeline aggregations

Com pipeline aggregations você pode concatenar agregações usando os resultados de uma agregação como entrada para outra agregação.

Pipeline aggregations possibilitam cálculos estatísticos mais complexos, como derivadas, somas cumulativas e médias móveis.

  • Parent pipeline: pipeline aggregation na qual resultados de uma agregação pai são usadas para calcular novos buckets ou novas agregações que serão adicionadas aos buckets existentes. É necessário que o min_doc_count para o parent pipeline seja 0, que é o valor padrão para agregações do tipo histograma. A métrica deve ser com base em valores numéricos.

  • Sibling pipeline: pipeline aggregation na qual os resultados de uma agregação irmã são usados para calcular uma nova agregação que estará no mesmo nível da agregação irmã. Necessariamente, sibling pipelines são do tipo multi-value e a métrica deve ser um valor numérico.

As agregações pipeline encontram-se na mesma lista de agregações Metrics, como mostra a imagem abaixo.

detalhe da tela visualize com destaque para a lista de metrics com pipeline aggregations

Ao selecionar uma agregação pipeline (identificado como 1 na figura abaixo), seja ela pai ou irmã, outra caixa se abre abaixo para que você possa configurar a segunda agregação (identificado como 2 na figura abaixo):

detalhe da tela visualize com destaque para a área de configuração da segunda agregação

Parent pipeline aggregations

Agregação

Descrição

Cumulative sum soma cumulativa

Calcula a soma cumulativa de uma métrica em uma agregação do tipo histograma ou date histogram pai. Esta agregação calcula o valor do campo somando o valor anterior com o atual. O resultado será um único valor representando a soma cumulativa dos valores do campo. A métrica deve ser numérica e o histograma adicionado deve ter o min_doc_count configurado como 0 (valor padrão para agregação do tipo histograma).

Derivative derivada

Calcula a derivada de uma métrica em uma agregação do tipo histograma ou date histogram pai. A métrica deve ser numérica e o histograma adicionado deve ter o min_doc_count configurado como 0 (valor padrão para agregação do tipo histograma). Derivadas descrevem a taxa de variação de uma função, para analisar e resumir dados. Pode ser usada para identificar tendências e anomalias nos dados.

Moving avg média móvel

Encontra as séries de médias de diferentes subgrupos (janelas) de um dataset. Pode ser usado para suavizar flutuações ou destacar tendências ou ciclos nos dados do tipo time_series.

Serial diff

Serial differencing é uma técnica que subtrai um valor em uma série temporal de si mesmo em um intervalo ou período diferente. Primeiramente, é necessário especificar um histograma ou date_histogram para um campo. Em seguida, pode-se adicionar uma métrica simples, como sum (soma) dentro do histograma, para então incluir o serial_diff no histograma.


Sibling pipeline aggregations

Agregação

Descrição

Average bucket

Calcula o valor médio de uma métrica específica em uma agregração do tipo sibling. A métrica deve ser numérica e a sibling aggregation deve ser do tipo multi-bucket. Especifique um intevalo mínimo. Por padrão, Auto vem selecionado. Outras unidades aceitas: milisegundo, segundo, minuto, hora, dia, semana, mês e ano.

Max bucket

Identifica o(s) bucket(s) com o valor máximo de uma determinada métrica em uma agregação irmã e devolve o valor e a chave do(s) bucket(s). A métrica deve ser numérica e a agregação irmã deve ser do tipo multi-bucket. Minimum interval: especifique o intevalo mínimo de arredondamento. Por padrão, Auto vem selecionado. Outras unidades aceitas: milisegundo, segundo, minuto, hora, dia, semana, mês e ano.

Min bucket

Identifica o(s) bucket(s) com o valor mínimo de uma determinada métrica em uma agregação irmã e devolve o valor e a chave do(s) bucket(s). A métrica deve ser numérica e a agregação irmã deve ser do tipo multi-bucket. Minimum interval: especifique o intevalo mínimo de arredondamento. Por padrão, Auto vem selecionado. Outras unidades aceitas: milisegundo, segundo, minuto, hora, dia, semana, mês e ano.

Sum bucket

Calcula a soma entre todos os buckets de uma determinada métrica em uma agregação irmã. A métrica deve ser numérica e a agregação irmã deve ser do tipo multi-bucket.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]