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 编码的。
