aggregate clause
Clause description
A keyword query may return tens of thousands of documents. Users are unlikely to browse all of these documents to find the information they need. In some cases, users may be more interested in statistical information.
Syntax
Statistics clause format:
group_key:field, range:number1~number2, agg_fun:func1#func2, max_group:number2,
agg_filter:filter_clause, max_group:numberParameters:
Parameter | Type | Required | Valid values | Default value | Description |
group_key:field | field is an attribute field | Required | Currently, statistics are supported only for fields of the INT, LITERAL, INT_ARRAY, and LITERAL_ARRAY types. (Note: When statistics are calculated for fields of the INT_ARRAY or LITERAL_ARRAY type, each identical value in the field is used as a unit for statistics.) | field specifies the name of the field on which statistics are calculated. The field must be configured as an attribute field. | |
agg_fun | Required | Five system functions: count(id), sum(id), max(id), min(id), and distinct_count(id) | func can be one of the five system functions: count(), sum(id), max(id), min(id), and distinct_count(id). These functions respectively count the number of documents, calculate the sum of the id field, obtain the maximum value of the id field, obtain the minimum value of the id field, and count the distinct values of id. You can calculate statistics with multiple functions at the same time. Separate the functions with number signs (#). The content of sum, max, and min supports basic arithmetic operations. | ||
range | Optional | Indicates the interval from number1 to number2 and the interval greater than number2. (Note: Distribution statistics are not supported for fields of the string type.) | Specifies segmented statistics, which can be used for distribution statistics. Only a single range parameter is supported. | ||
agg_filter | Optional | Specifies that statistics are calculated only for documents that meet specific conditions. | |||
agg_sampler_threshold | int | Optional | , the threshold for sampling statistics. Documents before this value are counted one by one, and documents after this value are counted by sampling; | ||
agg_sampler_step | int | Optional | The step size for sampling statistics. Starting after agg_sampler_threshold, one document is counted every agg_sampler_step documents. For sum and count statistics, the sampling result after the threshold is multiplied by the step size to obtain an estimate. The estimate plus the statistics result before the threshold is the final statistics result. | ||
max_group | int | Optional | 1000 | The maximum number of groups to return. |
Usage notes
The aggregate clause is optional.
Fields that appear in the aggregate clause must be configured as attribute fields when you define the application schema.
The aggregate results are displayed in the facet node of the search results. The name of each value field is the name of agg_fun, such as sum or count.
The aggregate clause supports statistics on multiple keys. Separate multiple statistics with semicolons (;). Reference format:
group_key:field1,agg_fun:func1;group_key:field2,agg_fun:func2The statistics clause information is displayed in the facet node of the returned results only if format in the config clause is set to fulljson.
The distinct_count feature is supported only in exclusive clusters, and you must add the
enable_accurate_statistics:trueparameter to the kvpairs clause. When you use the distinct_count feature, the query no longer retrieves specific result data and returns only the statistics in facet.In exclusive clusters, accurate statistics are supported for count, max, min, and sum. You must add the enable_accurate_statistics:true parameter to the kvpairs clause.
Due to engine performance limits, the aggregate statistics clause can guarantee accurate document counts only when up to 100,000 documents are retrieved. Accuracy is not guaranteed for counts of more than 100,000 documents. (In exclusive clusters, you can improve statistical accuracy by adding the enable_accurate_statistics:true parameter to the kvpairs clause.)
Examples
Search for documents that contain "Zhejiang University" and calculate statistics by the group_id field. The statistics include the sum and maximum value of the price field. Also count the documents by company_id:
query=default:'Zhejiang University'&&aggregate=group_key:group_id,agg_fun:sum(price)#max(price);group_key:company_id,agg_fun:count()Results:
{ status: "OK", result: { searchtime: 0.015634, total: 5, num: 1, viewtotal: 5, items: [ //Specific search results { ... } ], facet: [ { key: "group_id", items: [ { value: 43, sum: 81, max: 20, }, { value: 63, sum: 91, max: 50, }, ], }, { key: "company_id", items: [ { value: 13, count: 4, }, { value: 10, count: 1, }, ], }, ], }, errors: [ ], tracer: "", },Search for documents that contain "Zhejiang University" and calculate statistics by the group_id field. The statistics include the sum of the price field. Documents after the first 10,000 are sampled with a step size of 5:
query=default:'Zhejiang University'&&aggregate=group_key:group_id,agg_fun:sum(price), agg_sampler_threshold:10000, agg_sampler_step:5Search for documents that contain "Zhejiang University" and count documents by the group_id field. The statistics dimensions are the numbers of documents in which the value is less than 10, from 10 to 50, and greater than 50:
query=default:'Zhejiang University'&&aggregate=group_key:group_id,agg_fun:count(),range:10~50Search for documents that contain "Zhejiang University" and, grouped by the group_id field, calculate the maximum value of the sum of hits and replies. Only documents whose create_timestamp is greater than 1423456781 are included in the statistics:
query=default:'Zhejiang University'&&aggregate=group_key:group_id,agg_fun:max(hits+replies),agg_filter:create_timestamp>1423456781