附录二:支持的白名单

本文为您介绍阿里云Elasticsearch Serverless检索增强型应用(8.17版)支持的集群配置白名单、索引配置白名单、Processors白名单以及Query白名单。

使用说明

为了确保您的业务稳定运行,阿里云Elasticsearch Serverless(简称ES Serverless)服务对应用的资源及用法进行了一定的限制。以下白名单项为目前开放的用法和配置,但部分白名单配置和功能项存在参数范围约束,若超过相应范围,需通过调整服务配额提交工单申请后方可使用。

集群配置白名单

集群配置用于定义和控制整个Elasticsearch集群的行为,从而确保集群的稳定性、性能、安全性和可扩展性。检索增强型应用(8.17版)支持修改的集群配置白名单如下。

说明

阿里云Elasticsearch Serverless以应用形式管理资源,并无集群概念,但您可使用原生Elasticsearch的如下集群级别配置,调整Elasticsearch Serverless的应用参数。此处为了与原生Elasticsearch保持一致,命名为集群配置。更多集群级别相关的配置,可通过GET/_cluster/settings/include_defaults API查看。

配置项

描述

action.destructive_requires_name

用于控制在执行高危操作时,是否需要指定操作的索引名称,防止误操作删除多个索引或大量数据。取值如下:

说明

高危操作包括删除索引、关闭集群、清除缓存等可能会导致数据丢失或集群不可用的操作。

  • true:需要指定索引名称。使用通配符(*)或 _all 进行模糊匹配时会被系统拒绝,例如,DELETE /my_*

  • false(默认值):无需指定索引名称,可执行模糊匹配。

apack.tenant.index_settings.throw_unsupported_setting

用于控制在创建索引或更新索引配置时,若使用了不支持的配置参数,是否报错。取值如下:

  • true:报错,创建索引或更新索引配置操作失败。

  • false(默认值):不报错,系统会忽略不支持的配置参数,继续创建索引或更新索引配置。

action.auto_create_index

用于控制是否支持自动创建索引。取值如下:

  • true(默认值):支持。当数据写入至不存在的索引时,系统会自动创建该索引。

  • false:不支持。当数据写入至不存在的索引时,系统会报错,您需手动创建该索引后,才能写入数据。

索引配置白名单

背景信息

Elasticsearch中,您可将结构相似的文档组织到同一个索引中,便于快速查询和搜索指定内容。索引的MappingSettings则是定义索引行为和结构的核心操作,它们共同决定了数据如何被存储、查询和管理。

  • Mapping:定义索引中文档的结构,即字段的数据类型(例如, textintegerdate 等)和行为(例如,是否分词、是否存储原始值、是否支持排序或聚合等)。

  • Settings:定义索引级别的全局行为和相关约束,控制索引的存储、性能、可用性以及与数据相关的高级规则。相关配置将直接影响数据如何分布、搜索如何执行,以及资源如何分配。

您可参考本文,了解检索增强型应用(8.17版)支持的字段数据类型索引配置白名单。

说明

更多索引的创建及配置,请参见Update index settings API

支持的字段数据类型

字段数据类型(Field Data Types)决定了数据在Elasticsearch的存储和查询方式。检索增强型应用(8.17版)支持的字段数据类型如下。

类别

字段数据类型

描述

数值类型

byte

8位有符号整数,取值为-128~127。用于存储小范围的整数。

short

16位有符号整数,取值为-32,768~32,767。用于存储中等范围的整数。

integer

32位有符号整数,取值为-231~231-1。用于存储通用类型的整数。例如,库存量、订单号。

long

64位有符号整数,取值为-263~263-1。用于存储大量数值的整数(例如,Unix时间戳、IP地址)。

half_float

16位浮点数,精度较低。用于存储较小的浮点值,节省存储空间。

float

32位浮点数,单精度。用于存储较高精度的浮点值。例如,温度、价格。

double

64位浮点数,双精度。用于存储高精度数据。例如,科学计算、金融计算。

scaled_float

进行压缩存储的浮点值,较节省存储空间。

unsigned_long

64位无符号整数,取值为0~264-1。用于存储非负整数。例如,超大ID。

范围类型

integer_range

存储整数范围,包含起始值和结束值,用于整数区间查询。例如,年龄区间。

float_range

存储浮点数范围,包含起始值和结束值,用于浮点数区间查询。例如,包含小数的温度范围、价格区间。

long_range

存储长整数范围,包含起始值和结束值,用于大整数区间查询。例如,查询订单ID在指定区间内的记录。

double_range

存储双精度浮点数范围,包含起始值和结束值,用于高精度的数值区间查询。例如,金融数据中的价格波动范围199.99 ~ 999.99

ip_range

存储IP地址范围,用于IP地址段匹配。例如,屏蔽指定范围的IP地址。

date_range

存储日期范围,包括开始时间和结束时间,用于时间区间查询。例如,活动时间、订单有效期。

子数据类型

说明

用于处理嵌套或复杂结构的数据。

object

存储JSON对象,包含无结构化的嵌套数据。例如,用户配置信息。

nested

可查询的嵌套对象,支持独立索引。用于存储多个独立子对象。例如,产品评论、订单详情。

文本与关键词类型

text

用于全文搜索,支持分词。适用于非结构化内容,例如,商品描述、文章内容。

keyword

用于精确匹配,不进行分词。适用于结构化内容,例如,ID、邮箱地址。

constant_keyword

用于存储索引中值相同的固定值(即所有文档的该字段必须具有相同值)。例如,版本号、环境标识production

match_only_text

适用于全文搜索,但无需存储或高亮显示的搜索场景。该方式能够有效节省存储空间,提升搜索性能。

日期与时间类型

date

日期时间格式,精确到毫秒。用于存储时间序列数据(例如,日志数据)或事件的日期。

date_nanos

日期时间格式,精确到纳秒。用于存储高精度时间戳,例如,金融交易。

二进制类型

binary

可直接存储原始二进制数据(例如,二进制日志)。

布尔类型

boolean

存储布尔值(truefalse),用于条件过滤、判断开关状态等。

地理位置类型

geo_point

存储地理坐标(即单个点的经纬度),用于位置点查询。例如,商店坐标。

geo_shape

存储复杂几何形状(例如,多边形),用于区域匹配。例如,行政区边界查询。

point

存储地理坐标(即单个点的经纬度),用于位置点查询,常用于关联字段。例如,订单与配送地址关联。

IP与网络类型

ip

用于IPv4IPv6地址的存储与查询。

向量类型

dense_vector

存储密集向量,常用于机器学习。例如,图像向量、文本嵌入。

sparse_vector

存储稀疏向量(仅存储非零值和索引),常用于高维稀疏数据。例如,文本特征。

其他类型

flattened

存储嵌套对象或数组。用于非常规聚合或存储非结构化数据。

wildcard

基于通配符的文本匹配查询,用于在字段中查找符合特定模式的文本。例如, 使用"?at" 匹配 cat 或 hat

shape

存储地理空间几何形状(例如,多边形、线、区域等),用于处理复杂的地理区域范围和空间关系查询。

alias

别名可用于指向一个或多个索引,后续通过一个别名,即可统一查询多个索引的数据。

例如,将log_2025_01log_2025_02等索引的别名设置为all_logs,查询all_logs,即可获取所有相关的日志数据。

version

用于控制文档更新的并发性和数据一致性,常用于冲突检测,避免多个客户端同时修改同一文档所导致的数据覆盖或不一致问题。

search_as_you_type

提供实时搜索建议,当您逐字输入查询词时,系统能立即返回相关的、部分匹配的结果。

semantic_text

通过推理端点自动将文本内容转换为语义向量,并对长文本进行智能分块,支持大规模语料的高效处理。通过将复杂的向量化流程封装为字段级能力,显著降低了构建智能语义搜索应用的技术门槛。

支持的索引配置

检索增强型应用(8.17版)支持的索引配置分为映射限制配置索引通用配置两类,您可按需配置。

映射限制配置

索引映射限制相关的配置项,用于限制字段映射的数量,避免映射字段过多,导致索引性能下降。检索增强型应用(8.17版)支持的映射限制配置如下。

配置项

描述

index.mapping.field_name_length.limit

用于设置字段名的最大长度,防止字段名过长,占用过多内存。

index.mapping.depth.limit

用于设置嵌套字段(即nested类型字段)的最大层级,限制嵌套对象的复杂性,避免内存溢出。默认为20级。

index.mapping.nested_fields.limit

用于设置嵌套字段(即nested类型字段)的最大数量,防止嵌套映射过多,导致查询性能下降。默认为50个。

index.mapping.nested_objects.limit

用于设置单个文档中嵌套对象的最大数量,避免文档包含过多嵌套对象,导致内存不足。默认为10,000个。

index.mapping.total_fields.limit

用于设置索引中的最大字段数,防止字段过多,导致索引膨胀影响查询性能。默认为1,000个。

index.mapping.coerce

是否强制转换输入值的字段类型(例如,将字符串 "123" 转换为数值 123)。取值如下:

  • true:转换,将当前字段的输入值,转换为该字段所定义的类型。

  • false(默认值):不转换,直接以输入值的原始类型存储,若类型不匹配可能会产生报错。

index.mapping.ignore_malformed

是否忽略不符合字段类型的数据,取值如下:

  • true:忽略,即允许插入类型错误的数据,但该数据不会被索引。

  • false(默认值):不忽略,即不允许插入类型错误的数据,且会产生报错,影响其他数据的插入。

索引通用配置

索引通用配置用于定义索引的底层行为和资源分配(例如,分片数量、分词规则等),合理的配置索引有助于提升查询及写入性能、提高资源利用率、高效管理数据。检索增强型应用(8.17版)支持的索引通用配置如下。

类别

配置项

描述

索引核心配置

index.number_of_shards

用于设置索引的主分片数,控制数据分布和并行处理能力。默认为1

index.codec

用于设置使用哪种压缩格式来存储数据。取值如下:

  • default(默认值):中等压缩,适用于需要快速检索且存储空间充足的场景。

  • best_compression:极高压缩,适用于索引读取不频繁或存储受限的场景。

index.refresh_interval

用于设置分片数据从内存刷新到磁盘的时间间隔,可调整写入性能及查询实时性。默认为1s

分析器与管道

index.analysis.*

自定义分析器、分词器、过滤器等,用于控制文本字段的分词规则。

index.default_pipeline

插入文档时默认使用的数据管道,用于系统预处理数据(例如,格式转换、字段计算)。

index.final_pipeline

文档插入后的最终处理管道,用于确保数据符合规范(例如,过滤加密或敏感字段)。

查询与排序

index.query.default_field

定义当所查询的字符串未指定字段时,默认会匹配哪些字段。例如,将查询语句 query: "text" 自动匹配到 content 字段。

index.sort.*

定义文档在分片内的排序规则,用于加速查询(例如,按时间排序)。

索引阻塞

index.blocks.*

限制对某个索引可执行的操作类型(例如,写入、删除、元数据访问),用于维护或调试场景下临时锁定索引。

索引性能

index.max_adjacency_matrix_filters

用于设置邻接矩阵查询的复杂度阈值,防止因条件过多或较复杂,导致内存溢出或性能下降。默认为1,000条。

index.max_docvalue_fields_search

单个搜索请求中最大允许的docvalue_fields数量,用于限制聚合查询的资源消耗。默认为100

说明

docvalue_fields 是一个搜索参数,用于在搜索结果中返回指定字段的原始值。

index.max_inner_result_window

用于设置嵌套查询或聚合中inner_hits的最大结果窗口大小,以限制复杂查询的内存使用。默认为100

说明

inner_hits用于在嵌套查询的上下文中,检索嵌套文档的具体信息。

index.max_ngram_diff

用于设置Ngram分词器中分片长度的最大差值,防止因分词器配置不当导致索引膨胀或性能下降。

index.max_refresh_listeners

用于设置单个索引的最大刷新监听器数量,避免监听器过多,影响刷新性能。

index.max_regex_length

用于设置正则表达式或前缀查询的最大长度,防止相关内容较长,影响查询速度。默认为1,000

index.max_rescore_window

用于设置重评分操作(即通过更复杂的评分模型重新排序结果)的最大文档窗口大小,以限制该过程的资源消耗。默认为10,000

index.max_result_window

用于设置分页查询的最大结果窗口大小,防止高开销的分页查询,例如,from: 100000, size: 10。默认为10,000

index.max_script_fields

用于设置单个搜索请求中脚本字段的最大数量,限制脚本计算的资源消耗。默认为32

index.max_shingle_diff

用于控制Shingle分词器中分片长度的最大差值,防止分词器生成过多组合词。默认为3

index.max_terms_count

用于设置单个查询或聚合中,允许添加的最大条件数,避免条件列表过大导致内存不足,影响性能。默认为65,536

index.max_prefix_length

用于设置前缀查询的最大长度,防止前缀超长,影响查询性能。默认为0,表示无限制。

index.max_wildcard_length

用于设置通配符查询的最大长度,限制通配符查询的复杂度,避免全表扫描。默认为10

Processors白名单

在文档被索引到Elasticsearch之前,您可通过Processor(处理器)对文档内容进行一系列的转换、清洗、丰富或过滤操作。检索增强型应用(8.17版)支持的Ingest Pipelines Processor白名单如下。

Processor类型

Processor

描述

基础数据操作

append

向字段的值(数组)追加一个或多个值。

set

设置字段的值。若字段不存在则创建,存在则覆盖。

remove

删除一个或多个字段。

rename

重命名字段。

drop

丢弃整个文档,不会对其进行索引。

fail

强制终止处理器,中断管道并返回错误。

pipeline

调用另一个Ingest Pipeline。

terminate

立即终止管道执行,后续处理器不再运行。

数据类型转换与格式化

convert

转换字段的数据类型。

bytes

将字节大小字符串(例如, 1kb)转换为字节数(整数)。

date

解析时间字符串并设置为@timestamp或其他字段。

sort

对字段中的数组值进行排序。

字符串与文本处理

trim

去除字符串首尾空格。

split

将字符串按分隔符拆分为数组。

join

将数组合并为字符串。

uppercase

将字符串转为大写。

lowercase

将字符串转为小写。

gsub

使用正则表达式替换字符串中的内容。

urldecode

解码URL编码的字符串。

html_strip

移除HTML标签。

结构化解析

dissect

使用简单的模式匹配提取字段。

grok

使用正则表达式模式解析非结构化文本。

kv

从键值对字符串中提取字段。

json

JSON字符串解析为对象字段。

csv

CSV字符串解析为多个字段。

地理与网络信息处理

geo_grid

将经纬度转换为地理网格,常用于聚合。

ip_location

IP地址解析为地理位置,需集成GeoIP。

network_direction

用于判断网络流量方向。

user_agent

解析User-Agent字符串,提取浏览器、操作系统等信息。

uri_parts

解析URI,提取协议、主机、路径等信息。

数据安全

redact

对字段内容进行脱敏(例如,隐藏手机号中间几位)。

fingerprint

生成字段内容的哈希值,该值唯一,用于去重。

高级处理器

attachment

提取文件附件内容(例如,PDF、Word)中的文本。

circle

将圆形区域(中心点+半径)转换为地理形状,用于地理查询。

community_id

生成网络流的社区ID,用于流量分析。

dot_expand

将点号分隔的字段名展开为嵌套对象。

for_each

对数组中的每个元素执行一组处理器。

脚本及AI处理

script

使用Painless脚本编写复杂逻辑(例如,条件判断、数学运算、动态字段生成)。

说明

自定义脚本需提交工单添加白名单。

inference

调用已部署的机器学习模型(例如,NLP模型)进行推理。

Query白名单

Query Section白名单

检索增强型应用(8.17版)搜索请求体的最外层JSON对象支持的参数如下。

参数

描述

retriever

用于构建检索增强生成(RAG)系统。支持混合检索(关键词 + 向量),简化语义搜索流程。

terminate_after

最大命中数限制。

min_score

最小评分过滤。

_source

控制返回_source字段。

stored_fields

返回存储字段。

query

主查询条件。

post_filter

查询后过滤(不影响聚合)。

knn

向量近似最近邻搜索。

script_fields

返回脚本计算字段。

说明

自定义脚本需提交工单添加白名单。

indices_boost

给不同索引分配权重。

aggs / aggregations

聚合分析。

highlight

高亮匹配内容。

rescore

重打分机制。

slice

索引切片查询。

collapse

将多个重复或相似的查询条件合并、去重。

pit

时间点搜索。

docvalue_fields

返回doc_values字段。

fields

返回指定字段。

search_after

深度分页。

runtime_mappings

定义运行时字段,在查询时动态计算字段值,无需重新索引。常用于日志解析、字段转换、敏感数据脱敏等。

说明

部分type暂不支持,如需使用,请提交工单添加白名单。

Query Type白名单

检索增强型应用(8.17版)支持的查询类型如下。

  • 复合查询(Compound Queries)

    查询类型

    描述

    bool

    组合多个查询子句,支持布尔逻辑(例如,mustshould)。

    boosting

    对满足某个条件的文档降低其评分,但仍然会返回。

    constant_score

    使所有匹配的文档获得相同的评分,常用于过滤场景。

    dis_max

    在多个查询中,取最高评分作为最终评分,避免评分叠加过高。

    function_score

    完全控制文档的评分方式,可结合脚本、随机性等进行评分。

  • 全文查询(Full Text Queries)

    查询类型

    描述

    intervals

    精确控制词的位置和顺序,用于复杂文本模式匹配。

    match

    标准全文搜索,对输入文本进行分词后匹配。

    match_bool_prefix

    匹配前缀,用于自动补全场景。

    match_phrase

    短语匹配,要求词序一致且相邻。

    match_phrase_prefix

    短语匹配 + 最后一个词支持前缀匹配。

    combined_fields

    将多个字段合并为一个虚拟字段进行搜索,提升跨字段相关性。

    multi_match

    在多个字段上执行match查询。

    query_string

    支持复杂查询语法(例如,ANDORNOT+-等)。

    simple_query_string

    简化版query_string,语法更友好、容错更强。

    common

    优化对长文本的搜索,自动区分高频词和低频关键词。

  • 地理空间查询(Geo Queries)

    查询类型

    描述

    geo_distance

    根据一个中心点(经纬度)和一个距离范围,筛选出落在该圆形区域内的地理数据。

  • Shape查询(Shape Queries)

    查询类型

    描述

    shape

    判断文档中的地理形状(例如,多边形、线条)是否与指定的查询形状存在某种空间关系(例如,相交、包含)。

  • 连接查询(Joining Queries)

    查询类型

    描述

    nested

    用于处理嵌套对象(nested objects)的精确匹配。

  • Match All

    查询类型

    描述

    match_all

    查询时会匹配索引中的所有文档。

  • 跨度查询(Span Queries)

    查询类型

    描述

    span_containing

    匹配一个Span查询,并且它需要被另一个Span查询所包含。

    span_first

    匹配某个Span查询,并限制它必须出现在字段的前N个词内。

    span_multi

    使span_term支持模糊匹配,通常会配合wildcardregexpprefix 等使用。

    span_near/span_gap

    匹配多个词,并要求它们在一定距离(例如,允许中间间隔三个词)内出现,可控制顺序。

    span_not

    从一个Span查询结果中排除另一个Span查询的结果。

    span_or

    多个Span查询中,任意一个匹配即可。

    span_term

    匹配一个精确的词,类似term查询,但用于Span查询链中。

    span_within

    匹配一个Span查询,并且它需要完全在另一个Span查询的范围内。

  • 向量查询(Vector Queries)

    查询类型

    描述

    knn

    ES实现密集向量搜索的主要方式。通过计算向量之间的相似度(例如,余弦相似度),找出最接近的k个文档。

    sparse_vector

    用于存储关键词权重,提升计算效率。

    text_expansion

    将查询扩展为稀疏向量,提升召回率。

  • 专用查询(Specialized Queries)

    查询类型

    描述

    distance_feature

    根据某个时间或地理距离,提升符合条件的文档评分。

    script

    允许使用Painless脚本语言编写自定义的布尔逻辑,判断文档是否匹配。

    说明

    自定义脚本需提交工单添加白名单。

    script_score

    script_scorefunction_score的一部分,允许完全自定义文档的_score,用于实现个性化排序。

    说明

    自定义脚本需提交工单添加白名单。

    pinned

    允许手动指定某些文档ID必须出现在搜索结果中,并控制它们的位置。

  • 术语级查询(Term-Level Queries)

    查询类型

    描述

    exists

    匹配包含该字段且字段值非null的文档。

    fuzzy

    匹配拼写相近的term,基于Levenshtein编辑距离。

    ids

    通过_id精确查找文档。

    prefix

    匹配以指定前缀开头的term

    range

    匹配数值、日期、字符串的范围。

    regexp

    使用正则表达式匹配term

    term

    精确匹配一个term,需完全一致,且大小写敏感。

    terms

    匹配字段值在给定列表中的任意一个。

    wildcard

    支持*(任意字符)和?(单个字符)的模糊匹配。

  • 混合检索(Retriever rrf)

    查询类型

    描述

    rank_rrf

    用于在搜索请求中启用RRF(Reciprocal Rank Fusion)融合排序。

Agg Query Type白名单

检索增强型应用(8.17版)支持的聚合查询类型如下。

  • 桶聚合(Bucket Aggregations)

    分类

    查询类型

    描述

    基础类型

    terms

    按字段值分组(例如,状态、地区)。

    multi_terms

    按多个字段组合分组(复合主键)。

    histogram

    按数值区间分组。

    date_histogram

    按时间间隔分组(例如,每小时、每天)。

    auto_date_histogram

    自动选择合适的时间间隔。

    variable_width_histogram

    可变宽直方图,用于处理数据分布不均匀或极端值较多的情况。

    range

    按自定义数值范围分组。

    date_range

    按自定义日期范围分组。

    ip_range

    IP地址段分组。

    ip_prefix

    IP前缀分组。

    地理空间类型

    geo_distance

    按到某点的距离分组(例如,0~1km1~5km)。

    geohash_grid

    Geohash网格分组(经纬度网格)。

    geotile_grid

    Google S2XYZ瓦片网格分组(地图瓦片)。

    geohex_grid

    按六边形网格分组。

    过滤与采样类型

    filter

    创建一个桶,只包含匹配该查询的文档。

    filters

    创建多个桶,每个桶对应一个过滤条件。

    missing

    所有字段缺失的文档归为一个桶。

    sampler

    随机采样一部分文档进行后续聚合。

    diversified_sampler

    采样时确保某个字段值不重复。

    random_sampler

    按样本随机采样。

    嵌套类型

    nested

    进入nested对象内部进行聚合。

    reverse_nested

    nested文档回到根文档上下文。

    children

    在父子关系中,聚合子文档。

    parent

    在父子关系中,从子文档聚合父文档。

    高级分析类型

    significant_terms

    查找显著性高的词。

    significant_text

    对文本字段做显著性分析。

    rare_terms

    查找低频值。

    frequent_item_sets

    查找频繁一起出现的字段组合。

    categorize_text

    自动对非结构化文本分类。

    其他类型

    adjacency_matrix

    构建布尔条件的交叉矩阵,用于调试过滤器。

    aggs/aggregations

    嵌套聚合的语法关键字。

    composite

    维度组合分桶,支持深度分页,用于导出全量数据。

    global

    创建一个全局桶,会忽略所有过滤器。

    time_series

    针对时间序列数据的高效聚合。

  • 指标聚合(Metrics aggregations)

    分类

    查询类型

    描述

    基础统计类型

    avg

    计算平均值。

    sum

    求和。

    min

    最小值。

    max

    最大值。

    value_count

    统计字段值的数量(包括重复值)。

    cardinality

    去重计数(唯一值个数)。

    高级统计类型

    stats

    一次性返回countminmaxavgsum

    extended_stats

    stats基础上增加sum_of_squaresvariancestd_deviation等返回数据。

    percentiles

    计算百分位数。

    percentile_ranks

    给定值对应的百分位等级。

    median_absolute_deviation

    中位数绝对偏差,衡量数据离散程度。

    地理空间类型

    geo_bounds

    计算地理点的边界框。

    geo_centroid

    计算地理点的中心点。

    geo_line

    将地理点按顺序连接成线。

    cartesian_bounds

    笛卡尔坐标的边界框。

    cartesian_centroid

    笛卡尔坐标的中心点。

    数据结构类型

    top_hits

    返回桶内匹配度最高的若干文档。

    top_metrics

    返回某个指标最优时对应的其他字段值。

    boxplot

    返回箱线图所需的五个值minq1medianq3max

    其他类型

    matrix_stats

    计算多个字段之间的统计关系。例如,均值、协方差、相关系数矩阵。

    rate

    计算增长率或速率。

    string_stats

    统计文本字段的长度、字符种类等。

    t_test

    执行t检验,判断两组数据均值是否有显著差异。

    weighted_avg

    加权平均值。