Aggregazioni di query

Utilizzare le aggregazioni per raggruppare, analizzare o confrontare i risultati restituiti da una richiesta di query.

Un'aggregazione è definita da un parametro di aggregation che puoi specificare nell'API Query. L'input per il parametro di aggregazione è la serie di documenti restituita dal parametro query, filter o natural_language_query specificato come parametro separato nella stessa richiesta di query. Altrimenti, l'aggregazione viene applicata a tutti i documenti nel progetto.

È possibile utilizzare un'aggregazione per eseguire calcoli dai valori nella serie di documenti risultati. Ad esempio, per ottenere informazioni sull'importo più elevato in dollari nel campo order.total dei documenti restituiti come risultati della query, utilizzare max(order.total) come valore del parametro aggregation.

Esempio di struttura della query di aggregazione che mostra max come tipo di aggregazione e order.total come raggruppamento dei
del
di struttura della query di aggregazione*

Il parametro di aggregazione restituisce i dati relativi al campo con il valore più alto.

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

Raggruppamento di documenti

Oltre a eseguire i calcoli, è possibile utilizzare un'aggregazione per raggruppare i documenti nella serie di risultati che corrispondono a determinati valori, in modo da poterli contare o analizzare ulteriormente. Ad esempio, puoi utilizzare un'aggregazione per ricercare una serie di report di incidenti di traffico per documenti che menzionano il termine brake. E dai documenti restituiti, trova i report degli Stati Uniti con le menzioni più rilevanti del termine.

Nella seguente richiesta di esempio, viene incluso il parametro di conteggio che restituisce solo 3 risultati di aggregazione per rendere l'esempio più semplice da seguire.

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

L'output del parametro di aggregazione viene restituito in un oggetto aggregations che viene visualizzato prima dell'oggetto results, che contiene i risultati della query. È possibile restituire un massimo di 50.000 valori nell'oggetto aggregations per una singola interrogazione.

L'oggetto aggregations risultante contiene informazioni di riepilogo sui risultati della query. In questo esempio, ad esempio, mostra che i report di incidenti di traffico da New York, California e Florida hanno le citazioni più rilevanti del termine 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": []

Combinazione di tipi di aggregazione

Esistono diversi tipi di aggregazioni che è possibile utilizzare per analizzare o raggruppare i risultati della query. Inoltre, è possibile combinare più di un'aggregazione in una richiesta per eseguire un'analisi più mirata.

Il seguente esempio mostra una richiesta composta da due operatori di termini. Il primo termine di aggregazione raggruppa i documenti di input in base ai valori US STATE e seleziona 3 gruppi. Il secondo termine di aggregazione si applica a ciascuno di questi 3 gruppi e li raggruppa ulteriormente in base al valore di CITY. Solo 2 di questi sottogruppi CITY vengono restituiti per gruppo STATE.

Il parametro di rilevanza viene escluso per rendere i risultati più semplici da leggere.

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

La risposta contiene informazioni sulla città da ogni stato.

{
  "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'ordine in cui si specificano le aggregazioni. Ad esempio, se si inverte l'ordine delle aggregazioni di termini dall'esempio precedente, si ottengono risultati diversi.

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

Il nuovo ordine produce risultati che fanno superficie a Chicago, una città che non era inclusa nella serie precedente di risultati. Quando la richiesta inizia raggruppando per stato, Illinois, che ha solo una città con un numero elevato di report di incidenti stradali, non è incluso nei risultati. New York e la Florida, che hanno entrambe più di una città con molte segnalazioni di incidenti, hanno prodotto un maggior numero di partite in tutto lo stato e quindi, sono stati restituiti. Quando si raggruppa per città per prima, i risultati cambiano.

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

Utilizzo delle aggregazioni per esplorare gli arricchimenti

L'aggregazione term() è particolarmente utile per analizzare i risultati per scoprire quanti arricchimenti vengono riconosciuti nei documenti. Ad esempio, per contare il numero di volte in cui ogni tipo di entità viene riconosciuto nei documenti filtrati, è possibile inviare i seguenti parametri della query:

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

La query seleziona prima i documenti che hanno almeno un'entità di tipo Location e il testo è Gilroy. Questa azione restituisce 3 documenti. Dai documenti restituiti, l'aggregazione conta il numero di documenti in cui viene visualizzato ciascun tipo di entità.

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

I 3 documenti corrispondenti hanno tutti un tipo di entità Location e Person ("matching_results": 3). Tuttavia, solo 2 dei documenti corrispondenti hanno un tipo entità Company.

Per impostazione predefinita, vengono restituite le prime 10 corrispondenze, ordinate per rilevanza. È possibile cambiare il numero di risultati aggiungendo il parametro count all'aggregazione.

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

Aggiungi un filtro

Utilizzare filter() nella clausola di aggregazione per filtrare i risultati. Ad esempio, è possibile specificare lo stesso filtro che è stato inoltrato separatamente nell'esempio precedente direttamente nella clausola aggregation.

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

In questo caso, l'aggregazione filter().term() trova lo stesso risultato dell'esempio precedente con le clausole filter e aggregation separate. Tuttavia, i risultati vengono classificati in modo diverso quando viene utilizzata la clausola filter. È possibile sfruttare questa differenza utilizzando la clausola filter() all'interno della clausola aggregation per filtrare i risultati da una serie di espressioni, come mostrato nell'esempio successivo.

Inizia con oggetti nidificati

Negli esempi precedenti, il valore "matching_counts" rappresenta il numero di documenti che corrispondono al filtro e all'aggregazione. È possibile contare quanti oggetti nidificati sono presenti nella risposta della query. L'aggregazione nested() consente di modificare la serie di documenti utilizzata come input per altri termini di aggregazione.

Ad esempio, nella seguente query il segmento nested() seleziona tutti gli oggetti nidificati enriched_text.entities come input utilizzato dai segmenti filter() e term().

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

La query risulta in un oggetto aggregations che si presenta come segue:

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

Il segmento nested() della query ha trovato oggetti nidificati 1993 enriched_text.entities. Il filtro è stato applicato a tali oggetti e ha trovato 645 enriched_text.entities di tipo Organization.

Operazioni terminale

Per la maggior parte dei tipi di aggregazione, quando si crea una query con più operazioni di aggregazione, la prima operazione viene applicata ai documenti. Quindi, l'output di tale operazione viene utilizzato come input per l'operazione successiva. Tuttavia, un sottoinsieme dei tipi di aggregazioni è operazioni terminale. L'output di un'operazione di terminale non viene utilizzato come input per l'aggregazione successiva. Invece, l'output viene restituito in un gruppo discreto.

Per un esempio di richiesta che combina tipi di aggregazione e include un'aggregazione che esegue un'operazione terminale, consultare il secondo esempio per il tipo di aggregazione average.

Tipi di aggregazione

Sono supportati i seguenti tipi di aggregazioni:

Per i tipi di progetto di richiamo documenti, quando non si include un parametro di aggregazione in una richiesta di query, viene applicata una richiesta di aggregazione predefinita. Per ulteriori informazioni, consultare Document Retrieval project aggregations.

Per ulteriori informazioni su come inoltrare una query, vedi il Riferimento API Discovery.

media

Restituisce la media dei valori del campo specificato su tutti i documenti corrispondenti.

Sintassi

average(field)

Esempio

Esempi di prezzi dei prodotti
Prodotto Prezzo
Serie i 200
Serie J 450
Serie X 325

Quando il tipo di aggregazione average viene applicato a una serie di documenti in cui il campo price contiene i valori mostrati nella Tabella 1, il risultato è 325.

average(price)=325

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

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

Per ogni stato restituito dalla prima operazione di aggregazione term, la risposta mostra la velocità media del veicolo specificata nei report di incidente. Notare che la seconda aggregazione term utilizza l'output della prima aggregazione term, non l'aggregazione average, come suo input.

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

filtro

Un modificatore che restringe la serie di documenti della query di aggregazione che precede.

Sintassi

filter(field)

Esempio

Il seguente esempio filtra la serie di documenti corrispondenti per includere solo i documenti che menzionano IBM.

filter(enriched_text.entities.text:IBM)

Se combinato con altre aggregazioni, filtra i documenti corrispondenti impostati in modo da includere solo i documenti che soddisfano la condizione specificata.

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

La risposta della query mostra le città in cui si verificano incidenti che coinvolgono i freni e la velocità del veicolo è superiore 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
                    }
                  ]
                }
              ]
            }

gruppo_da

Separa i risultati in gruppi definiti dall'utente.

Sintassi

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

Ogni condizione deve essere specificata come un'espressione Discovery Query Language valida racchiusa tra parentesi. Ad esempio, (age<20) o (flavor:chocolate). Il numero massimo di condizioni che possono essere definite è 50.

Puoi facoltativamente includere il parametro relevancy e impostarlo su true per restituire il valore di rilevanza della serie di documenti che soddisfano la condizione specificata. Quando true, i risultati sono ordinati in base alla rilevanza. Quando false, i risultati vengono ordinati per il numero più elevato di matching_results.

Esempio

La seguente richiesta cerca i documenti che riportano il termine engine e li raggruppa per anno di produzione dell'auto. I documenti sono suddivisi in 3 gruppi, un gruppo di segnalazioni di incidenti stradali che coinvolgono auto prodotte prima del 2000, un gruppo per auto prodotte nel 2000 e un gruppo per auto prodotte dopo il 2000.

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

I risultati potrebbero essere simili a quelli riportati di seguito:

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

istrogramma

Crea segmenti di intervallo numerico per categorizzare i documenti.

Sintassi

histogram({field},{interval})

Utilizza i valori campo da un singolo campo numerico per descrivere la categoria. Il campo utilizzato per creare l'istogramma deve avere un tipo di dati numerico, ad esempio integer, float, double o date.

I tipi non numerici come string non sono supportati. Ad esempio, "price": 1.30 è un valore numerico che funziona, mentre "price": "1.30" è una stringa, quindi non funziona.

Utilizzare l'argomento interval per definire la dimensione delle sezioni in cui dividere i risultati. I valori di intervallo devono essere numeri interi non negativi. Scegliere un valore che abbia senso per segmentare i valori tipici dal campo.

Gli istogrammi possono elaborare valori decimali specificati in un campo, ma l'intervallo deve essere un numero intero.

È possibile includere un nome personalizzato includendo un parametro name.

Esempio

Ad esempio, se il proprio dataset include il prezzo di diversi elementi, come: “price”: 1.30, “price”: 1.99 e “price”: 2.99, è possibile utilizzare gli intervalli di 1, in modo da visualizzare tutto ciò che è raggruppato nell'intervallo 1 - 2 e 2 e 3. Non si desidera utilizzare un intervallo di 100 perché tutti i dati finiscono nello stesso segmento.

histogram(product_price,interval:1)

max

Restituisce il valore più alto nel campo specificato su tutti i documenti corrispondenti.

Sintassi

max(field)

Esempio

Esempi di prezzi dei prodotti
Prodotto Prezzo
Serie i 200
Serie J 450
Serie X 325

Quando il tipo di aggregazione max viene applicato a una serie di documenti in cui il campo price contiene i valori mostrati nella Tabella 2, il risultato è 450.

max(price)=450

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

min

Restituisce il valore più basso nel campo specificato su tutti i documenti corrispondenti.

Sintassi

min(field)

Esempio

Esempi di prezzi dei prodotti
Prodotto Prezzo
Serie i 200
Serie J 450
Serie X 325

Quando il tipo di aggregazione min viene applicato a una serie di documenti in cui il campo price contiene i valori mostrati nella Tabella 3, il risultato è 200.

min(price)=200

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

nidificato

L'applicazione di nested prima di una query di aggregazione limita l'aggregazione all'area dei risultati specificati.

Ad esempio, nested(enriched_text.entities) significa che solo i componenti enriched_text.entities di qualsiasi risultato vengono utilizzati per l'aggregazione.

Il seguente esempio controlla quante citazioni vengono restituite per tipo di modello.

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

Il risultato mostra che ci sono un totale di 50 entità riconosciute e tutte di tipo 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
          }
        ]
      }
    ]
  }
]

Per un altro esempio, vedere Avvio con oggetti nidificati.

coppia

Analizza le relazioni tra due campi.

Sintassi

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

Il primo e il secondo valore {aggregation} devono essere uno dei seguenti tipi di aggregazione:

  • term
  • group_by
  • histogram
  • timeslice

Il parametro relevancy dall'aggregazione term o group_by viene ignorato. Il tipo di aggregazione pair calcola i valori di pertinenza utilizzando combinazioni di serie di documenti dai risultati delle due aggregazioni.

Solo un'aggregazione di coppie può essere utilizzata per richiesta di query e non può essere combinata con altre aggregazioni.

Esempio

Ad esempio, è possibile specificare term(model_name) come prima aggregazione e term(component_name) come seconda. Ciascuna delle aggregazioni restituisce i seguenti valori come chiavi di serie di documenti aggregati:

  • term (nome_modello): Accord, CR-V
  • termine (component_name): motore, freno, radiatore

I valori di rilevanza calcolati delle combinazioni di ciascuna serie di documenti potrebbero essere simili a quelli riportati di seguito:

  • Motore Accord x
  • Accord x freno
  • Radiatore x Accord
  • Motore CR-V x
  • Freno CR-V x
  • Radiatore CR-V x

La risposta definisce un array bidimensionale di risultati di aggregazione, che possono essere rappresentati in una tabella.

Esempio di aggregazione a coppie
Questa tabella ha intestazioni di riga e di colonna. Le intestazioni di riga identificano i modelli di auto. Le intestazioni di colonna identificano le parti del componente auto. Ogni cella calcola un punteggio di rilevanza moltiplicando il valore di rilevanza del modello di auto (riga) per il valore di rilevanza del componente auto (intestazione).
Modello di automobile Componente: motore Componente: freno Componente: radiatore
Accordo Motore Accord x Accord x freno Radiatore x Accord
CRV Motore CR-V x Freno CR-V x Radiatore CR-V x

Ogni array di colonne e righe della tabella viene ordinato nello stesso ordine dei risultati della prima e della seconda aggregazione. Ad esempio, se si specifica l'aggregazione term come primo argomento, gli array di colonne risultanti vengono ordinati in base alla frequenza dei termini. Se si utilizza l'aggregazione timeslice come secondo argomento, gli array di righe vengono ordinati per data o ora.

somma

Aggiunge i valori del campo specificato in tutti i documenti corrispondenti.

Sintassi

sum(field)

Esempio

Esempi di prezzi dei prodotti
Prodotto Prezzo
Serie i 200
Serie J 450
Serie X 325

Quando il tipo di aggregazione sum viene applicato a una serie di documenti in cui il campo price contiene i valori mostrati nella Tabella 6, il risultato è 975.

sum(price)=975

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

termine

Indica la frequenza di un termine o di una serie di termini in una serie di documenti sottoposti a query.

Sintassi

term(field:{field_name})

Facoltativamente, è possibile specificare i seguenti parametri:

  • count: Specifica il numero massimo di termini da restituire.

  • name: è possibile includere facoltativamente un nome personalizzato. Non viene restituito se le informazioni di rilevanza sono incluse nella richiesta.

  • relevancy: valore booleano che indica se includere le informazioni di rilevanza nel risultato. È possibile utilizzare la rilevanza per ottenere un punteggio che indica il livello di rilevanza tra il termine e le parole chiave nella query. Questo parametro è false per impostazione predefinita. Se impostato su true, vengono restituiti anche i seguenti campi:

    • total_matching_documents: numero di documenti nella raccolta in cui il termine è menzionato nel campo specificato.
    • estimated_matching_results: numero di documenti che si stima abbiano il termine nel campo specificato nella serie di documenti restituiti dalla query.

Esempio

Il seguente esempio restituisce il testo dalle entità riconosciute nel documento e specifica di restituire un massimo di 10 termini.

Ad esempio:

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

Quando relevancy è impostato su true, nei risultati viene visualizzato un punteggio di rilevanza. La rilevanza misura il livello di univocità del numero di frequenza confrontato con altri documenti che corrispondono alla query. Se la rilevanza mostra 2.0, significa che il numero di volte in cui i due punti di dati si intersecano è 2 volte più grande del previsto.

Per ulteriori esempi, consultare Raggruppamento di documenti e Combinazione di tipi di aggregazione.

timeslice

Un istogramma specializzato che utilizza le date per creare segmenti di intervallo.

Sintassi

La sintassi è timeslice({field},{interval},{time_zone}).

  • Il campo specificato deve avere un tipo di dati date. Per ulteriori informazioni sul campo data, consultare Modalità di gestione delle date.
  • I valori di intervalli validi sono 1second o {n}seconds, 1minute o {n}minutes, 1hour o {n}hours, 1day o {n}days, 1week o {n}weeks, 1month o {n}months, e 1year o {n}years dove {n} è un numero.
  • È possibile includere un nome personalizzato includendo un parametro name.

Esempio

Il seguente esempio mostra il numero di corrispondenze per ogni valore del giorno.

timeslice(field:DATEA,interval:1day)

I risultati sono i seguenti.

"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

Restituisce i documenti classificati in base al punteggio della query o dell'arricchimento. Può essere utilizzato con qualsiasi aggregazione o parametro di query.

Sintassi

{aggregation}.top_hits({n})

Esempio

Il seguente esempio restituisce l'hit principale per il termine halt per città.

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

La risposta contiene i primi risultati della query per il termine halt raggruppati per città indicate nei documenti in cui il termine è più menzionato. Per impostazione predefinita vengono restituiti dieci risultati. Per ciascuna delle 10 città, il documento con il punteggio più alto viene restituito come oggetto hit. Il contenuto per ogni hit nell'array hits corrisponde al contenuto in ogni result nell'array results. Solo l'ordine dei risultati è diverso.

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

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

tendenza

Rileva le modifiche acute e impreviste nella frequenza di un valore della parola chiave in un periodo di tempo specificato in base alle modifiche di frequenza passate del valore della parola chiave.

Sytnax

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

La prima aggregazione (facet) deve essere uno dei seguenti tipi di aggregazioni:

  • term
  • group_by

Il parametro relevancy dall'aggregazione term o group_by viene ignorato.

La seconda aggregazione (time_segments) deve essere un'aggregazione di tipo timeslice.

In alternativa è possibile includere i parametri seguenti:

  • show_estimated_matching_results:true: indica se includere le informazioni estimated_matching_results nel risultato. Questo campo contiene il numero di documenti che si stima abbiano il termine nel campo specificato o soddisfino le condizioni nell'aggregazione specificata per l'intervallo di tempo specificato nella serie di documenti restituiti dalla query.
  • show_total_matching_documents:true: indica se includere le informazioni total_matching_documents nel risultato. Questo campo contiene il numero di documenti nella raccolta in cui il termine viene menzionato nel campo specificato o in cui viene soddisfatta la condizione.

È possibile utilizzare una sola aggregazione di tendenza per richiesta di query e non può essere combinata con altre aggregazioni.

Esempio

Il seguente esempio calcola l' indicatore di tendenza o indice di tendenza utilizzando combinazioni di risultati dalle seguenti aggregazioni:

  • Termine (sapore): vaniglia, cioccolato, menta
  • timeslice (date, 1month): Jan 2020, Feb 2020, Mar 2020, Apr 2020, May 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> )

La matrice risultante può essere rappresentata in una tabella.

Esempio di aggregazione delle tendenze
Questa tabella ha intestazioni di riga e di colonna. Le intestazioni di riga identificano i mesi dell'anno 2020. Le intestazioni delle colonne identificano i sapori del gelato. Ogni cella calcola un punteggio di rilevanza moltiplicando il valore di rilevanza mese (riga) per il valore di rilevanza flavor (intestazione).
Mese nel 2020 Sapore: vaniglia Sapore: cioccolato Sapore: menta
Gen vaniglia x Jan Cioccolato x Jan menta x gen
Feb vaniglia x Feb cioccolato x feb menta x feb
Mar vaniglia x Mar cioccolato x Mar menta x Mar
Apr vaniglia x Apr cioccolato x Apr menta x Apr
Maggio vaniglia x Maggio Cioccolato x Maggio menta x Maggio
Giu vaniglia x Giu cioccolato x Giu zecca x Giu

Nella seguente risposta di esempio, le informazioni chiave sono il valore trend_indicator. L'indicatore di tendenza misura il rapporto di aumento della frequenza di un determinato valore facet per un determinato intervallo di tempo rispetto alla frequenza media prevista. La frequenza media esclusa viene calcolata in base alle variazioni delle frequenze dell'intervallo di tempo passato del valore di facet fornito, utilizzando una media aritmetica ponderata.

Se il valore residuo standardizzato è inferiore a -2, la frequenza osservata è inferiore alla frequenza attesa. Se è maggiore di 2, la frequenza osservata è maggiore della frequenza prevista. Se il residuo standardizzato è maggiore o minore della frequenza prevista di 3 o più, sta accadendo qualcosa di insolito e suggerisce che potrebbe esserci un'anomalia che vale la pena investigare.

Ad esempio, il numero previsto di invii di feedback per il flavor vanilla a maggio viene calcolato dal numero di invii di feedback ricevuti precedentemente (da Gen ad Apr). Il risultato è 5.341. Il numero effettivo di invii di feedback a maggio è 10. I risultati indicano che il sapore di vaniglia ha ottenuto circa il doppio del numero di invii di feedback come previsto. Il valore residuo standardizzato è 2.016, che è maggiore del previsto, ma non in modo insolito.

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

argomento

Rileva la differenza tra la frequenza di un valore della parola chiave e la media prevista per il periodo di tempo specificato. Questo tipo di aggregazione non utilizza i dati dei periodi di tempo precedenti. Calcola un indice utilizzando le medie dei conteggi di frequenza di altri valori di parola chiave per il periodo di tempo specificato.

Sintassi

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

La prima aggregazione (facet) deve essere uno dei seguenti tipi di aggregazioni:

  • term
  • group_by

Il parametro relevancy dall'aggregazione term o group_by viene ignorato.

La seconda aggregazione (time_segments) deve essere un'aggregazione di tipo timeslice.

In alternativa è possibile includere i parametri seguenti:

  • show_estimated_matching_results:true: indica se includere le informazioni estimated_matching_results nel risultato. Questo campo contiene il numero di documenti che si stima abbiano il termine nel campo specificato o soddisfino le condizioni nell'aggregazione specificata per l'intervallo di tempo specificato nella serie di documenti restituiti dalla query.
  • show_total_matching_documents:true: indica se includere le informazioni total_matching_documents nel risultato. Questo campo contiene il numero di documenti nella raccolta in cui il termine viene menzionato nel campo specificato o in cui viene soddisfatta la condizione.

Solo un'aggregazione di argomenti può essere utilizzata per richiesta di query e non può essere combinata con altre aggregazioni.

Esempio

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

Con la stessa serie di dati e aggregazione utilizzata nell'esempio di aggregazione del termine, i risultati potrebbero essere simili a quelli riportati di seguito.

Si noti che i valori topic_indicator sono differenti dai valori trend_indicator restituiti dall'aggregazione trend. Mentre entrambi sono calcolati dalle frequenze effettive e previste, differiscono perché le loro frequenze previste sono calcolate in modo diverso. Nell'aggregazione trend, la frequenza prevista di invio di feedback per il gelato aromatizzato alla vaniglia a maggio viene calcolata dal numero di invii di feedback ricevuti in precedenza per la vaniglia (da Jan ad Apr) e dal numero totale di invii di feedback ricevuti per tutti i flavor a maggio. Tuttavia, nell'aggregazione topic, la frequenza prevista di invii di feedback per il gelato aromatizzato alla vaniglia a maggio è calcolata dal numero di invii di feedback ricevuti per la vaniglia e dal numero totale di invii di feedback ricevuti per tutti i gusti a maggio. In questo esempio, il risultato della frequenza previsto è 12.169, la frequenza effettiva è 10 e 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",
                ...
              }
}

unique_count

Restituisce un conteggio delle istanze univoche del campo specificato nella raccolta.

Sintassi

unique_count(field)

Esempio

La seguente aggregazione richiede il numero di tipi di arricchimento univoci riconosciuti nella query.

unique_count(enriched_text.keyword.type)

Il risultato indica che ci sono 17 risultati corrispondenti. In questi 17 documenti vengono menzionati 14 tipi di entità.

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

Questo tipo di aggregazione esegue un'operazione di terminale. Se combinato con altre aggregazioni, l'output non viene utilizzato come input per l'aggregazione successiva. L'output viene restituito in un gruppo discreto.

Nel seguente esempio, il parametro di aggregazione richiede che i risultati mostrino le prime 45 entità più frequentemente menzionate. Per entità, indica quanti documenti menzionano il termine e quante volte in totale si verifica il termine.

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

I risultati includono diverse aggregazioni come il seguente gruppo per il termine PostgreSQL. L'aggregazione indica che il termine appare in 4 documenti ed è menzionato 12 volte.

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