Percentile Ranks Aggregation 百分位数排名

一种多值度量标准聚合，用于计算从聚合文档中提取的数值的一个或多个百分位数排名。可以从文档中的特定数字字段提取这些值，也可以通过提供的脚本生成这些值。

NOTE 请参阅Percentiles（通常）近似和压缩，以获得关于百分位数排列聚合的近似和记忆使用的建议

百分位数等级显示低于特定值的观测值的百分比。例如，如果值大于或等于观察值的95％，则称其为第95百分位数。

假设您的数据包含网站加载时间。您可能有一个服务协议，95％的页面在500毫秒内完全加载，99％的页面加载在600毫秒内完成。

让我们看一下表示加载时间的百分位数范围：

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs" : {
  5.         "load_time_ranks" : {
  6.             "percentile_ranks" : {
  7.                 "field" : "load_time",   # @1
  8.                 "values" : [500, 600]
  9.             }
  10.         }
  11.     }
  12. }

@1: 字段load_time必须是数字字段

响应将如下所示：

  1. {
  2.     ...
  4.    "aggregations": {
  5.       "load_time_ranks": {
  6.          "values" : {
  7.             "500.0": 55.00000000000001,
  8.             "600.0": 64.0
  9.          }
  10.       }
  11.    }
  12. }

根据这些信息，您可以确定您达到了99％的加载时间目标，但未达到95％的加载时间目标

Keyed Response

默认情况下，keyed标志设置为true将唯一字符串键与每个存储桶相关联，并将范围作为哈希而不是数组返回。将keyed标志设置为false将禁用此行为：

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs": {
  5.         "load_time_ranks": {
  6.             "percentile_ranks": {
  7.                 "field": "load_time",
  8.                 "values": [500, 600],
  9.                 "keyed": false
  10.             }
  11.         }
  12.     }
  13. }

响应：

  1. {
  2.     ...
  4.     "aggregations": {
  5.         "load_time_ranks": {
  6.             "values": [
  7.                 {
  8.                     "key": 500.0,
  9.                     "value": 55.00000000000001
  10.                 },
  11.                 {
  12.                     "key": 600.0,
  13.                     "value": 64.0
  14.                 }
  15.             ]
  16.         }
  17.     }
  18. }

Script

百分等级指标支持脚本。例如，如果我们的加载时间以毫秒为单位但我们想要以秒为单位指定值，我们可以使用脚本即时转换它们：

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs" : {
  5.         "load_time_ranks" : {
  6.             "percentile_ranks" : {
  7.                 "values" : [500, 600],
  8.                 "script" : {
  9.                     "lang": "painless",
  10.                     "source": "doc['load_time'].value / params.timeUnit",   #@1
  11.                     "params" : {
  12.                         "timeUnit" : 1000      #@2
  13.                     }
  14.                 }
  15.             }
  16.         }
  17.     }
  18. }

@1: field参数将替换为script参数，该参数使用脚本生成计算百分位数的值
@2: Scripting支持参数化输入，就像任何其他脚本一样

这将使用 painless 脚本语言并且没有脚本参数将脚本参数解释为内联脚本。要使用存储的脚本，请使用以下语法：

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs" : {
  5.         "load_time_ranks" : {
  6.             "percentile_ranks" : {
  7.                 "values" : [500, 600],
  8.                 "script" : {
  9.                     "id": "my_script",
  10.                     "params": {
  11.                         "field": "load_time"
  12.                     }
  13.                 }
  14.             }
  15.         }
  16.     }
  17. }

HDR Histogram

NOTE 此设置公开HDR直方图的内部实现，语法可能在将来发生变化。

HDR直方图（高动态范围直方图）是一种替代实现，在计算延迟测量的百分位数时非常有用，因为它可以比t-digest实现更快，并且需要更大的内存占用。此实现维护固定的最坏情况百分比错误（指定为有效位数）。这意味着如果数据以1微秒到1小时（3,600,000,000微秒）的值记录在直方图中设置为3位有效数字，则对于高达1毫秒和3.6秒（或更高）的值，它将保持1微秒的值分辨率）最大跟踪值（1小时）。

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

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs" : {
  5.         "load_time_ranks" : {
  6.             "percentile_ranks" : {
  7.                 "field" : "load_time",
  8.                 "values" : [500, 600],
  9.                 "hdr": {    # @1
  10.                   "number_of_significant_value_digits" : 3    #@2
  11.                 }
  12.             }
  13.         }
  14.     }
  15. }

@1: hdr对象表示应使用HDR直方图来计算百分位数，并且可以在对象内指定此算法的特定设置
@2: number_of_significant_value_digits以有效位数指定直方图的值的分辨率

Missing value

缺少的参数定义了应该如何处理缺少值的文档。默认情况下，它们将被忽略，但也可以将它们视为具有值。

  1. GET latency/_search
  2. {
  3.     "size": 0,
  4.     "aggs" : {
  5.         "load_time_ranks" : {
  6.             "percentile_ranks" : {
  7.                 "field" : "load_time",
  8.                 "values" : [500, 600],
  9.                 "missing": 10    #@1
  10.             }
  11.         }
  12.     }
  13. }

@1: load_time字段中没有值的文档将与值为10的文档属于同一个存储桶。