适用版本： 7.13-7.15
1. 错误异常的基本描述 #
Unicode sequence should use [2-8] hex digits 表示 Elasticsearch 在解析 SQL 查询中的 Unicode 转义序列时，发现十六进制数字位数不在 2-8 范围内。
从源码可见，这个异常在 SQL 字符串解析路径中抛出，当 Unicode 序列 \u{...} 中的十六进制位数少于 2 位或超过 8 位时触发。
典型报错 #
ParsingException: Unicode sequence should use [2-8] hex digits; [\u{1}] has [1]
2. 为什么会发生这个错误 #
- Unicode 位数不足：少于 2 位十六进制数字。
- Unicode 位数过多：超过 8 位十六进制数字。
- 格式错误：Unicode 转义序列格式不正确。
- 缺少闭合括号：Unicode 序列缺少
}闭合。
3. 排查步骤 #
- 检查 Unicode 序列：确认所有
\u{...}序列格式正确。 - 验证十六进制位数：确保位数在 2-8 范围内。
- 检查特殊字符：确认字符串中的特殊字符正确转义。
- 使用 Unicode 验证工具：验证 Unicode 码点有效性。
4. 修复建议 #
方案一：修正 Unicode 位数 #
确保 Unicode 序列有正确的位数：
-- 错误示例
SELECT * FROM test WHERE field = '\u{1}'
-- 正确示例
SELECT * FROM test WHERE field = '\u{01}'
-- 或
SELECT * FROM test WHERE field = '\u{0001}'
方案二：使用正确的 Unicode 格式 #
对于 BMP 字符，可以使用 4 位十六进制：
-- 4 位 Unicode (BMP)
SELECT '\u{0041}' -- A
-- 6 位 Unicode (补充平面)
SELECT '\u{01F600}' -- 😀
方案三：避免不必要的 Unicode 转义 #
如果不需要特殊字符，直接使用普通字符串：
-- 不需要转义时直接使用
SELECT 'Hello World'
5. 小结 #
Unicode sequence should use [2-8] hex digits 通常意味着 SQL 查询中的 Unicode 转义序列格式不正确。排查时应优先检查 Unicode 序列的位数和格式。
相关错误 #
- parsing-exception-how-to-solve-this-elasticsearch-exception
- sql-parsing-exception-how-to-solve-this-elasticsearch-exception
- invalid-sql-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
int startIdx = i + 1;
int endIdx = text.indexOf('}', startIdx);
unicodeSequence = text.substring(startIdx, endIdx);
int length = unicodeSequence.length();
if (length < 2 || length > 8) {
throw new ParsingException(source, "Unicode sequence should use [2-8] hex digits; [{}] has [{}]",
text.substring(startIdx - 3, endIdx + 1), length);
}
sb.append(hexToUnicode(source, unicodeSequence));
return endIdx;
}
