ES官网reference翻译文章(18)—Percentile Ranks Aggregation

对ES官网的reference的翻译，同时也是备忘，ES版本为7.5

下面是正文翻译，附上原文链接：

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-percentile-rank-aggregation.html

==================================================================================================

百分位数排名聚合

多值指标聚合，计算从聚合的文档中提取出来的数值上的一个或多个百分位排名。这些值可以从文档中某些特定的数值字段中提取出来，也可以使用给定的脚本生成。

NOTE：百分位数排名聚合关于近似和内存使用方面的问题可以参考上一篇文章中百分位数聚合的对应章节。

百分位数排名显示观测值中低于特定值的百分比。例如，如果一个数值不小于95%的观测值，那么这个数就被认为位于第95个百分位数排名。（这两句话对应起来看，百分位数排名解决的其实就是这个数值在观测值中不小于百分之多少的其他值的问题）

假设你的数据由网站载入时间组成。你可能有个服务协议声称95%的网页载入时间都在500ms内，99%的网页载入时间在600ms以内。

我们可以看一下代表网站载入时间的百分位数范围(load_time要求是个数值字段)：

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "field": "load_time",
                "values": [500, 600]
            }
        }
    }
}'

返回下面的响应：

{
    ...

   "aggregations": {
      "load_time_ranks": {
         "values" : {
            "500.0": 90.01,
            "600.0": 100.0
         }
      }
   }
}

从上面的信息你可以判断出99%网页载入时间的目标达到了，但95%网站载入时间的目标并未完成。

说一下自己的理解，上面的请求其实是求500ms和600ms的load_time在整个观测值中位于多少百分位数，即有多少观测值不大于500ms和600ms。对比上一篇文章里的百分位数聚合，这两个应该是互逆的，百分位数聚合求的是观测值中第95个百分位数是多少，第99个百分位数是多少；而百分位数排名聚合求的是某个特定的观测值在整个数据集中是第多少个百分位数。

Keyed响应

默认的，keyed标志被设置为true，在这种情况下，每个bucket会跟一个独特的字符串key关联并将范围作为hash而不是array返回。将keyed标志位设置为false会禁止上面的行为：

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "field": "load_time",
                "values": [500, 600],
                "keyed": false
            }
        }
    }
}'

返回下面的响应：

{
    ...

    "aggregations": {
        "load_time_ranks": {
            "values": [
                {
                    "key": 500.0,
                    "value": 90.01
                },
                {
                    "key": 600.0,
                    "value": 100.0
                }
            ]
        }
    }
}

脚本

百分位数排名指标支持使用脚本。例如，如果我们的载入时间的单位是ms但我们想要百分位数的计算单位变成s，我们可以使用脚本来进行单位的转换：

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "values": [500, 600],
                "script": {
                    "lang": "painless",
                    "source": "doc['load_time'].value/params.timeUnit",
                    "params": {
                        "timeUnit": 1000
                    }
                }
            }
        }
    }
}'

与之前的请求体相比，filed参数被script参数替代，script参数使用脚本生成被计算百分位数的观测值，与其他脚本类似，我们也可以给脚本中传入参数。

上面的请求使用的是painless脚本语言编写的无参数的内联脚本，为了使用缓存的脚本，使用下面的请求：

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "values": [500, 600],
                "script": {
                    "id": "my_script",
                    "params": {
                        "field": "load_time"
                    }
                }
            }
        }
    }
}'

HDR直方图

NOTE：这个设置会把HDR直方图的内部实现暴露出来，未来的语法可能会有变化。

HDR直方图（高动态范围直方图）是一种可选的实现，该实现在计算延时测量的百分位数的情况下很有用，因为计算HDR直方图会比tdigest算法要快。HDR直方图实现维护一个固定的最坏情况百分比错误（由有效数字的个数指定）。举个例子，假如数据集包含从1微秒到1小时（3600000000微秒）的数据，HDR直方图被设置为3个有效数字，那么1毫秒的数据会维持1微秒的值分辨率，1小时的数据会维持3.6秒（或者更好）的值分辨率（3个有效数字意味着0.001的百分比错误）。

可以通过在请求中指定method参数使用HDR直方图：

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "field": "load_time",
                "values": [500,600],
                "hdr": {
                    "number_of_significant_value_digits": 3 
                }
            }
        }
    }
}'

hdr参数表明HDR直方图应该被用来计算百分位数，而与HDR直方图算法相关的具体设置可以在hdr中指定。

number_of_significant_value_digits参数以有效数字个数的方式制定了直方图中的值分辨率。

HDR直方图只支持正数，如果传给它负数会报错。在不知道数据集中数值的范围的情况下使用HDR直方图也不是一个好主意，因为这可能导致很高的内存使用。

缺失的值

missing这个参数定义了缺失某个字段的文档应该如何被处理，默认的这些文档会被忽略，但我们也能通过假设它们这个字段有值来处理这些文档。

curl http://host_ip:host_port/latency/_search?pretty
-H 'content-type:application/json'
-d '{
    "size": 0,
    "aggs": {
        "load_time_ranks": {
            "percentile_ranks": {
                "field": "load_time",
                "values": [500,600],
                "missing": 10
            }
        }
    }
}'

load_time字段没有值的文档会落入与load_time=10的文档相同的桶中。