Incluir um Filtro

Use o filter() na cláusula de agregação para filtrar resultados. Por exemplo, você pode especificar o mesmo filtro que foi enviado separadamente no exemplo anterior diretamente na cláusula aggregation.

{
  "aggregation": "filter(enriched_text.entities:(text::Gilroy,type::Location)).term(enriched_text.entities.type)"
}

Nesse caso, a agregação filter().term() encontra o mesmo resultado que o exemplo anterior com as cláusulas separadas filter e aggregation. No entanto, os resultados são ranqueados de forma diferente quando a cláusula filter é usada. Você pode alavancar essa diferença usando a cláusula filter() dentro da cláusula aggregation para filtrar resultados a partir de uma sequência de expressões, como mostrado no próximo exemplo.

Início com objetos aninhados

Nos exemplos anteriores, o valor "matching_counts" representa o número de documentos que combinam com o filtro e agregação. Você pode querer contar quantos objetos aninhados estão presentes na resposta de consulta. A agregação nested() permite alterar o conjunto de documentos que é usado como entrada para outros termos de agregação.

Por exemplo, na consulta a seguir o segmento nested() seleciona todos os objetos aninhados enriched_text.entities como a entrada utilizada pelos segmentos filter() e term().

{
  "aggregation": "nested(enriched_text.entities).filter(enriched_text.entities.type::Organization).term(enriched_text.entities.text,count:3)"
}

A consulta resulta em um objeto aggregations que olha da seguinte forma:

{
  "aggregations": [
    {
      "type": "nested",
      "path": "enriched_text.entities",
      "matching_results": 1993,
      "aggregations": [
        {
          "type": "filter",
          "match": "enriched_text.entities.type::Organization",
          "matching_results": 645,
          "aggregations": [
            {
              "type": "term",
              "field": "enriched_text.entities.text",
              "count": 3,
              "results": [
                {
                  "key": "IBM",
                  "matching_results": 36
                },
                {
                  "key": "Docker",
                  "matching_results": 12
                },
                {
                  "key": "OpenShift",
                  "matching_results": 12
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

O segmento nested() da consulta encontrou 1993 enriched_text.entities objetos aninhados. O filtro foi aplicado a esses objetos e encontrou 645 enriched_text.entities do tipo Organization.

Operações de terminal

Para a maioria dos tipos de agregação, ao construir uma consulta com operações de agregação múltipla, a primeira operação é aplicada aos documentos. Em seguida, a saída dessa operação é utilizada como a entrada para a próxima operação. No entanto, um subconjunto dos tipos de agregação são operações de terminal. A saída de uma operação de terminal não é usada como entrada para a próxima agregação. Em vez disso, a saída é devolvida em um grupo discreto.

Para um exemplo de uma solicitação que combina tipos de agregação e inclui uma agregação que executa uma operação de terminal, veja o segundo exemplo para o tipo de agregação average.

Sintaxe

average(field)

Exemplo

Quando o tipo de agregação average é aplicado a um conjunto de documentos em que o campo price contém os valores que são mostrados na Tabela 1, o resultado é 325.

average(price)=325

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

{
    "query":"brake",
    "aggregation": "term(field:STATE,count:3).average(field:VEH_SPEED).term(field:CITY,count:2)"
}

Para cada estado retornado pela primeira operação de agregação term, a resposta mostra a velocidade média do veículo especificada nos relatórios de incidentes. Percebesse que a segunda agregação term usa a saída a partir da primeira agregação term, não da agregação average, como sua entrada.

{
  "matching_results": 9064,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "term",
      "field": "STATE",
      "count": 3,
      "results": [
        {
          "key": "CA",
          "matching_results": 1210,
          "aggregations": [
            {
              "type": "average",
              "field": "VEH_SPEED",
              "value": 26.239653512993264
            },
            {
              "type": "term",
              "field": "CITY",
              "count": 2,
              "results": [
                {
                  "key": "LOS ANGELES",
                  "matching_results": 77
                },
                {
                  "key": "SAN DIEGO",
                  "matching_results": 66
                }
              ]
            }
          ]
        }

Sintaxe

filter(field)

Exemplo

O exemplo a seguir filtra o conjunto de documentos correspondentes para incluir apenas documentos que mencionam IBM.

filter(enriched_text.entities.text:IBM)

Quando combinado com outras agregações, filtra os documentos correspondentes configurados para incluir apenas aqueles documentos que atendem a condição que você especifica.

{
    "query":"brake",
    "aggregation": "filter(VEH_SPEED>50).term(field:STATE,count:3).term(field:CITY,count:2)"
}

A resposta da consulta mostra cidades onde incidentes acontecem que envolvem o freio e a velocidade do veículo é superior a 50.

{
  "matching_results": 9064,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "filter",
      "match": "VEH_SPEED>50",
      "matching_results": 1075,
      "aggregations": [
        {
          "type": "term",
          "field": "STATE",
          "count": 3,
          "results": [
            {
              "key": "CA",
              "matching_results": 176,
              "aggregations": [
                {
                  "type": "term",
                  "field": "CITY",
                  "count": 2,
                  "results": [
                    {
                      "key": "FONTANA",
                      "matching_results": 6
                    },
                    {
                      "key": "ALTA LOMA",
                      "matching_results": 5
                    }
                  ]
                }
              ]
            }

Sintaxe

group_by(condition:[(condition 1),(condition 2)...])

Cada condição deve ser especificada como uma expressão válida de Query Query Language rodeada por parênteses. Por exemplo, (age<20) ou (flavor:chocolate). O número máximo de condições que você pode definir é de 50.

Você pode, opcionalmente, incluir o parâmetro relevancy e configurá-lo como true para retornar o valor de relevância do conjunto de documentos que atendem à condição especificada. Quando true, os resultados são classificados por relevância. Quando false, os resultados são classificados pelo maior número de matching_results.

Exemplo

A solicitação a seguir procura documentos que mencionam o termo engine, e os agrupa por ano de fabricação de automóveis. Os documentos são sorteados em 3 grupos, um grupo de relatórios de incidentes de trânsito envolvendo carros que foram fabricados antes de 2000, um grupo para carros fabricados em 2000, e um grupo para carros fabricados após 2000.

{
    "query":"engine",
    "aggregation": "group_by(condition:[(YEARTXT<2000),(YEARTXT=2000),(YEARTXT>2000)],relevancy:true)"
}

Os resultados podem parecer com isso:

{
  "type": "group_by",
  "results": [
    {
    "key": "YEARTXT<2000",
      "matching_results": 2034,
      "relevancy": 1.0,
      "total_matching_documents": 2034,
      "estimated_matching_results": 2034
    },
    {
      "key": "YEARTXT=2000",
      "matching_results": 1738,
      "relevancy": 1.0,
      "total_matching_documents": 1738,
      "estimated_matching_results": 1738
    },
    {
      "key": "YEARTXT>2000",
      "matching_results": 32708,
      "relevancy": 1.0,
      "total_matching_documents": 32708,
      "estimated_matching_results": 32708
    }
  ]
}

Sintaxe

histogram({field},{interval})

Usa valores de campo de um campo numérico único para descrever a categoria. O campo que é usado para criar o histograma deve ter um tipo de dado de número, como integer, float, double ou date.

Não há suporte para tipos não numéricos, como string. Por exemplo, "price": 1.30 é um valor numérico que funciona, e "price": "1.30" é uma cadeia de caracteres, portanto, não funciona.

Use o argumento interval para definir o tamanho das seções em que os resultados serão divididos. Os valores de intervalo devem ser inteiros, números não negativos. Escolha um valor que faça sentido para segmentar os valores típicos do campo.

Os histogramas podem processar valores decimais que são especificados em um campo, mas o intervalo deve ser um número inteiro.

Você pode, opcionalmente, incluir um nome personalizado incluindo um parâmetro name.

Exemplo

Por exemplo, se seu conjunto de dados incluir o preço de vários itens, como: “price”: 1.30, “price”: 1.99, e “price”: 2.99, você poderá usar intervalos de 1, para que veja tudo o que está agrupado no intervalo 1 - 2, e 2 e 3. Você não quer usar um intervalo de 100 porque então todos os dados acabam no mesmo segmento.

histogram(product_price,interval:1)

Sintaxe

max(field)

Exemplo

Quando o tipo de agregação max é aplicado a um conjunto de documentos em que o campo price contém os valores que são mostrados na Tabela 2, o resultado é 450.

max(price)=450

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

Sintaxe

min(field)

Exemplo

Quando o tipo de agregação min é aplicado a um conjunto de documentos em que o campo price contém os valores que são mostrados na Tabela 3, o resultado é 200.

min(price)=200

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

Sintaxe

pair(first:{aggregation},second:{aggregation})

Os valores de primeiro e segundo {aggregation} devem ser um dos seguintes tipos de agregação:

• term
• group_by
• histogram
• timeslice

O parâmetro relevancy da agregação term ou group_by é ignorado. O tipo de agregação pair calcula valores de relevância utilizando combinações de conjuntos de documentos a partir dos resultados das duas agregações.

Apenas uma agregação de par pode ser usada por solicitação de consulta, e não pode ser combinada com quaisquer outras agregações.

Exemplo

Por exemplo, você pode especificar term(model_name) como a primeira agregação e term(component_name) como a segunda. Cada uma das agregações retorna os seguintes valores como chaves de conjuntos de documentos agregados:

• termo (model_name): Accord, CR-V
• termo (component_name): motor, freio, radiador

Os valores de relevância calculados de combinações de cada um dos conjuntos de documentos podem parecer assim:

• Mecanismo de accord x
• Acordo x freio
• Acordo x radiador
• Motor CR-V x
• CR-V x freio
• CR-V x radiador

A resposta define uma matriz bidimensional de resultados de agregação, que pode ser representada em uma tabela.

Cada matriz de colunas e linhas da tabela é classificada na mesma ordem dos resultados da primeira e da segunda agregações. Por exemplo, se você especificar a agregação term como o primeiro argumento, as arrays de coluna resultantes são classificadas por frequência de termos. Se você usar a agregação timeslice como o segundo argumento, as matrizes de linha são classificadas por data ou hora.

Sintaxe

sum(field)

Exemplo

Quando o tipo de agregação sum é aplicado a um conjunto de documentos em que o campo price contém os valores que são mostrados na Tabela 6, o resultado é 975.

sum(price)=975

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

Sintaxe

term(field:{field_name})

Opcionalmente, você pode especificar os seguintes parâmetros:

• count: Especifica o número máximo de termos a serem retornados.

• name: Você pode, opcionalmente, incluir um nome personalizado. Não retornou se informações de relevância estão incluídas no pedido.

• relevancy: Valor booleano que indica se deve incluir informações de relevância no resultado. Você pode usar relevância para obter uma pontuação que indica o nível de relevância entre o termo e palavras-chave na consulta. Esse parâmetro é false por padrão. Se configurado como true, os campos a seguir são retornados também:

  • total_matching_documents: Número de documentos na coleção em que o termo é mencionado no campo especificado.
  • estimated_matching_results: Número de documentos que são estimados para ter o termo no campo especificado no conjunto de documentos retornados pela consulta.

Exemplo

O exemplo a seguir retorna o texto das entidades reconhecidas no documento, e especifica para retornar um máximo de 10 termos.

Por exemplo:

term(enriched_text.entities.text,count:10)

Quando relevancy é configurado como true, uma pontuação de relevância é mostrada nos resultados. A relevância mede o nível de exclusividade da contagem de frequência em comparação com outros documentos que correspondam à sua consulta. Se a relevância mostrar 2.0, significa que o número de vezes que os dois pontos de dados se cruzam é 2 vezes maior do que o esperado.

Para obter mais exemplos, consulte Grouping documents e Combinando tipos de agregação.

Sintaxe

A sintaxe é timeslice({field},{interval},{time_zone}).

• O campo que você especificar deve ter um tipo de dado date. Para obter mais informações sobre o campo date, consulte Como as datas são tratadas.
• Valid interval values are 1second or {n}seconds, 1minute or {n}minutes, 1hour or {n}hours, 1day or {n}days, 1week or {n}weeks, 1month or {n}months, and 1year or {n}years where {n} is a number.
• Você pode, opcionalmente, incluir um nome personalizado incluindo um parâmetro name.

Exemplo

O exemplo a seguir mostra o número de correspondências para cada valor de dia.

timeslice(field:DATEA,interval:1day)

Os resultados são os seguintes.

"aggregations": [
  {
    "type": "timeslice",
    "field": "DATEA",
    "interval": "1d",
    "results": [
        {
    "key": 1262304000000,
    "key_as_string": "2010-01-01T00:00:00.000Z",
    "matching_results": 5
        },
        {
    "key": 1262390400000,
    "key_as_string": "2010-01-02T00:00:00.000Z",
    "matching_results": 18
        },
        {
    "key": 1262476800000,
    "key_as_string": "2010-01-03T00:00:00.000Z",
    "matching_results": 38
        },
        {
    "key": 1262563200000,
    "key_as_string": "2010-01-04T00:00:00.000Z",
    "matching_results": 66
        }

Sintaxe

{aggregation}.top_hits({n})

Exemplo

O exemplo a seguir retorna o hit superior para o termo halt por cidade.

{
  "query":"halt",
  "aggregation": "term(CITY).top_hits(1)"
}

A resposta contém os principais resultados de consulta para o termo halt agrupados por cidades mencionadas em documentos onde o termo é mais mencionado. Dez resultados são retornados por padrão. Para cada uma das 10 cidades, o documento com a pontuação superior é retornado como o objeto hit. O conteúdo para cada hit na matriz hits corresponde ao conteúdo em cada result na matriz results. Só que a ordem dos resultados é diferente.

"aggregations": [
  {
    "type": "term",
    "field": "CITY",
    "results": [
      {
        "key": "LOS ALTOS",
        "matching_results": 3,
        "aggregations": [
          {
            "type": "top_hits",
            "size": 1,
            "hits": {
              "matching_results": 3,
              "hits": [
                {
                  "document_id": "2bed19a9069442fd82542827ebe260d5_7015",
                  ...
                }
              ]
            }
          }
        ]
      },
      {
        "key": "ANDOVER",
        "matching_results": 2,
        "aggregations": [
          {
            "type": "top_hits",
            "size": 1,
            "hits": {
              "matching_results": 2,
              "hits": [
                {
                  "document_id": "2bed19a9069442fd82542827ebe260d5_18329",
                  ...
                }
              ]
            }
          }
        ]
      },
      ...
      {
        "key":"ACTON",
        "maatching_results": 1,
        "aggregations": []
      }
      ...

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

Sytnax

trend(facet:{aggregation},time_segments:{aggregation})

A primeira (facet) agregação deve ser um dos seguintes tipos de agregações:

• term
• group_by

O parâmetro relevancy da agregação term ou group_by é ignorado.

A agregação de segundo (time_segments) deve ser uma agregação do tipo timeslice.

Você pode, alternativamente, incluir os seguintes parâmetros:

• show_estimated_matching_results:true: Indica se deve incluir as informações estimated_matching_results no resultado. Este campo contém o número de documentos que são estimados para ter o termo no campo especificado ou atendem as condições na agregação especificada para o intervalo de tempo especificado no conjunto de documentos retornados pela consulta.
• show_total_matching_documents:true: Indica se deve incluir as informações total_matching_documents no resultado. Este campo contém o número de documentos na coleção em que o termo é mencionado no campo especificado ou a condição é atendida.

Apenas uma agregação de tendência pode ser usada por solicitação de consulta, e não pode ser combinada com quaisquer outras agregações.

Exemplo

O exemplo a seguir calcula o indicador de tendência ou índice de tendência usando combinações de resultados a partir das seguintes agregações:

• termo (sabor): baunilha, chocolate, hortelã
• timeslice (data, 1month): Jan 2020, Feb 2020, Mar 2020, Apr 2020, maio 2020, Jun 2020

trend( facet: aggregation(<parameter>...), time_segments: timeslice(<parameter>...)),
show_estimated_matching_results: <true_or_false>, show_total_matching_documents: <true_or_false> )

A matriz resultante pode ser representada em uma tabela.

Na resposta de amostra a seguir, as informações principais são o valor trend_indicator. O indicador de tendência mede a relação de aumento da frequência de um determinado valor de faceta para um determinado intervalo de tempo em comparação com a frequência média esperada. A frequência média excepcionada é calculada com base nas alterações nas frequências de intervalo de tempo passado do valor de faceta determinado, utilizando uma média aritmética ponderada.

Se o valor residual padronizado for menor que -2, a frequência observada será menor que a frequência esperada. Se for maior que 2, a frequência observada é maior do que a frequência esperada. Se o residual padronizado for maior ou menor do que a frequência esperada por 3 ou mais, então algo incomum está acontecendo e sugere que pode haver uma anomalia que vale a pena investigar.

Por exemplo, o número esperado de submissões de feedback para o sabor vanilla em maio é calculado a partir do número de submissões de feedback que foram recebidas anteriormente (de Jan a Apr). O resultado é 5.341. O número real de submissões de feedback em maio é 10. Os resultados indicam que o sabor de baunilha conseguiu cerca de duas vezes o número de submissões de feedback como esperado. O valor residual padronizado é 2.016, que é maior do que o esperado, mas não excepcionalmente assim.

{
"aggregations": [
  {
    "type": "trend",
    "facet": "term(flavor),",
    "time_segments": "timeslice(date, 1month)",
    "show_estimated_matching_results": true,
    "show_total_matching_documents": true,
    "results": [
      {
        "aggregations": [
          {
            "type": "term",
            "field": "flavor",
            "results": [
              {
                "key": "vanilla",
                "matching_results": 36,
                "aggregations": [
                  {
                    "type": "timeslice",
                    "field": "date",
                    "results": [
                      {
                        "key": 1577836800000,
                        "key_as_string": "2020-01-01T00:00:00.000Z",
                        "matching_results": 4,
                        "trend_indicator": 0.0,
                        "total_matching_documents": 7,
                        "estimated_matching_results": 0.0
                      },
                      {
                        "key": 1588291200000,
                        "key_as_string": "2020-05-01T00:00:00.000Z",
                        "matching_results": 10,
                        "trend_indicator": 2.016106745,
                        "total_matching_documents": 12,
                        "estimated_matching_results": 5.340760209
                      },
                      {
                        "key": 1590969600000,
                        "key_as_string": "2020-06-01T00:00:00.000Z",
                        "matching_results": 5,
                        "trend_indicator": -0.763212711,
                        "total_matching_documents": 11,
                        "estimated_matching_results": 7.022515985
                      }
                    ]
                  }
                ]
              },
              {
                "key": "chocolate",
                "matching_results": 10,
                "aggregations": [...]
              },
              {
                "key": "mint",
                "matching_results": 25,
                "aggregations": [...]
...
}  

Sintaxe

topic(facet:{aggregation},time_segments:{aggregation})

A primeira (facet) agregação deve ser um dos seguintes tipos de agregações:

• term
• group_by

O parâmetro relevancy da agregação term ou group_by é ignorado.

A agregação de segundo (time_segments) deve ser uma agregação do tipo timeslice.

Você pode, alternativamente, incluir os seguintes parâmetros:

• show_estimated_matching_results:true: Indica se deve incluir as informações estimated_matching_results no resultado. Este campo contém o número de documentos que são estimados para ter o termo no campo especificado ou atendem as condições na agregação especificada para o intervalo de tempo especificado no conjunto de documentos retornados pela consulta.
• show_total_matching_documents:true: Indica se deve incluir as informações total_matching_documents no resultado. Este campo contém o número de documentos na coleção em que o termo é mencionado no campo especificado ou a condição é atendida.

Apenas uma agregação de tópico pode ser usada por solicitação de consulta, e não pode ser combinada com quaisquer outras agregações.

Exemplo

{
    "query: like",
    "aggregation": "topic( facet: term(flavor), time_segments: timeslice(date, 1month), show_estimated_matching_results: true, show_total_matching_documents: true )"
}

Com o mesmo conjunto de dados e agregação como é utilizado no exemplo de agregação de termo, os resultados podem parecer a seguir.

Percebesse que os valores topic_indicator são diferentes dos valores trend_indicator que são retornados pela agregação trend. Enquanto ambos são calculados a partir das freqüências reais e esperadas, eles diferem porque suas frequências esperadas são computadas de forma diferente. Na agregação trend, a frequência esperada das submissões de feedback para sorvetes com sabor de baunilha em maio é computada a partir do número de submissões de feedback que foram recebidas para baunilha anteriormente (de Jan a Apr) e o número total de envios de feedback recebidos para todos os sabores em maio. No entanto, na agregação topic, a frequência esperada de submissões de feedback para sorvetes com sabor de baunilha em maio é calculada a partir do número de submissões de feedback que foram recebidas para baunilha e o número total de submissões de feedback recebidas para todos os sabores em maio. Neste exemplo, o resultado de frequência esperado é 12.169, a frequência real é 10 e o topic_indicator é -0.621777032.

{
"aggregations": [
  {
    "type": "topic",
    "facet": "term(flavor)",
    "time_segments": "timeslice(date, 1month)",
    "show_estimated_matching_results": true,
    "show_total_matching_documents": true,
    "results": [
      {
        "aggregations": [
          {
            "type": "term",
            "field": "flavor",
            "results": [
              {
                "key": "vanilla",
                "matching_results": 36,
                "aggregations": [
                  {
                    "type": "timeslice",
                    "field": "date",
                    "results": [
                      {
                        "key": 1577836800000,
                        "key_as_string": "2020-01-01T00:00:00.000Z",
                        "matching_results": 4,
                        "topic_indicator": -0.027972712,
                        "total_matching_documents": 7,
                        "estimated_matching_results": 4.056338028
                      },
                      {
                        "key": 1588291200000,
                        "key_as_string": "2020-05-01T00:00:00.000Z",
                        "matching_results": 10,
                        "topic_indicator": -0.621777032,
                        "total_matching_documents": 12,
                        "estimated_matching_results": 12.16901408
                      },
                      {
                        "key": 1590969600000,
                        "key_as_string": "2020-06-01T00:00:00.000Z",
                        "matching_results": 5,
                        "topic_indicator": -0.787665504,
                        "total_matching_documents": 11,
                        "estimated_matching_results": 7.098591549
                      }
                    ]
                  }
                ]
              },
              {
                "key": "chocolate",
                ...
              },
              {
                "key": "mint",
                ...
              }
}

Sintaxe

unique_count(field)

Exemplo

A agregação a seguir solicita o número de tipos de enriquecimento exclusivo que são reconhecidos na consulta.

unique_count(enriched_text.keyword.type)

O resultado indica que há 17 resultados correspondentes. Nesses 17 documentos, são mencionados 14 tipos de entidade.

{
  "matching_results": 17,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "unique_count",
      "field": "enriched_text.entities.type",
      "value": 14.0
    }
  ],
  "results": []
}

Esse tipo de agregação executa uma operação de terminal. Quando combinado com outras agregações, a saída não é usada como entrada para a próxima agregação. A saída é devolvida em um grupo discreto.

No exemplo a seguir, o parâmetro de agregação solicita os resultados para mostrar as primeiras 45 entidades mais freqüentemente mencionadas. Por entidade, ele indica quantos documentos mencionam o termo e quantas vezes no total que o termo ocorre.

term(enriched_text.entities.text,count:45).unique_count(enriched_text.entities.type)

Os resultados incluem várias agregações como o grupo a seguir para o termo PostgreSQL. A totalização indica que o termo aparece em 4 documentos e é mencionado 12 vezes.

{
  "key": "PostgreSQL",
  "matching_results": 4,
  "aggregations": [
    {
      "type": "unique_count",
      "field": "enriched_text.entities.type",
      "value": 12.0
    }
  ]
}