All Products
Search
Document Center

Tablestore:Aggregation

Last Updated:Aug 23, 2023

You can perform aggregation operations to obtain the minimum value, maximum value, sum, average, count and distinct count of rows, percentile statistics, and rows in each group. You can also perform aggregation operations to group results by field value, range, geographical location, filter, or histogram, and perform nested queries. You can perform multiple aggregation operations for complex queries.

Procedure

The following figure shows the complete procedure of aggregation.

fig_agg_pro

The server queries the data that meets the query conditions and performs aggregation on the data based on the request. Therefore, a request that requires aggregation is more complex than a request that does not require aggregation.

Background information

The following table describes the aggregation methods.
MethodDescription
Minimum value

The aggregation method that can be used to return the minimum value of a field. This method can be used in a similar manner as the SQL MIN function.

Maximum value

The aggregation method that can be used to return the maximum value of a field. This method can be used in a similar manner as the SQL MAX function.

Sum

The aggregation method that can be used to return the sum of all values for a numeric field. This method can be used in a similar manner as the SQL SUM function.

Average value

The aggregation method that can be used to return the average of all values for a numeric field. This method is used in a similar manner as the SQL AVG function.

CountThe aggregation method that can be used to return the total number of values for a specified field or the total number of rows in a search index. This method can be used in a similar manner as the SQL COUNT function.
Distinct countThe aggregation method that can be used to return the number of distinct values for a field. This method can be used in a similar manner as the SQL COUNT(DISTINCT) function.
Percentile statistics

A percentile value indicates the relative position of a value in a dataset. For example, when you collect statistics for the response time of each request during the routine O&M of your system, you must analyze the response time distribution by using percentiles such as p25, p50, p90, and p99.

Group by field value
The aggregation method that can be used to group query results based on field values. The values that are the same are grouped together. The identical value of each group and the number of identical values in each group are returned.
Note The calculated number may be different from the actual number if the number of values in a group is very large.
Group by range

The aggregation method that can be used to group query results based on the value ranges of a field. Field values that are within a specified range are grouped together. The number of values in each range is returned.

Group by geographical location

The aggregation method that can be used to group query results based on geographical locations to a central point. Query results in distances that are within a specified range are grouped together. The number of items in each range is returned.

Group by filter

The aggregation method that can be used to filter the query results and group them together to obtain the number of results that match each filter. Results are returned in the order in which the filters are specified.

Query by histogram

The aggregation method that can be used to group query results based on specific data intervals. Field values that are within the same range are grouped together. The value range of each group and the number of values in each group are returned.

Query the rows that are obtained from the results of an aggregation operation in each group

After you group query results, you can query the rows in each group. This method can be used in a similar manner as ANY_VALUE(field) in MySQL.

Nesting

GroupBy supports nesting. You can perform sub-aggregation operations by using GroupBy.

Multiple aggregations
You can perform multiple aggregation operations.
Note If you perform multiple complex aggregation operations at the same time, a long period of time may be required.

Prerequisites

  • An OTSClient instance is initialized. For more information, see Initialization.
  • A data table is created. Data is written to the table.
  • A search index is created for the data table. For more information, see Create search indexes.

Minimum value

The aggregation method that can be used to return the minimum value of a field. This method can be used in a similar manner as the SQL MIN function.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, and DATE types are supported.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Minimum value. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void MinAggregation(OTSClient otsClient)
    {
        MinAggregation minAggregation = new MinAggregation();
        minAggregation.AggName = "Min_Agg";
        minAggregation.FieldName = "pk1";
    
        RangeQuery rangeQuery = new RangeQuery();
        rangeQuery.FieldName = "pk1";
        rangeQuery.From = new ColumnValue(0);
        rangeQuery.To = new ColumnValue(100);
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = rangeQuery,
            AggregationList = new List<IAggregation>
            {
                minAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsMinAggregationResult("Min_Agg")));
    }

Maximum value

The aggregation method that can be used to return the maximum value of a field. This method can be used in a similar manner as the SQL MAX function.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, and DATE types are supported.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Maximum value. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void MaxAggregation(OTSClient otsClient)
    {
        MaxAggregation maxAggregation = new MaxAggregation();
        maxAggregation.AggName = "Max_Agg";
        maxAggregation.FieldName = "pk1";
    
        RangeQuery rangeQuery = new RangeQuery();
        rangeQuery.FieldName = "pk1";
        rangeQuery.From = new ColumnValue(0);
        rangeQuery.To = new ColumnValue(100);
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = rangeQuery,
            AggregationList = new List<IAggregation>
            {
                maxAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsMaxAggregationResult("Max_Agg")));
    }

Sum

The aggregation method that can be used to return the sum of all values for a numeric field. This method can be used in a similar manner as the SQL SUM function.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG and DOUBLE types are supported.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Sum. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void SumAggregation(OTSClient otsClient)
    {
        SumAggregation sumAggregation = new SumAggregation();
        sumAggregation.AggName = "Sum_Agg";
        sumAggregation.FieldName = "pk1";
    
        RangeQuery rangeQuery = new RangeQuery();
        rangeQuery.FieldName = "pk1";
        rangeQuery.From = new ColumnValue(0);
        rangeQuery.To = new ColumnValue(100);
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = rangeQuery,
            AggregationList = new List<IAggregation>
            {
                sumAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsSumAggregationResult("Sum_Agg")));
    }

Average value

The aggregation method that can be used to return the average of all values for a numeric field. This method is used in a similar manner as the SQL AVG function.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, and DATE types are supported.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Average value. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void AvgAggregation(OTSClient otsClient)
    {
        AvgAggregation avgAggregation = new AvgAggregation();
        avgAggregation.AggName = "Avg_Agg";
        avgAggregation.FieldName = "pk1";
    
        RangeQuery rangeQuery = new RangeQuery();
        rangeQuery.FieldName = "pk1";
        rangeQuery.From = new ColumnValue(0);
        rangeQuery.To = new ColumnValue(100);
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = rangeQuery,
            AggregationList = new List<IAggregation>
            {
                avgAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsAvgAggregationResult("Avg_Agg")));
    }

Count

The aggregation method that can be used to return the total number of values for a specified field or the total number of rows in a search index. This method can be used in a similar manner as the SQL COUNT function.

Note

You can use the following methods to query the total number of rows in a search index or the total number of rows that meet the query conditions:

  • Use the count feature of aggregation and specify count(*) in the request.

  • Use the query feature to obtain the number of rows that meet the query conditions. Set setGetTotalCount to true in the query. Use MatchAllQuery to obtain the total number of rows in a search index.

You can use the name of a column as the value of the count expression to query the number of rows that contain the column in a search index. This method is suitable for scenarios that involve sparse columns.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, BOOLEAN, KEYWORD, GEO_POINT, and DATE types are supported.

  • Example

    /// <summary>
    /// Count. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void CountAggregation(OTSClient otsClient)
    {
        CountAggregation countAggregation = new CountAggregation();
        countAggregation.AggName = "Count_Agg";
        countAggregation.FieldName = "pk1";
    
        RangeQuery rangeQuery = new RangeQuery();
        rangeQuery.FieldName = "pk1";
        rangeQuery.From = new ColumnValue(0);
        rangeQuery.To = new ColumnValue(100);
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = rangeQuery,
            AggregationList = new List<IAggregation>
            {
                countAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsCountAggregationResult("Count_Agg")));
    }

Distinct count

The aggregation method that can be used to return the number of distinct values for a field. This method can be used in a similar manner as the SQL COUNT(DISTINCT) function.

Note

The number of distinct values is an approximate number.

  • If the total number of rows before the distinct count feature is used is less than 10,000, the calculated result is close to the exact value.

  • If the total number of rows before the distinct count feature is used is greater than or equal to 100 million, the error rate is approximately 2%.

  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, BOOLEAN, KEYWORD, GEO_POINT, and DATE types are supported.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Distinct count. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void DistinctCountAggregation(OTSClient otsClient)
    {
        DistinctCountAggregation distinctCountAggregation = new DistinctCountAggregation();
        distinctCountAggregation.AggName = "DistinctCount_Agg";
        distinctCountAggregation.FieldName = "pk1";
    
        TermsQuery termsQuery = new TermsQuery();
        termsQuery.FieldName = "pk0";
        termsQuery.Terms = new List<ColumnValue>
        {
            new ColumnValue("Sample"),
            new ColumnValue("SearchIndex")
        };
    
        SearchQuery seachQuery = new SearchQuery
        {
            Limit = 0,
            Query = termsQuery,
            AggregationList = new List<IAggregation>
            {
                distinctCountAggregation
            }
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, seachQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse.AggregationResults.GetAsDistinctCountAggregationResult("DistinctCount_Agg")));
    }

Percentile statistics

A percentile value indicates the relative position of a value in a dataset. For example, when you collect statistics for the response time of each request during the routine O&M of your system, you must analyze the response time distribution by using percentiles such as p25, p50, p90, and p99.

Note To improve the accuracy of the results, we recommend that you specify extreme percentile values such as p1 and p99. If you use extreme percentile values instead of other values such as p50, the returned results are more accurate.
  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, and DATE types are supported.

    Percentiles

    The percentiles such as p50, p90, and p99. You can specify one or more percentiles.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Percentile statistics. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void PercentilesAggregation(OTSClient otsClient)
    {
        PercentilesAggregation percentilesAggregation = new PercentilesAggregation();
        percentilesAggregation.AggName = "Percentiles_Agg";
        percentilesAggregation.FieldName = "pk1";
        percentilesAggregation.Missing = new ColumnValue(10);
        percentilesAggregation.Percentiles = new List<double> { 10.0, 30.0, 60.0, 90.0, 100.0 };
    
        MatchAllQuery matchAllQuery = new MatchAllQuery();
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.AggregationList = new List<IAggregation> { percentilesAggregation };
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
    }

Group by field value

The aggregation method that can be used to group query results based on field values. The values that are the same are grouped together. The identical value of each group and the number of identical values in each group are returned.

Note

The calculated number may be different from the actual number if the number of values in a group is very large.

  • Parameters

    Parameter

    Description

    GroupByName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG, DOUBLE, BOOLEAN, KEYWORD, and DATE types are supported.

    Size

    The number of groups that you want to return. Default value: 10. Maximum value: 2000. If the number of groups exceeds 2,000, only the first 2,000 groups are returned.

    GroupBySorters

    The sorting rules for groups. By default, groups are sorted based on the number of items in the groups in descending order. If you configure multiple sorting rules, the groups are sorted based on the order in which the rules are configured. Supported parameters:

    • Sort by value in alphabetical order.

    • Sort by value in reverse alphabetical order.

    • Sort by row count in ascending order.

    • Sort by row count in descending order.

    • Sort by the values that are obtained from sub-aggregation results in ascending order.

    • Sort by the values that are obtained from sub-aggregation results in descending order.

    SubAggregation and SubGroupBy

    The sub-aggregation operation. You can perform the sub-aggregation operation based on the grouping results.

    • Scenario

      Query the number of products in each category, and the maximum and minimum product prices in each category.

    • Methods

      Group query results by product category to obtain the number of products in each category. Then, perform two sub-aggregation operations to obtain the maximum and minimum product prices in each category.

    • Sample result

      • Fruits: 5. The maximum price is CNY 15. The minimum price is CNY 3.

      • Toiletries: 10. The maximum price is CNY 98. The minimum price is CNY 1.

      • Electronic devices: 3. The maximum price is CNY 8,699. The minimum price is CNY 2,300.

      • Other products: 15. The maximum price is CNY 1,000. The minimum price is CNY 80.

  • Example

    /// <summary>
    /// Group by field value. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void GroupByField(OTSClient otsClient)
    {
        GroupByField groupByField = new GroupByField
        {
            GroupByName = "GroupBy_Field",
            FieldName = "pk0",
            GroupBySorters = new List<GroupBySorter>{
                new GroupBySorter()
                {
                    RowCountSort = new RowCountSort{ Order = SortOrder.DESC }
                },
                new GroupBySorter()
                {
                    GroupKeySort = new GroupKeySort{ Order = SortOrder.DESC }
                }
            }
        };
    
        MatchAllQuery matchAllQuery = new MatchAllQuery();
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.GroupByList = new List<IGroupBy> { groupByField };
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
    }

Group by range

The aggregation method that can be used to group query results based on the value ranges of a field. Field values that are within a specified range are grouped together. The number of values in each range is returned.

  • Parameters

    Parameter

    Description

    GroupByName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG and DOUBLE types are supported.

    Range[double_from, double_to)

    The value ranges for grouping.

    The value range can start from double.MinValue and end with double.MaxValue.

    SubAggregation and SubGroupBy

    The sub-aggregation operation. You can perform the sub-aggregation operation based on the grouping results.

    For example, after you group query results by sales volume and by province, you can obtain the province that has the largest proportion of sales volume in a specified range. You must specify a value for GroupByField in GroupByRange to perform this query.

  • Example

    /// <summary>
    /// Query by range. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void GroupByRange(OTSClient otsClient)
    {
        GroupByRange groupByRange = new GroupByRange();
        groupByRange.GroupByName = "GroupBy_Range";
        groupByRange.FieldName = "pk1";
        groupByRange.Ranges = new List<Range>
        {
            new Range(double.MinValue, 5.0),
            new Range(5.0, 50.0),
            new Range(50.0, 100.0),
            new Range(100.0, double.MaxValue)
        };
    
        MatchAllQuery matchAllQuery = new MatchAllQuery();
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.GroupByList = new List<IGroupBy> { groupByRange };
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
    }

Group by geographical location

The aggregation method that can be used to group query results based on geographical locations to a central point. Query results in distances that are within a specified range are grouped together. The number of items in each range is returned.

  • Parameters

    Parameter

    Description

    GroupByName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used for the aggregation operation. Only the GEOPOINT type is supported.

    Origin(double latitude, double longitude)

    The longitude and latitude of the central point.

    latitude specifies the latitude of the central point. longitude specifies the longitude of the central point.

    Range[double_from, double_to)

    The distance ranges that are used for grouping. Unit: meters.

    The value range can start from double.MinValue and end with double.MaxValue.

    SubAggregation and SubGroupBy

    The sub-aggregation operation. You can perform the sub-aggregation operation based on the grouping results.

  • Example

    /// <summary>
    /// Group by geographical location. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void GroupByGeoDistance(OTSClient otsClient)
    {
        GroupByGeoDistance groupByGeoDistance = new GroupByGeoDistance
        {
            GroupByName = "GroupBy_GeoDistance",
            FieldName = "geo_col",
            Origin = new GeoPoint(0, 0),
            Ranges = new List<Range>
            {
                new Range(double.MinValue , 1000.0),
                new Range(1000.0, 5000.0),
                new Range(5000.0, double.MaxValue)
            }
        };
    
        MatchAllQuery matchAllQuery = new MatchAllQuery();
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.GroupByList = new List<IGroupBy> { groupByGeoDistance };
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
    }

Group by filter

The aggregation method that can be used to filter the query results and group them together to obtain the number of results that match each filter. Results are returned in the order in which the filters are specified.

  • Parameters

    Parameter

    Description

    GroupByName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    Filters

    The filters that can be used for the query. Results are returned in the order in which the filters are specified.

    SubAggregation and SubGroupBy

    The sub-aggregation operation. You can perform the sub-aggregation operation based on the grouping results.

  • Example

    /// <summary>
    /// Group by filter. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void GroupByFilter(OTSClient otsClient)
    {
        GroupByFilter groupByFilter = new GroupByFilter
        {
            GroupByName = "GroupBy_Filter",
            Filters = new List<IQuery>
            {
                new RangeQuery
                {
                    FieldName = "pk1",
                    From = new ColumnValue(0.0),
                    To = new ColumnValue(5.0)
                },
            }
        };
    
        TermsQuery termsQuery = new TermsQuery();
        termsQuery.FieldName = "pk0";
        termsQuery.Terms = new List<ColumnValue>
        {
            new ColumnValue("Tablestore SearchIndex"),
            new ColumnValue("SearchIndex")
        };
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.GroupByList = new List<IGroupBy> { groupByFilter };
        searchQuery.Query = termsQuery;
        searchQuery.Limit = 0;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
    }

Query by histogram

The aggregation method that can be used to group query results based on specific data intervals. Field values that are within the same range are grouped together. The value range of each group and the number of values in each group are returned.

  • Parameters

    Parameter

    Description

    GroupByName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    FieldName

    The name of the field that is used to perform the aggregation operation. Only the LONG and DOUBLE types are supported.

    Interval

    The data interval that is used to obtain aggregation results.

    FieldRange[min,max]

    The range that is used together with the interval parameter to limit the number of groups. The value that is calculated by using the (FieldRange.max-FieldRange.min)/interval formula cannot exceed 2,000.

    MinDocCount

    The minimum number of rows. If the number of rows in a group is less than the minimum number of rows, the aggregation results for the group are not returned.

    Missing

    The default value for the field that is used to perform the aggregation operation on a row when the field value is empty.

    • If you do not specify a value for Missing, the row is ignored.

    • If you specify a value for Missing, the value of this parameter is used as the field value of the row.

  • Example

    /// <summary>
    /// Query by histogram. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void HistogramAggregation(OTSClient otsClient)
    {
        GroupByHistogram groupByHistogram = new GroupByHistogram();
        groupByHistogram.GroupByName = "GroupBy_Histogram";
        groupByHistogram.FieldName = "pk1";
        groupByHistogram.Interval = new ColumnValue(5);
        groupByHistogram.Missing = new ColumnValue(100);
        groupByHistogram.FieldRange = new FieldRange(new ColumnValue(0), new ColumnValue(1000));
    
        MatchAllQuery matchAllQuery = new MatchAllQuery(); ;
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
        searchQuery.GroupByList = new List<IGroupBy>
        {
            groupByHistogram
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        foreach (GroupByHistogramResultItem item in searchResponse.GroupByResults.GetAsGroupByHistogramResult("GroupBy_Histogram").GroupByHistogramResultItems)
        {
            Console.WriteLine(JsonConvert.SerializeObject(item));
        }
    }

Query the rows that are obtained from the results of an aggregation operation in each group

After you group query results, you can query the rows in each group. This method can be used in a similar manner as ANY_VALUE(field) in MySQL.

Note When you query the rows that are obtained from the results of an aggregation operation in each group, the returned results contain only the primary key information if the search index contains the NESTED, GEOPOINT, or ARRAY field. To obtain the required field, you must query the data table.
  • Parameters

    Parameter

    Description

    AggName

    The unique name of the aggregation operation. You can query the results of a specific aggregation operation based on this name.

    Limit

    The maximum number of rows that can be returned for each group. By default, only one row of data is returned.

    Sort

    The sorting method that is used to sort data in groups.

    ColumnsToGet

    The fields that you want to return. Only fields in search indexes are supported. ARRAY, DATE, GEOPOINT, and NESTED fields are not supported.

    The value of this parameter is the same as the value of columnsToGet in SearchRequest. You need to only specify columnsToGet in SearchRequest.

  • Example

    /// <summary>
    /// Query the rows that are obtained from the results of an aggregation operation in each group. 
    /// </summary>
    /// <param name="otsClient"></param>
    public static void TopRowsAggregation(OTSClient otsClient)
    {
        GroupByField groupByField = new GroupByField();
        groupByField.GroupByName = "GroupBy_Field";
        groupByField.FieldName = "pk0";
        groupByField.SubAggregations = new List<IAggregation>
        {
            new TopRowsAggregation
            {
                AggName = "TopRows_Agg",
                Sort = new Sort(new List<ISorter> { new FieldSort("pk1", SortOrder.DESC) }),
                Limit = 2
            }
        };
    
        MatchAllQuery matchAllQuery = new MatchAllQuery(); ;
    
        SearchQuery searchQuery = new SearchQuery();
        searchQuery.Query = matchAllQuery;
        searchQuery.Limit = 0;
        searchQuery.GroupByList = new List<IGroupBy>
        {
            groupByField
        };
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        SearchResponse searchResponse = otsClient.Search(searchRequest);
    
        foreach (GroupByFieldResultItem item in searchResponse.GroupByResults.GetAsGroupByFieldResult("GroupBy_Field").GroupByFieldResultItems)
        {
            foreach (Row row in item.SubAggregationResults.GetAsTopRowsAggregationResult("TopRows_Agg").Rows)
            {
                Console.WriteLine(JsonConvert.SerializeObject(row));
            }
        }
    }

Nesting

GroupBy supports nesting. You can perform sub-aggregation operations by using GroupBy.

You can use nesting to perform sub-aggregation operations in a group. For example, you can perform nesting aggregation operations up to two levels.

  • GroupBy + SubGroupBy: Items are grouped by province and by city to obtain data for each city in each province.

  • GroupBy + SubAggregation: Items are grouped by province and the maximum value of a metric is calculated to obtain the maximum value of a metric for each province.

Note To ensure high performance of queries and perform GroupBy operations, you can specify only a small number of levels for nesting. For information, see Search index limits.
/// <summary>
/// Nesting. 
/// </summary>
/// <param name="otsClient"></param>
public static void SubGroupBy(OTSClient otsClient)
{
    GroupByField groupByField = new GroupByField();
    groupByField.GroupByName = "Field_GroupBy";
    groupByField.FieldName = "pk0";
    groupByField.SubGroupBys = new List<IGroupBy>
    {
        new GroupByRange
        {
            GroupByName = "Range_GroupBy",
            FieldName = "pk1",
            Ranges = new List<Range>
            {
                new Range(double.MinValue, 5),
                new Range(5,100),
                new Range(100, double.MaxValue)
            }

        }
    };

    MatchAllQuery matchAllQuery = new MatchAllQuery();

    SearchQuery searchQuery = new SearchQuery();
    searchQuery.GroupByList = new List<IGroupBy>
    {
        groupByField
    };
    searchQuery.GetTotalCount = true;
    searchQuery.Limit = 0;
    searchQuery.Query = matchAllQuery;

    SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);

    SearchResponse searchResponse = otsClient.Search(searchRequest);

    foreach (GroupByFieldResultItem item in searchResponse.GroupByResults.GetAsGroupByFieldResult("Field_GroupBy").GroupByFieldResultItems)
    {
        Console.WriteLine(JsonConvert.SerializeObject(item.SubGroupByResults.GetAsGroupByRangeResult("Range_GroupBy")));
    }
}

Multiple aggregations

You can perform multiple aggregation operations.

Note

If you perform multiple complex aggregation operations at the same time, a long period of time may be required.

/// <summary>
/// Multiple aggregations. 
/// </summary>
/// <param name="otsClient"></param>
public static void MultipleAggregation(OTSClient otsClient)
{
    MaxAggregation maxAggregation = new MaxAggregation();
    maxAggregation.AggName = "Max_Agg";
    maxAggregation.FieldName = "pk1";

    MinAggregation minAggregation = new MinAggregation();
    minAggregation.AggName = "Min_Agg";
    minAggregation.FieldName = "pk1";

    SumAggregation sumAggregation = new SumAggregation();
    sumAggregation.AggName = "Sum_Agg";
    sumAggregation.FieldName = "pk1";

    SearchQuery searchQuery = new SearchQuery();
    searchQuery.Limit = 0;
    searchQuery.Query = new MatchAllQuery();
    searchQuery.AggregationList = new List<IAggregation>
    {
        maxAggregation,
        minAggregation,
        sumAggregation
    };

    SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);

    SearchResponse searchResponse = otsClient.Search(searchRequest);

    Console.WriteLine(JsonConvert.SerializeObject(searchResponse));
}