IBM Cloud Docs
Agrégations de requêtes

Agrégations de requêtes

Utilisez des agrégations pour regrouper, analyser ou comparer les résultats renvoyés par une demande de requête.

Une agrégation est définie par un paramètre aggregation que vous pouvez spécifier dans l'API de requête. L'entrée du paramètre d'agrégation est le jeu de documents renvoyé par le paramètre query, filter ou natural_language_query qui est spécifié en tant que paramètre distinct dans la même demande de requête. Sinon, l'agrégation est appliquée à tous les documents du projet.

Vous pouvez utiliser une agrégation pour effectuer des calculs à partir des valeurs de l'ensemble de documents de résultats. Par exemple, pour obtenir des informations sur le montant le plus élevé en dollars dans la zone order.total des documents renvoyés en tant que résultats de requête, utilisez max(order.total) comme valeur du paramètre aggregation.

Exemple de structure de requête d'agrégation indiquant max comme type d'agrégation et order.total comme regroupement de
de
de structure de requête d'agrégation*

Le paramètre d'agrégation renvoie des données sur la zone dont la valeur est la plus élevée.

"aggregations": [
  {
    "type": "max",
    "field": "order.total",
    "value": 100668.00
  }
]

Regroupement de documents

En plus d'effectuer des calculs, vous pouvez utiliser une agrégation pour regrouper dans l'ensemble de résultats des documents qui correspondent à certaines valeurs, de sorte que vous pouvez les compter ou les analyser plus en détail. Par exemple, vous pouvez utiliser une agrégation pour rechercher dans un ensemble de rapports d'incidents de trafic des documents qui mentionnent le terme brake. Et à partir des documents renvoyés, trouvez les rapports des États américains avec les mentions les plus pertinentes du terme.

Dans l'exemple de demande suivant, le paramètre count qui ne renvoie que 3 résultats d'agrégation est inclus pour faciliter le suivi de l'exemple.

{
    "query":"brake",
    "aggregation": "term(field:STATE,count:3,relevancy:true)"
}

La sortie du paramètre d'agrégation est renvoyée dans un objet aggregations qui est affiché avant l'objet results, qui contient les résultats de la requête. Un maximum de 50 000 valeurs peuvent être renvoyées dans l'objet aggregations pour une requête unique.

L'objet aggregations résultant contient des informations récapitulatives sur les résultats de la requête. Dans cet exemple, par exemple, il montre que les rapports d'incident de trafic provenant de New York, de Californie et de Floride contiennent les mentions les plus pertinentes du terme brake.

{
  "matching_results": 9064,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "term",
      "field": "STATE",
      "results": [
        {
          "key": "NY",
          "matching_results": 693,
          "relevancy": 1.1649531567631084,
          "total_matching_documents": 2156,
          "estimated_matching_results": 542
        },
        {
          "key": "CA",
          "matching_results": 1210,
          "relevancy": 1.1170819184294765,
          "total_matching_documents": 4017,
          "estimated_matching_results": 1011
        },
        {
          "key": "FL",
          "matching_results": 511,
          "relevancy": 0.828014956418841,
          "total_matching_documents": 2199,
          "estimated_matching_results": 553
        }
      ]
    }
  ],
  "results": []

Combinaison de types d'agrégation

Il existe différents types d'agrégations que vous pouvez utiliser pour analyser ou regrouper les résultats de la requête. Vous pouvez également combiner plusieurs agrégations dans une demande pour effectuer une analyse plus ciblée.

L'exemple suivant illustre une demande composée de deux opérateurs de terme. La première agrégation de termes regroupe les documents d'entrée par valeurs US STATE et sélectionne 3 groupes. Le deuxième terme d'agrégation s'applique à chacun de ces trois groupes et les regroupe en fonction de la valeur de CITY. Seuls 2 de ces sous-groupes CITY sont renvoyés par groupe STATE.

Le paramètre de pertinence est exclu pour faciliter la lecture des résultats.

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

La réponse contient des informations sur la ville de chaque état.

{
  "matching_results": 9064,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "term",
      "field": "STATE",
      "count": 3,
      "results": [
        {
          "key": "CA",
          "matching_results": 1210,
          "aggregations": [
            {
              "type": "term",
              "field": "CITY",
              "count": 2,
              "results": [
                {
                  "key": "LOS ANGELES",
                  "matching_results": 77
                },
                {
                  "key": "SAN DIEGO",
                  "matching_results": 66
                }
              ]
            }
          ]
        },
        {
          "key": "NY",
          "matching_results": 693,
          "aggregations": [
            {
              "type": "term",
              "field": "CITY",
              "count": 2,
              "results": [
                {
                  "key": "BROOKLYN",
                  "matching_results": 35
                },
                {
                  "key": "NEW YORK",
                  "matching_results": 21
                }
              ]
            }
          ]
        },
        {
          "key": "FL",
          "matching_results": 511,
          "aggregations": [
            {
              "type": "term",
              "field": "CITY",
              "count": 2,
              "results": [
                {
                  "key": "JACKSONVILLE",
                  "matching_results": 33
                },
                {
                  "key": "TAMPA",
                  "matching_results": 29
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "results": []

L'ordre dans lequel vous spécifiez les agrégations est important. Par exemple, si vous inversez l'ordre des agrégations de termes de l'exemple précédent, vous obtenez des résultats différents.

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

Le nouvel ordre produit des résultats qui font surface à Chicago, une ville qui n'était pas incluse dans l'ensemble de résultats précédent. Lorsque la demande commence par le regroupement par état, l'Illinois, qui ne possède qu'une seule ville avec un nombre élevé de rapports d'incident de trafic, n'est pas inclus dans les résultats. New York et la Floride, qui ont toutes deux plus d'une ville avec de nombreux rapports d'incident, produisent un plus grand nombre de matchs à l'échelle de l'État et, par conséquent, ont été renvoyés. Lorsque vous effectuez un regroupement par ville en premier, les résultats changent.

{
  "matching_results": 9064,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "term",
      "field": "CITY",
      "count": 4,
      "results": [
        {
          "key": "LOS ANGELES",
          "matching_results": 77,
          "aggregations": [
            {
              "type": "term",
              "field": "STATE",
              "count": 1,
              "results": [
                {
                  "key": "CA",
                  "matching_results": 77
                }
              ]
            }
          ]
        },
        {
          "key": "SAN DIEGO",
          "matching_results": 66,
          "aggregations": [
            {
              "type": "term",
              "field": "STATE",
              "count": 1,
              "results": [
                {
                  "key": "CA",
                  "matching_results": 66
                }
              ]
            }
          ]
        },
        {
          "key": "CHICAGO",
          "matching_results": 59,
          "aggregations": [
            {
              "type": "term",
              "field": "STATE",
              "count": 1,
              "results": [
                {
                  "key": "IL",
                  "matching_results": 59
                }
              ]
            }
          ]
        }
      ]
    }
    ],
    "results": []

Utilisation d'agrégations pour explorer les enrichissements

L'agrégation term() est particulièrement utile pour analyser les résultats afin de déterminer le nombre d'enrichissements reconnus dans les documents. Par exemple, pour compter le nombre de fois où chaque type d'entité est reconnu dans les documents filtrés, vous pouvez soumettre les paramètres de requête suivants:

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

La requête sélectionne d'abord les documents qui possèdent au moins une entité de type Location et dont le texte est Gilroy. Cette action renvoie 3 documents. A partir des documents renvoyés, l'agrégation compte ensuite le nombre de documents dans lesquels chaque type d'entité apparaît.

{
  "matching_results": 3,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "term",
      "field": "enriched_text.entities.type",
      "results": [
        {
          "key": "Location",
          "matching_results": 3
        },
        {
          "key": "Person",
          "matching_results": 3
        },
        {
          "key": "Company",
          "matching_results": 2
        },
        {
          "key": "GeographicFeature",
          "matching_results": 2
        },
        {
          "key": "Organization",
          "matching_results": 2
        },
        {
          "key": "Quantity",
          "matching_results": 2
        },
        {
          "key": "Facility",
          "matching_results": 1
        },
        {
          "key": "PrintMedia",
          "matching_results": 1
        }
      ]
    }
  ]
}

Les 3 documents correspondants ont tous un type d'entité Location et Person ("matching_results": 3). Toutefois, seuls 2 des documents correspondants ont un type d'entité Company.

Par défaut, les 10 premières correspondances sont renvoyées, triées par pertinence. Vous pouvez modifier le nombre de résultats en ajoutant le paramètre count à l'agrégation.

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

Ajouter un filtre

Utilisez filter() dans la clause d'agrégation pour filtrer les résultats. Par exemple, vous pouvez spécifier le même filtre que celui qui a été soumis séparément dans l'exemple précédent directement dans la clause aggregation.

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

Dans ce cas, l'agrégation filter().term() trouve le même résultat que l'exemple précédent avec les clauses filter et aggregation distinctes. Toutefois, les résultats sont classés différemment lorsque la clause filter est utilisée. Vous pouvez optimiser cette différence en utilisant la clause filter() dans la clause aggregation pour filtrer les résultats d'une séquence d'expressions, comme illustré dans l'exemple suivant.

Démarrer avec des objets imbriqués

Dans les exemples précédents, la valeur "matching_counts" représente le nombre de documents correspondant au filtre et à l'agrégation. Vous souhaiterez peut-être compter le nombre d'objets imbriqués présents dans la réponse à la requête. L'agrégation nested() vous permet de modifier l'ensemble de documents utilisé comme entrée pour d'autres termes d'agrégation.

Par exemple, dans la requête suivante, le segment nested() sélectionne tous les objets imbriqués enriched_text.entities comme entrée utilisée par les segments filter() et term().

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

La requête génère un objet aggregations qui se présente comme suit:

{
  "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
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Le segment nested() de la requête a trouvé des objets imbriqués en 1993 enriched_text.entities. Le filtre a été appliqué à ces objets et a trouvé 645 enriched_text.entities de type Organization.

Opérations de terminal

Pour la plupart des types d'agrégation, lorsque vous construisez une requête avec plusieurs opérations d'agrégation, la première opération est appliquée aux documents. Ensuite, la sortie de cette opération est utilisée comme entrée pour l'opération suivante. Toutefois, un sous-ensemble des types d'agrégation sont des opérations de terminal. La sortie d'une opération de terminal n'est pas utilisée comme entrée pour l'agrégation suivante. A la place, la sortie est renvoyée dans un groupe discret.

Pour un exemple de demande qui combine des types d'agrégation et inclut une agrégation qui effectue une opération de terminal, voir le deuxième exemple pour le type d'agrégation average.

types d'agrégation

Les types d'agrégations suivants sont pris en charge :

Pour les types de projet Document Retrieval, lorsque vous n'incluez pas de paramètre d'agrégation dans une demande de requête, une demande d'agrégation par défaut est appliquée. Pour plus d'informations, voir Agrégation de projets d'extraction de documents.

Pour plus d'informations sur la soumission d'une requête, voir la référence d'API Discovery.

moyenne

Renvoie la moyenne des valeurs de la zone spécifiée dans tous les documents correspondants.

Syntaxe

average(field)

Exemple

Exemples de prix de produits
Produit Prix
Série I 200
Série J 450
Série X 325

Lorsque le type d'agrégation average est appliqué à un ensemble de documents dans lequel la zone price contient les valeurs affichées dans le tableau 1, le résultat est 325.

average(price)=325

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

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

Pour chaque état renvoyé par la première opération d'agrégation term, la réponse indique la vitesse moyenne du véhicule spécifiée dans les rapports d'incident. Notez que la deuxième agrégation term utilise la sortie de la première agrégation term, et non l'agrégation average, comme entrée.

{
  "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
                }
              ]
            }
          ]
        }

filter

Un modificateur qui restreint l'ensemble des documents de la requête d'agrégation qu'il précède.

Syntaxe

filter(field)

Exemple

L'exemple suivant filtre le jeu de documents correspondant pour inclure uniquement les documents qui mentionnent IBM.

filter(enriched_text.entities.text:IBM)

Lorsqu'il est combiné à d'autres agrégations, filtre les documents correspondants définis pour inclure uniquement les documents qui remplissent la condition que vous spécifiez.

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

La réponse à la requête indique les villes où des incidents impliquant les freins et la vitesse du véhicule est supérieure à 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
                    }
                  ]
                }
              ]
            }

group_by

Sépare les résultats en groupes que vous définissez.

Syntaxe

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

Chaque condition doit être spécifiée en tant qu'expression de langage de requête de reconnaissance valide entre parenthèses. Par exemple, (age<20) ou (flavor:chocolate). Le nombre maximal de conditions que vous pouvez définir est de 50.

Vous pouvez éventuellement inclure le paramètre relevancy et le définir sur true pour renvoyer la valeur de pertinence de l'ensemble de documents qui remplissent la condition spécifiée. Lorsque la valeur est true, les résultats sont triés par pertinence. Lorsque la valeur est false, les résultats sont triés en fonction du nombre le plus élevé de matching_results.

Exemple

La demande suivante recherche les documents qui mentionnent le terme engine et les regroupe par année de fabrication automobile. Les documents sont classés en trois groupes: un groupe de rapports d'incidents de la circulation impliquant des voitures fabriquées avant 2000, un groupe pour les voitures fabriquées en 2000 et un groupe pour les voitures fabriquées après 2000.

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

Les résultats peuvent ressembler à ce qui suit:

{
  "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
    }
  ]
}

histogramme

Permet de créer des segments d'intervalle numériques pour classer des documents.

Syntaxe

histogram({field},{interval})

Utilisez les valeurs d'une zone numérique unique pour décrire la catégorie. La zone utilisée pour créer l'histogramme doit avoir un type de données numérique, tel que integer, float, double ou date.

Les types non numériques tels que string ne sont pas pris en charge. Par exemple, "price": 1.30 est une valeur numérique qui fonctionne, et "price": "1.30" est une chaîne de caractères, qui ne fonctionne donc pas.

Utilisez l'argument interval pour définir la taille des sections dans lesquelles les résultats doivent être divisés. Les valeurs d'intervalle doivent être des nombres entiers et non négatifs. Choisissez une valeur qui a un sens pour segmenter les valeurs typiques de la zone.

Les histogrammes peuvent traiter les valeurs décimales spécifiées dans un champ, mais l'intervalle doit être un nombre entier.

Vous pouvez éventuellement inclure un nom personnalisé en incluant un paramètre name.

Exemple

Par exemple, si votre ensemble de données comprend le prix de plusieurs articles, comme : “price”: 1.30, “price”: 1.99, et “price”: 2.99, vous pouvez utiliser des intervalles de 1, afin de voir tout ce qui est regroupé dans l'intervalle 1 - 2, et 2 et 3. Vous ne souhaitez pas utiliser un intervalle de 100 car toutes les données se trouvent alors dans le même segment.

histogram(product_price,interval:1)

max

Renvoie la valeur maximale de la zone spécifiée dans tous les documents correspondants.

Syntaxe

max(field)

Exemple

Exemples de prix de produits
Produit Prix
Série I 200
Série J 450
Série X 325

Lorsque le type d'agrégation max est appliqué à un ensemble de documents dans lequel la zone price contient les valeurs affichées dans le tableau 2, le résultat est 450.

max(price)=450

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

min

Renvoie la valeur minimale de la zone spécifiée dans tous les documents correspondants.

Syntaxe

min(field)

Exemple

Exemples de prix de produits
Produit Prix
Série I 200
Série J 450
Série X 325

Lorsque le type d'agrégation min est appliqué à un ensemble de documents dans lequel la zone price contient les valeurs affichées dans le tableau 3, le résultat est 200.

min(price)=200

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

imbriqué

L'application de nested avant une requête d'agrégation limite l'agrégation à la zone de résultats spécifiée.

Par exemple, nested(enriched_text.entities) signifie que seules les composantes enriched_text.entities d'un résultat sont utilisées pour l'agrégation.

L'exemple suivant vérifie le nombre de mentions renvoyées par type de modèle.

nested(enriched_text.entities).term(enriched_text.entities.model_name)

Le résultat montre qu'il y a un total de 50 entités reconnues et qu'elles sont toutes de type NLU.

"aggregations": [
  {
    "type": "nested",
    "path": "enriched_text.entities",
    "matching_results": 50,
    "aggregations": [
      {
        "type": "term",
        "field": "enriched_text.entities.model_name",
        "results": [
          {
            "key": "natural_language_understanding",
            "matching_results": 50
          }
        ]
      }
    ]
  }
]

Pour un autre exemple, voir Démarrage avec des objets imbriqués.

paire

Analyse les relations entre deux zones.

Syntaxe

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

Les première et seconde valeurs {aggregation} doivent correspondre à l'un des types d'agrégation suivants:

  • term
  • group_by
  • histogram
  • timeslice

Le paramètre relevancy de l'agrégation term ou group_by est ignoré. Le type d'agrégation pair calcule les valeurs de pertinence en utilisant des combinaisons de jeux de documents à partir des résultats des deux agrégations.

Une seule agrégation de paires peut être utilisée par demande de requête et ne peut pas être combinée avec d'autres agrégations.

Exemple

Par exemple, vous pouvez spécifier term(model_name) comme première agrégation et term(component_name) comme deuxième agrégation. Chacune des agrégations renvoie les valeurs suivantes en tant que clés de jeux de documents agrégés:

  • term (nom_modèle): Accord, CR-V
  • term (nom_composant): moteur, frein, radiateur

Les valeurs de pertinence calculées des combinaisons de chacun des jeux de documents peuvent se présenter comme suit:

  • Moteur Accord x
  • Accord x frein
  • Accord x radiateur
  • Moteur CR-V x
  • Frein CR-V x
  • Radiateur CR-V x

La réponse définit un tableau à deux dimensions de résultats d'agrégation, qui peuvent être représentés dans un tableau.

Exemple d'agrégation de paires
Ce tableau comporte des en-têtes de lignes et de colonnes. Les en-têtes de ligne identifient les modèles de voiture. Les en-têtes de colonne identifient les composants de voiture. Chaque cellule calcule un score de pertinence en multipliant la valeur de pertinence du modèle de voiture (ligne) par la valeur de pertinence du composant de voiture (en-tête).
Modèle de voiture Composant: engine Composant: frein Composant: radiateur
Accord Moteur Accord x Accord x frein Accord x radiateur
CR-V Moteur CR-V x Frein CR-V x Radiateur CR-V x

Chaque tableau de colonnes et de lignes de la table est trié dans le même ordre des résultats des première et deuxième agrégations. Par exemple, si vous spécifiez l'agrégation term comme premier argument, les tableaux de colonnes résultants sont triés par fréquence de termes. Si vous utilisez l'agrégation timeslice comme second argument, les tableaux de lignes sont triés par date ou heure.

sum

Ajoute les valeurs du champ spécifié à tous les documents correspondants.

Syntaxe

sum(field)

Exemple

Exemples de prix de produits
Produit Prix
Série I 200
Série J 450
Série X 325

Lorsque le type d'agrégation sum est appliqué à un ensemble de documents dans lequel la zone price contient les valeurs affichées dans le tableau 6, le résultat est 975.

sum(price)=975

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

terme

Indique la fréquence d'un terme ou d'un ensemble de termes dans un ensemble de documents interrogés.

Syntaxe

term(field:{field_name})

Vous pouvez éventuellement spécifier les paramètres suivants :

  • count: Spécifie le nombre maximum de termes à renvoyer.

  • name: vous pouvez éventuellement inclure un nom personnalisé. Non renvoyé si des informations de pertinence sont incluses dans la demande.

  • relevancy: valeur booléenne qui indique si les informations de pertinence doivent être incluses dans le résultat. Vous pouvez utiliser la pertinence pour obtenir un score qui indique le niveau de pertinence entre le terme et les mots clés dans la requête. Ce paramètre est false par défaut. Si la valeur est true, les zones suivantes sont également renvoyées:

    • total_matching_documents: nombre de documents dans la collection où le terme est mentionné dans la zone spécifiée.
    • estimated_matching_results: nombre de documents dont le terme est estimé dans la zone spécifiée de l'ensemble de documents renvoyés par la requête.

Exemple

L'exemple suivant renvoie le texte des entités reconnues dans le document et indique de renvoyer un maximum de 10 termes.

Par exemple :

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

Lorsque relevancy est défini sur true, un score de pertinence est affiché dans les résultats. La pertinence mesure le niveau d'unicité du nombre de fréquences par rapport aux autres documents qui correspondent à votre requête. Si la pertinence indique 2.0, cela signifie que le nombre de fois où les deux points de données se croisent est 2 fois plus grand que prévu.

Pour plus d'exemples, voir Groupement de documents et Combinaison de types d'agrégation.

intervalle de temps

Histogramme spécialisé qui utilise des dates pour créer des segments d'intervalle.

Syntaxe

La syntaxe est la suivante : timeslice({field},{interval},{time_zone}).

  • La zone que vous spécifiez doit avoir un type de données date. Pour plus d'informations sur la zone de date, voir Comment les dates sont traitées.
  • Les valeurs d'intervalle valides sont 1second ou {n}seconds, 1minute ou {n}minutes, 1hour ou {n}hours, 1day ou {n}days, 1week ou {n}weeks, 1month ou {n}months, et 1year ou {n}years où {n} est un nombre.
  • Vous pouvez éventuellement inclure un nom personnalisé en incluant un paramètre name.

Exemple

L'exemple suivant montre le nombre de correspondances pour chaque valeur de jour.

timeslice(field:DATEA,interval:1day)

Les résultats sont les suivants.

"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
        }

top_hits

Renvoie les documents classés en fonction du score de la requête ou de l'enrichissement. Peut être utilisé avec tout paramètre de requête ou agrégation.

Syntaxe

{aggregation}.top_hits({n})

Exemple

L'exemple suivant renvoie le meilleur hit pour le terme halt par ville.

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

La réponse contient les premiers résultats de requête pour le terme halt regroupés par villes mentionnées dans les documents où le terme est le plus mentionné. Dix résultats sont renvoyés par défaut. Pour chacune des 10 villes, le document avec le score le plus élevé est renvoyé en tant qu'objet hit. Le contenu de chaque élément hit du tableau hits correspond au contenu de chaque élément result du tableau results. Seul l'ordre des résultats est différent.

"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": []
      }
      ...

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

tendance

Détecte les changements brusques et inattendus de la fréquence d'une valeur de mot clé sur une période donnée en fonction des changements de fréquence passés de la valeur de mot clé.

Sytnax

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

La première agrégation (facet) doit être l'un des types d'agrégation suivants:

  • term
  • group_by

Le paramètre relevancy de l'agrégation term ou group_by est ignoré.

La deuxième agrégation (time_segments) doit être une agrégation de type timeslice.

Vous pouvez également inclure les paramètres suivants:

  • show_estimated_matching_results:true: indique si les informations estimated_matching_results doivent être incluses dans le résultat. Cette zone contient le nombre de documents dont le terme est estimé dans la zone spécifiée ou qui remplissent les conditions de l'agrégation spécifiée pour l'intervalle de temps spécifié dans l'ensemble de documents renvoyés par la requête.
  • show_total_matching_documents:true: indique si les informations total_matching_documents doivent être incluses dans le résultat. Cette zone contient le nombre de documents de la collection où le terme est mentionné dans la zone spécifiée ou où la condition est remplie.

Une seule agrégation de tendances peut être utilisée par demande de requête et ne peut pas être combinée avec d'autres agrégations.

Exemple

L'exemple suivant calcule l' indicateur de tendance ou l' index de tendance à l'aide de combinaisons de résultats provenant des agrégations suivantes:

  • terme (saveur): vanille, chocolat, menthe
  • timeslice (date, 1month): janvier 2020, février 2020, mars 2020, avril 2020, mai 2020, juin 2020
trend( facet: aggregation(<parameter>...), time_segments: timeslice(<parameter>...)),
show_estimated_matching_results: <true_or_false>, show_total_matching_documents: <true_or_false> )

La matrice résultante peut être représentée dans un tableau.

Exemple d'agrégation de tendances
Ce tableau comporte des en-têtes de lignes et de colonnes. Les en-têtes de ligne identifient les mois de l'année 2020. Les en-têtes de colonne identifient les saveurs de crème glacée. Chaque cellule calcule un score de pertinence en multipliant la valeur de pertinence du mois (ligne) par la valeur de pertinence de la version (en-tête).
Mois en 2020 Version: vanille Saveur: chocolat Version: menthe
Jan vanille x Jan chocolat x Jan Mint x Jan
Fév vanille x fév chocolat x fév mint x fév
Mar vanille x Mar chocolat x Mar Mint x Mar
Avr vanille x avr chocolat x avr mint x avr
Mai vanille x mai chocolat x mai menthe x mai
Juin vanille x juin chocolat x juin mint x juin

Dans l'exemple de réponse suivant, les informations de clé sont la valeur trend_indicator. L'indicateur de tendance mesure le rapport d'augmentation de la fréquence d'une valeur de facette donnée pour un intervalle de temps donné par rapport à la fréquence moyenne attendue. La fréquence moyenne exceptée est calculée en fonction des changements dans les fréquences des intervalles de temps passés de la valeur de facette donnée, à l'aide d'une moyenne arithmétique pondérée.

Si la valeur résiduelle normalisée est inférieure à -2, la fréquence observée est inférieure à la fréquence attendue. Si elle est supérieure à 2, la fréquence observée est supérieure à la fréquence attendue. Si le résidu standardisé est supérieur ou inférieur à la fréquence attendue de 3 ou plus, alors quelque chose d'inhabituel se produit et suggère qu'il peut y avoir une anomalie qui mérite d'être explorée.

Par exemple, le nombre attendu de soumissions de commentaires pour la version vanilla en mai est calculé à partir du nombre de soumissions de commentaires reçues précédemment (de janvier à avril). Le résultat est 5.341. Le nombre réel de soumissions de commentaires en retour en mai est 10. Les résultats indiquent que le goût de vanille a obtenu environ deux fois plus de commentaires que prévu. La valeur résiduelle standardisée est 2.016, qui est supérieure à la valeur attendue, mais pas de façon inhabituelle.

{
"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": [...]
...
}  

sujet

Détecte la déviation de la fréquence d'une valeur de mot clé par rapport à la moyenne attendue pour la période spécifiée. Ce type d'agrégation n'utilise pas les données des périodes précédentes. Il calcule un index en utilisant les moyennes des nombres de fréquences des autres valeurs de mot clé pour la période spécifiée.

Syntaxe

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

La première agrégation (facet) doit être l'un des types d'agrégation suivants:

  • term
  • group_by

Le paramètre relevancy de l'agrégation term ou group_by est ignoré.

La deuxième agrégation (time_segments) doit être une agrégation de type timeslice.

Vous pouvez également inclure les paramètres suivants:

  • show_estimated_matching_results:true: indique si les informations estimated_matching_results doivent être incluses dans le résultat. Cette zone contient le nombre de documents dont le terme est estimé dans la zone spécifiée ou qui remplissent les conditions de l'agrégation spécifiée pour l'intervalle de temps spécifié dans l'ensemble de documents renvoyés par la requête.
  • show_total_matching_documents:true: indique si les informations total_matching_documents doivent être incluses dans le résultat. Cette zone contient le nombre de documents de la collection où le terme est mentionné dans la zone spécifiée ou où la condition est remplie.

Une seule agrégation de rubrique peut être utilisée par demande de requête et ne peut pas être combinée avec d'autres agrégations.

Exemple

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

Avec le même jeu de données et la même agrégation que ceux utilisés dans l'exemple d'agrégation de termes, les résultats peuvent se présenter comme suit.

Notez que les valeurs topic_indicator sont différentes des valeurs trend_indicator renvoyées par l'agrégation trend. Bien que les deux soient calculées à partir des fréquences réelles et attendues, elles diffèrent car leurs fréquences attendues sont calculées différemment. Dans l'agrégation trend, la fréquence prévue des soumissions de commentaires pour la crème glacée aromatisée à la vanille en mai est calculée à partir du nombre de soumissions de commentaires qui ont été reçues pour la vanille précédemment (de janvier à avril) et du nombre total de soumissions de commentaires reçues pour toutes les saveurs en mai. Toutefois, dans l'agrégation topic, la fréquence prévue des soumissions de rétroaction pour la crème glacée aromatisée à la vanille en mai est calculée à partir du nombre de soumissions de rétroaction reçues pour la vanille et du nombre total de soumissions de rétroaction reçues pour toutes les saveurs en mai. Dans cet exemple, le résultat de la fréquence attendue est 12.169, la fréquence réelle est 10 et topic_indicator est -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",
                ...
              }
}

unique_count

Renvoie un comptage des instances uniques de la zone spécifiée dans la collection.

Syntaxe

unique_count(field)

Exemple

L'agrégation suivante demande le nombre de types d'enrichissement uniques reconnus dans la requête.

unique_count(enriched_text.keyword.type)

Le résultat indique qu'il y a 17 résultats correspondants. Dans ces 17 documents, 14 types d'entités sont mentionnés.

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

Ce type d'agrégation effectue une opération de terminal. Lorsqu'elle est combinée à d'autres agrégations, la sortie n'est pas utilisée comme entrée pour l'agrégation suivante. La sortie est renvoyée dans un groupe discret.

Dans l'exemple suivant, le paramètre d'agrégation demande que les résultats affichent les 45 premières entités les plus fréquemment mentionnées. Par entité, il indique combien de documents mentionnent le terme et combien de fois au total le terme se produit.

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

Les résultats incluent plusieurs agrégations, telles que le groupe suivant pour le terme PostgreSQL. L'agrégation indique que le terme apparaît dans 4 documents et est mentionné 12 fois.

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