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
.

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 :
- average
- filter
- group_by
- Histogramme
- max
- min
- imbriqué
- paire
- sum
- term
- intervalle de temps
- top_hits
- tendance
- Rubrique
- unique_count
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
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
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
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.
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
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 estfalse
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
, et1year
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 informationsestimated_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 informationstotal_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.
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 informationsestimated_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 informationstotal_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
}
]
}