数值字段必须同时设置这两个参数 - 如何解决此 Elasticsearch 异常

适用版本： 5.x-8.x

1. 错误异常的基本描述 #

both [scale] and [origin] must be set for numeric fields 是 Elasticsearch 在使用**衰减函数（Decay Function）**查询数值类型字段时抛出的参数校验异常。该错误表明：在构造 gauss、exp 或 linear 衰减函数时，针对数值字段未同时提供 scale 和 origin 两个必填参数，导致查询解析阶段即失败。

衰减函数常用于基于地理位置、时间或数值的评分衰减场景，例如：优先展示距离用户最近的商品、发布时间越近的内容排名越靠前等。当参数配置不完整时，Elasticsearch 会在查询解析阶段直接拒绝请求。

常见现象 #

• 查询请求返回 HTTP 400（Bad Request），异常类型为 illegal_argument_exception 或 search_phase_execution_exception。

• Elasticsearch 服务端日志中出现如下异常信息：

  ElasticsearchParseException: both [scale] and [origin] must be set for numeric fields.
  

• 应用侧表现为搜索结果异常、评分不符合预期，或查询直接失败导致页面空白/报错。

• 若该类查询通过脚本或模板动态生成，可能在参数缺失时间歇性触发，增加排查难度。

典型报错与异常栈 #

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "both [scale] and [origin] must be set for numeric fields."
      }
    ],
    "type": "search_phase_execution_exception",
    "reason": "all shards failed",
    "failed_shards": [...]
  },
  "status": 400
}

服务端日志中的调用栈通常如下：

ElasticsearchParseException: both [scale] and [origin] must be set for numeric fields.
  at org.elasticsearch.index.query.functionscore.decay.DecayFunctionBuilder.parseDecayFunction(DecayFunctionBuilder.java:...)
  at org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder$Parsed.parse(FunctionScoreQueryBuilder.java:...)

2. 为什么会发生这个错误 #

衰减函数通过 origin（原点）、scale（衰减尺度）、offset（偏移量）和 decay（衰减率）四个参数来控制评分衰减曲线。其中：

对于数值类型字段，origin 和 scale 必须同时显式设置，原因有二：

1. 数值字段无隐式原点：与地理位置字段（默认原点为当前位置）不同，数值字段无法推断合理的默认值，必须显式指定。
2. 衰减曲线无法计算：缺少任一参数，衰减函数无法构建有效的评分公式，Elasticsearch 选择在解析阶段快速失败，避免返回错误评分。

常见触发场景 #

• 动态生成查询参数时遗漏：通过代码或模板拼接衰减函数参数，未正确处理数值字段的必填参数。
• 从地理衰减函数直接复制配置：地理位置衰减函数允许只设置 origin，但数值字段不支持这种简写。
• 字段类型变更后未同步更新查询：字段从 geo_point 改为数值类型后，原有衰减函数配置不再兼容。
• 使用函数评分（function_score）查询时参数不完整：手动编写复杂 function_score DSL 时遗漏必填字段。

3. 如何排查这个异常 #

建议按以下步骤定位问题：

第一步：获取完整报错上下文 #

从 Elasticsearch 响应或日志中提取完整的错误信息和调用栈，确认异常类型为 ElasticsearchParseException 且原因包含 both [scale] and [origin] must be set for numeric fields。

第二步：定位触发异常的查询 DSL #

1. 在 Elasticsearch 日志中查找与报错时间对应的查询请求体。
2. 若使用 INFINI Gateway 或类似代理，可直接从请求日志中查看完整 DSL。
3. 将查询 DSL 提取出来，在开发/测试环境中用 _search API 单独复现。

第三步：检查衰减函数参数配置 #

重点检查 function_score 查询中所有 gauss、exp、linear 函数，确认数值字段是否同时设置了 origin 和 scale：

{
  "function_score": {
    "query": { "match_all": {} },
    "functions": [
      {
        "gauss": {
          "price": {
            "origin": 100,
            "scale": 50
          }
        }
      }
    ]
  }
}

排查时需要注意的问题 #

• 多函数场景：function_score 中可能包含多个衰减函数，需逐一检查，不能只关注第一个。
• 动态字段名：若字段名通过变量注入，需确认实际运行时字段类型是否为数值类型。
• 嵌套衰减函数：衰减函数可能嵌套在 bool 查询的 should/must 子句中，需递归检查完整查询树。

4. 如何解决这个错误 #

方案一：补充缺失的必填参数 #

对数值字段的衰减函数，确保 origin 和 scale 同时设置：

{
  "function_score": {
    "query": { "match_all": {} },
    "functions": [
      {
        "gauss": {
          "price": {
            "origin": 100,
            "scale": 50,
            "offset": 10,
            "decay": 0.5
          }
        }
      }
    ]
  }
}

注意：origin 和 scale 的单位须与字段类型一致。例如 price 字段为整型，origin: 100 和 scale: 50 表示以 100 为原点，距离 50 以内的文档评分开始衰减。

方案二：根据字段类型选择正确的衰减参数策略 #

方案三：使用默认值兜底（推荐在代码中实现） #

若查询参数由代码动态生成，建议在构建 DSL 时增加参数校验逻辑：

// 伪代码示例
if (fieldType == NUMERIC || fieldType == DATE) {
    if (origin == null || scale == null) {
        throw new IllegalArgumentException(
            "数值/日期字段的衰减函数必须同时设置 origin 和 scale"
        );
    }
}

方案四：通过 INFINI Gateway 拦截并修正异常查询 #

若无法立即修改应用代码，可通过 INFINI Gateway 的请求改写功能，在网关层对不完整的衰减函数参数进行补全或拒绝，避免异常查询到达 Elasticsearch 集群。

后续注意事项与推荐建议 #

• 建立查询 DSL 的代码审查机制：包含 function_score 的复杂查询应经过 review，重点检查衰减函数的参数完整性。
• 为动态查询增加单元测试：覆盖数值字段、日期字段、地理字段三种场景的衰减函数参数组合。
• 在开发环境开启慢查询日志：帮助提前发现参数不完整导致的异常查询。
• 使用 INFINI Console 监控异常趋势：通过 INFINI Console 查看集群错误分布，快速定位是否存在同类问题反复出现。

5. 小结 #

both [scale] and [origin] must be set for numeric fields 是一个典型的参数校验类异常，根源在于衰减函数对数值字段的 origin 和 scale 参数有强制要求。解决该问题的关键是：在构造 function_score 查询时，针对数值类型字段始终同时提供这两个参数，并通过代码校验或网关层拦截防止不完整的 DSL 到达 Elasticsearch。

只要建立规范的查询构建流程和参数校验机制，这类异常完全可以在开发和测试阶段被发现和修复，避免流入生产环境。

相关错误 #

• unknown-vector-index-options-type-type-for-field-fieldname：未知的向量索引选项类型
• unsupported-field-fieldname：不支持的字段名
• wrong-value-for-termvector-termvector-for-field-fieldname：termvector字段值错误
• unknown-property-fieldname：未知属性字段
• unknown-string-property-fieldname：未知字符串属性

附：源码上下文 #

以下是触发该异常的 Elasticsearch 源码片段，便于理解校验逻辑：

if (scaleFound == false || refFound == false) {
    throw new ElasticsearchParseException(
        "both [{}] and [{}] must be set for numeric fields.",
        DecayFunctionBuilder.SCALE,
        DecayFunctionBuilder.ORIGIN
    );
}