elasticsearch 的 range 查询需严格匹配字段类型和格式，laravel 中须通过 elasticsearch-php 客户端手动构造 dsl；scout 不原生支持，绕过抽象层或确认驱动扩展方可实现，常见问题多源于 mapping 与数据类型不一致。
range 查询是 Elasticsearch 原生支持的范围查询方式，Laravel 本身不内置 ES 客户端，所以“Laravel 中怎么写”实际取决于你用的 ES SDK —— 最常见的是 elasticsearch-php 官方客户端，或封装过的包（如 laravel-scout-elasticsearch）。直接拼 JSON 或调用 SDK 方法都可行，但容易错在字段类型、边界逻辑和时区/格式处理上。
用 elasticsearch-php 客户端写 range 查询
如果你通过 elasticsearch/elasticsearch 包直连 ES，range 查询必须放在 query 下的完整 DSL 结构中。不是 Laravel 的 Eloquent 风格，不能写 where('price', '>', 100) 这类链式调用。
- 必须手动构造
range子句，字段名要和 mapping 里定义的一致（比如price是keyword类型就不能查数值范围） -
gte/lte和gt/lt可混用，例如查「严格大于 100 且小于等于 500」就写{"gt": 100, "lte": 500} - 数值字段不用
format；日期字段必须确认 mapping 中的format，否则"2026-08-13"可能解析失败 - 示例代码片段：
$params = [
'index' => 'products',
'body' => [
'query' => [
'range' => [
'price' => [
'gte' => 100,
'lt' => 500
]
]
]
]
];
$response = $client->search($params);
用 Laravel Scout + elasticsearch-driver 时的 range 写法
Scout 默认不支持原生 range，它只暴露了 where()、whereBetween() 等有限方法，底层会转成 term 或 match，对数值范围无效。想用 range 必须绕过 Scout 的抽象层。
- 不能用
Product::search('')->where('price', '>=', 100)->get()—— 这会报错或查不到结果 - 推荐做法：在模型里加一个静态方法，直接调用
elasticsearch-php客户端，传入原始 DSL - 如果用了
laravel-scout-elasticsearch这类第三方驱动，检查它是否扩展了whereRange()方法；没有就别硬套 Scout 接口 - 注意：Scout 的
whereBetween('price', [100, 500])在多数驱动里只是伪实现，实际可能 fallback 到字符串匹配，不可信
常见错误：数字字段查不出结果
90% 的“range 查询无返回”问题，根源不在语法，而在字段映射（mapping）或数据写入方式。
- 字段被映射为
text或keyword类型 →range查询完全失效，ES 会静默忽略该条件 - 写入时把数字当字符串存了，比如
"price": "299"（带引号）→ 即使 mapping 是long，ES 也可能按字符串解析，导致范围比较异常 - 索引存在多 type（旧版 ES），但查询时没指定 type，或 type 名写错
- 未刷新索引：写入后立即查，需确认
refresh=true或等默认 1s refresh 周期 - 用
filter上下文（如bool.filter）时，range不参与相关性打分，但性能更好；用query上下文才影响_score
日期范围查询要注意 time_zone 和 format
查 created_at 这类日期字段时，range 行为高度依赖 mapping 定义的 format 和集群默认时区。
- 如果 mapping 中
created_at的format是strict_date_optional_time，那么"2026-08-13"会被补全为"2026-08-13T00:00:00.000Z" - 但如果你传
"gte": "2026-08-13"却期望包含当天所有时间，就得显式加"time_zone": "+08:00"，否则 UTC 时间下会漏掉北京时间 00:00–07:59 的文档 - 更稳妥的做法：统一用毫秒时间戳（
"gte": 1723507200000）或 ISO8601 带时区格式（"2026-08-13T00:00:00+08:00"），避免隐式转换 - 别在 PHP 层用
date('Y-m-d')拼字符串再塞进 DSL —— 时区不一致会导致线上环境和本地行为不同
真正卡住人的往往不是语法写不对，而是 mapping 类型和写入数据类型不一致，或者日期字段没配 time_zone 导致跨时区查询偏差。动手前先用 GET /your_index/_mapping 确认字段类型，再用 GET /your_index/_search?q=* 抽几条数据看真实存储格式。
