aggregate clause

Description

A keyword query can return tens of thousands of documents. Instead of browsing every document, you can use the aggregate clause to extract statistical information from the result set.

Syntax

aggregate=group_key:field, range:number1~number2, agg_fun:func1#func2, agg_filter:filter_clause, max_group:number

• group_key: Required. Specifies the field to group by. This field must be configured as an attribute field of type integer or string.

• agg_fun: Required. Specifies the aggregation function(s) to apply. Supported functions include count(), sum(field), max(field), and min(field), which calculate the document count, the sum of a field's values, the maximum value, and the minimum value, respectively. You can specify multiple functions by separating them with a hash sign (#). The arguments of sum(), max(), and min() also support basic arithmetic operations.

• range: Performs range aggregation, which is useful for distribution statistics. This parameter supports only a single range, defined as number1~number2. The engine calculates statistics for the range from number1 to number2 and for values greater than number2. Range aggregation is not supported for string fields.

• agg_filter: Optional. Aggregates only documents matching a specific condition.

• agg_sampler_threshold: Optional. The threshold for sampling. Documents ranked up to this value are fully aggregated, while documents ranked after this value are sampled.

• agg_sampler_step: Optional. The step size for sampling. For documents ranked after the agg_sampler_threshold, one document is sampled for every agg_sampler_step documents. For sum() and count() aggregations, the engine estimates the final result by multiplying the sampled result by the step size and adding it to the result from the documents processed before the threshold.

• max_group: Optional. The maximum number of groups to return. The default is 1000.

Examples:

• Simple aggregation

aggregate=group_key:group_id,agg_fun:sum(price)
Sample response (aggregation result only):
{
　　result: {
　　　　facet: [
　　　　　　{
　　　　　　　　key: "group_id",
　　　　　　　　items: [
　　　　　　　　　　{
　　　　　　　　　　　　value: 43,
　　　　　　　　　　　　sum: 81
　　　　　　　　　　},
　　　　　　　　　　{
　　　　　　　　　　　　value: 63,
　　　　　　　　　　　　sum: 91
　　　　　　　　　　}
　　　　　　　　]
　　　　　　}
　　　　]
　　}
},

• Sampling

aggregate=group_key:company_id,agg_fun:count(),agg_sampler_threshold:5,agg_sampler_step:2

Note: With a sampling threshold of 5 and a step size of 2, the first 5 matching documents are fully aggregated. After that, 1 out of every 2 documents is sampled. For sum() and count() functions, the engine produces the final estimated value by multiplying the result from the sampled set by the step size and adding it to the result from the initial set.

• Aggregate multiple metrics

aggregate=group_key:company_id,agg_fun:sum(id)#max(id)#min(id)
Note: This retrieves the sum, maximum value, and minimum value of the 'id' field for each 'company_id'. Separate multiple functions with a hash sign (#).

• Multiple group key aggregation

aggregate=group_key:id,agg_fun:sum(price);group_key:company_id,agg_fun:count(),agg_sampler_threshold:5,agg_sampler_step:2
Note: You can aggregate on multiple group keys. Separate the definitions for each group key with a semicolon (;).

• Accurate statistics

config=cluster:general.default_agg&&aggregate=group_key:company_id,agg_fun:count()
Note: To enable accurate statistics, append '.default_agg' to the cluster name. The engine guarantees accurate statistics only for results within the rank_size limit. If the number of matching documents greatly exceeds rank_size, the engine does not include documents beyond this limit in the aggregation.

• Approximate statistics

aggregate=group_key:company_id,agg_fun:distinct_count(brand)
Note: Using the `distinct_count()` function enables approximate statistics (based on the HyperLogLog algorithm). The accuracy loss is typically within 1%.

Notes

• The aggregate clause is optional.

• You must configure fields used in an aggregate clause as attribute fields in the application schema.

• The searcher node returns aggregation results in the facet node of its response. The name of the field that contains the result corresponds to the name of the aggregation function, such as sum or count.

• The aggregate clause supports aggregations on multiple group keys. Separate multiple aggregation definitions with a semicolon (;).

• The engine returns aggregation results in the facet node. To receive and display the facet content, you must set the format parameter in the config clause to fulljson.

• Due to engine performance limitations, the aggregate clause guarantees accurate document count statistics only for up to 100,000 returned documents. The engine does not guarantee accuracy for counts exceeding this limit.