Elasticsearch专题精讲——API规范—— 一般表达式
API规范—— 一般表达式
https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html
1、Pretty Results
当任何请求 URL 加 pretty=true 参数时,返回的 JSON 都是格式化的(仅用于调试)。另一个选项是设置 format=yaml,结果以更可读的 yaml 格式返回。
2、Human readable output
统计数据以适合人(例如 "exists_time": "1h" 或 "size": "1KB")和计算机(例如"exists_time_in_millis": 3600000 或 "size_in_bytes": 1024)的格式返回。可以通过添加 human=false 来关闭对人友好可读输出格式。
3、Date Math
表达式以基准日期(相对于一个特定的参考时间)开始,可以是 now,也可以是以 || 结束的日期字符串 。基准日期后面可以有一个或多个日期数学表达式:
-
- + 1h:加一个小时;
- - 1d:减一天。
- /d:近似到天。
时间单位 | 解释 | 时间单位 | 解释 |
y | Years | h | Hours |
M | Months | H | Hours |
w | Weeks | m | Minutes |
d |
Days | s | Seconds |
假如 now 是 2023-05-30 12:00:00,
时间表达式 | 解析结果 |
now+1h | now 加一个小时,解析为:2023-05-30 13:00:00 |
now-1h | now 减一个小时,解析为:2023-05-30 11:00:00 |
now-1h/d | now 减少一个小时,并近似取值UTC 00:00,解析为 2023-05-30 00:00:00 |
2023-05-30\|\|+1M/d | 2023-05-30 减一个月,解析为:2023-04-30 00:00:00 |
4、Response Filtering
所有 REST API 都接受一个 filter_path 参数,该参数可用于减少 Elasticsearch 返回的响应信息。此参数采用逗号分隔的列表形式,如下:
GET /bank/_search?q= * &sort=account_number:acs&pretty&&filter_path=took,hits.hits._id,hits.hits_score
这是一个 Elasticsearch 的查询语句,意思是在 bank 索引中搜索所有文档,并按照 account_number 字段升序排序,��回搜索结果的数量、ID和分数。这里使用了 filter_path 参数,指定只返回 took、hits.hits._id 和 hits.hits._score 三个字段的值。
具体来说,took 表示查询所用时间,hits.hits._id 表示搜索结果文档的 ID,hits.hits._score 表示搜索结果文档的匹配得分。这样可以减少返回结果的数据量,提高查询的效率。
在 Elasticsearch 中,_source 表示文档的原始内容,包含了所有存储在文档中的字段。
默认情况下,在执行搜索操作时,Elasticsearch 会返回文档的全部内容,这可能会导致返回数据过大,网络传输过慢,降低查询性能。为了解决这个问题,Elasticsearch 提供了 filter_path 参数,用于过滤并只返回需要的字段和信息。举个例子,若文档结果如下:
{ "title": "book", "author": "John Doe", "content": "This is a book" }
若希望只返回 title和 author 字段,可以这样设置 filter_path:
GET /my-index/_search?filter_path=hits.hits._source.title,hits.hits._source.author
这样搜索结果中就只包含 title 和 author 两个字段的内容。通过合理设置 filter_path,可以减少 Elasticsearch 返回的数据量,加快检索速度,提高整个搜索系统的效率。
我们来说说 _source,_source 是 Elasticsearch 文档中的一个特殊字段,它存储了文档的完整内容。在默认情况下,当你从 Elasticsearch 中检索一份文档时,它会返回这个文档的 _source 字段,也就是文档的完整内容。
你可以利用 _source 字段来获取文档的具体信息,进而进行相应的操作。比如,你可以通过 _source 字段来更新文档的内容,或者使用它来检索包含特定字段的文档。当然,如果你的文档很大,而你只对其中一部分字段感兴趣,那么你可以使用 source filtering 来仅检索你感兴趣的字段,避免数据传输和计算的开销。
举个例子:
假设我们有一个包含员工信息的 Elasticsearch 索引,其中每个员工文档都包含着许多字段,如姓名、部门、薪资、入职日期等。现在我们想要进行一个查询,找出所有在部门 A 工作的员工。
如果我们只需要返回员工的姓名和部门这两个字段,而不关心薪资和入职日期等敏感数据,我们就可以使用 Elasticsearch 的 source filtering 功能来排除这些字段,以减少响应数据的大小和提高网络传输效率。下面是一个简单的使用示例:
GET employees/_search { "_source": ["name", "department"], "query": { "match": { "department": "A" } } }
上述示例中的 _source
字段指定了我们要返回的字段名列表,查询语句会返回仅包含这些字段的员工文档信息。这样做不仅能够提高查询效率和减少带宽使用,还可以保护敏感数据不暴露给不应该获取它们的用户。
5、Flat Settings
flat_settings 标志会影响设置信息列表(_settings)的呈现。如果 flat_settings 标志位 true,则以平铺格式返回设置,假如我们有一个名为 bank 的 Elasticsearch 索引,我们可以通过以下的命令获取它的设置:
GET bank/_settings?flat_settings=true
请求完成后,Elasticsearch 将返回一个 JSON 格式的响应,其中包含了该索引的所有设置,如下所示:
{ "bank": { "settings": { "index": { "number_of_shards": "5", "number_of_replicas": "1", "routing": { "allocation": { "require": { "box_type": "hot" } } }, "refresh_interval": "1s", "aliases": { "my_bank": {} } } } } }
从响应中可以看到,该 bank
索引设置了 5
个分片、1 个副本,在路由分配中要求 box_type
为 hot
的节点,设置了 1
秒的刷新间隔,还为索引创建了别名 my_bank
。
如果 GET bank/_settings?flat_settings=false
,如果将 flat_settings
设置为 false
,则结果会像这样呈现:
{ "bank": { "settings": { "index.number_of_shards": "5", "index.number_of_replicas": "1", "index.routing.allocation.require.box_type": "hot", "index.refresh_interval": "1s", "index.aliases.my_bank": {} } } }
其中,所有的级别之间都用 .
进行分隔,这是扁平的表达方式。这种格式容易阅读和操作,大多数 Elasticsearch 的 API
都采用这种格式来设置索引配置或者请求结果。如果你更喜欢扁平化的数据格式,可以将 flat_settings
设置为 true
,则会返回扁平化的结果。
6、Boolean Values
https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#_boolean_values
在 Elasticsearch 的 REST API 中,布尔参数通常用来控制某些行为或选项。以下是常见的几个布尔参数:
-
-
true
:表示启用选项或开启某种行为。 -
false
:表示禁用选项或关闭某种行为。 -
yes
:表示启用选项或开启某种行为,与true
同义。 -
no
:表示禁用选项或关闭某种行为,与false
同义。 -
on
:表示启用选项或开启某种行为,与true
同义。 -
off
:表示禁用选项或关闭某种行为,与false
同义。
-
在使用布尔参数时,需要注意其大小写。通常情况下,参数值的大小写会被自动转换为小写形式,因此建议使用小写形式的参数值。另外,有些参数可能没有对应的布尔值,需要根据 API 文档中的说明进行设置。
7、Number Values
https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#_number_values
所有 REST API 都支持以字符串的形式提供数字参数,最常见的数字值参数就是分页参数和排序参数了。
8、Time units
https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#time-units
��当需要制定时间区间,例如对于超时参数时,时间区间必须制定单位,如下:
时间单位 | 解释 | 时间单位 | 解释 |
d | Days | ms | Milliseconds |
h | Hours | micros | Microseconds |
m | Minutes | nanos | Nanoseconds |
s | Seconds |
9、数据单位
每当需要制定数据的字节大小,例如设置缓冲区大小参数时,该值必须指定单位,如 10KB 表示 10 千字节。这些单位是 1024 的幂,所以 1KB 表示 1024 字节。
数据单位 | 解释 | 数据单位 | 解释 |
B | Bytes | GB | Gigabytes |
KB | Kilobytes | TB | Terabytes |
MB | Megabytes | PB | Petabytes |
10、缩略处理
数据中有一个很大,会把它特殊地缩略处理,例如 1000打印成7k。10就是10,1000000打印成1m。
简写 | 解释 | 简写 | 解释 |
k | Kilo | t | Tera |
m | Mega | p | Peta |
g | Giga |
11、Distance Units
https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#distance-units
需要指定距离(如地理距离查询中的距离参数)时,如果未指定,则默认单位为 m。
-
m
(米)km
(千米)mi
(英里)yd
(码)ft
(英尺)in
(英寸)
在 Elasticsearch 的查询中,我们可以使用以上距离单位来衡量两个地理位置之间的距离。例如,我们可以查询距离某个地理位置 10 公里内的所有文档,这个查询可以使用以下语句实现:
GET /my_index/_search { "query": { "bool": { "must": { "match_all": {} }, "filter": { "geo_distance": { "distance": "10km", "location": { "lat": 37.7749, "lon": -122.4194 } } } } } }
12、Fuzziness
https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness
一些查询和 API 支持使用模糊参数(fuzziness)进行不精确的模糊匹配。
在查询 text 或 keyword 字段时,fuzziness 被解释为编辑距离,也就是一个字符串需要更改的字符数,以使其与另一个字符串相同。
Fuzziness参数接受三种值:
- 0,1,2:允许的最大编辑距离(或编辑次数)
- AUTO:根据 term 的长度生成编辑距离。可以选择提供低距离和高距离参数 AUTO: [ Low ] ,[ high ]。如果没有指定,默认值是3和6,等效于 AUTO: 3,6,表示长度:
- 0..2:必须精准匹配。
- 3..5:编辑距离 1。
- >5:编辑距离 2.
AUTO 通常应该是模糊性的首选值。
13、启用堆栈跟踪
https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#common-options-error-options
默认情况下,当请求返回错误时,Elasticsearch 不包括错误的堆栈跟踪。可以通过将 error_trace 参数设置为 true 来启用堆栈跟踪。
例如:默认情况下,将无效的 size 参数发送到 _search API 时:
curl -X POST "localhost:9200/my-index-000001/_search?size=surprise_me&pretty"
响应如下:
{ "error" : { "root_cause" : [ { "type" : "illegal_argument_exception", "reason" : "Failed to parse int parameter [size] with value [surprise_me]" } ], "type" : "illegal_argument_exception", "reason" : "Failed to parse int parameter [size] with value [surprise_me]", "caused_by" : { "type" : "number_format_exception", "reason" : "For input string: \"surprise_me\"" } }, "status" : 400 }
如果设置了 error_trace=true:
curl -X POST "localhost:9200/my-index-000001/_search?size=surprise_me&error_trace=true&pretty"
返回如下:
{ "error": { "root_cause": [ { "type": "illegal_argument_exception", "reason": "Failed to parse int parameter [size] with value [surprise_me]", "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..." } ], "type": "illegal_argument_exception", "reason": "Failed to parse int parameter [size] with value [surprise_me]", "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...", "caused_by": { "type": "number_format_exception", "reason": "For input string: \"surprise_me\"", "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..." } }, "status": 400 }
14、查询字符串中的请求正文
对于不接受非 POST 请求的请求主体的库,可以将请求主体作为 source 查询字符串参数传递。
使用此方法时,还应使用指示源格式的媒体类型值(如 application/json)传递 source_content_type 参数。
15、Content-Type 要求
https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#_content_type_requirements
在请求正文中发送的内容的类型必须使用 Content-Type 头指定。此头的值必须映射到 API 支持的格式之一。
大多数 API 支持 JSON、YAML、CBOR 和 SMILE。批量和多搜索 API 支持 NDJSON、JSON 和 SMILE ,其他类型将导致错误。
此外,使用 source 参数时,必须使用 source_content_type 参数制定内容类型。
Elasticsearch 只支持 UTF-8 编码的 JSON。Elasticsearch 忽略随请求发送的任何其他编码标题。响应也是 UTF-8 编码的。