搜云库技术团队
文章永久连接：https://tech.souyunku.com/?p=2262
上一章节我们有提到 Elasticsearch 的 RESTful API 使用 HTTP 作为传输协议，使用 JSON 作为数据交换格式。但是，在 API 细节方面，Elasticsearch 还有一些简单的约定。
当然了，我们也可以说是 API 接口规范
API
API，是 Application Programming Interface 的简写，中文译为 应用程序编程接口。
API 是对一组函数调用或用于访问特定 Web 应用程序中的软件组件的其他编程指令，例如，微博 ( Weibo ) API 可帮助开发人员通过访问来自 微博 的数据或其它功能来创建应用程序，比如实现使用微博账号登录
因为 Elasticsearch 的 RESTful API 使用 HTTP 作为传输协议，使用 JSON 作为数据交换格式，所以它对如何使用 HTTP 发起请求和返回响应，如何使用 JSON 制定了一些规范
多个索引
有些时候，我们可能需要一次访问 API 的过程中在多个位置或所有可用数据中进行搜索，这时候就可能用到一个或多个索引。
Elasticsearch RESTful API 中的大部分操作 ( 主要是搜索 ) ，都适用于一个或多个索引的情况
Elasticsearch 提供了有许多不同的符号用于执行多个索引中的操作
逗号分隔符 ( , )
逗号分隔符用于分隔不同的索引
范例
下面发起的请求用于在 index1 ，index2 ，index3 索引中查询所有包含 any_string 数据
POST http://localhost:9200/index1,index2,index3/_search?pretty
请求正文
{
"query":{
"query_string":{
"query":"any_string"
}
}
}
_all 关键字用于所有的索引
如果要在所有的索引中查询，则可以使用 _all 关键字
范例
下面发起的请求用于查询当前服务器上所有索引中包含 any_string 的数据
POST http://localhost:9200/_all/_search?pretty
请求正文
{
"query":{
"query_string":{
"query":"any_string"
}
}
}
通配符 * , + , –
通配符 * , + , – 可以单独使用，也可以组合使用
1、通配符 * 用于匹配任意字符串
例如下面的请求在所有以 user 开头的索引中查找包含 ABCD 的数据
POST http://localhost:9200/user*/_search?pretty
请求正文
{
"query":{
"query_string":{
"query":"ABCD"
}
}
}
返回结果如下
{
"took": 29,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 0,
"max_score": null,
"hits": []
}
}
2、通配符 * 用于排除某些索引
例如下面的请求在所有以 user 开头但不包括 user_admin 的索引中查找包含 ABCD 的数据
POST http://localhost:9200/user*,-user_admin/_search?pretty
请求正文
{
"query":{
"query_string":{
"query":"ABCD"
}
}
}
返回结果如下
{
"took": 28,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 0,
"max_score": null,
"hits": []
}
}
除了上面说的这些符号，Elasticsearch 还提供了一些 URI 查询字符串用于指定某些条件
1、ignore_unavailable
如果 URL 中指定的一个或多个索引不存在，则不会抛出错误且不会停止操作，例如存在 user 索引但不存在 php 的索引的情况
POST http://localhost:9200/user*,php/_search
请求正文
{
"query":{
"query_string":{
"query":"CBSE"
}
}
}
因为没有添加 ignore_unavailable 参数，所以抛出了错误
{
"error": {
"root_cause": [
{
"type": "index_not_found_exception",
"reason": "no such index",
"resource.type": "index_or_alias",
"resource.id": "php",
"index_uuid": "_na_",
"index": "php"
}
],
"type": "index_not_found_exception",
"reason": "no such index",
"resource.type": "index_or_alias",
"resource.id": "php",
"index_uuid": "_na_",
"index": "php"
},
"status": 404
}
但如果使用下面的请求
POST http://localhost:9200/user*,php/_search?ignore_unavailable=true&pretty
请求正文
{
"query":{
"query_string":{
"query":"CBSE"
}
}
}
则不会抛出任何错误
{
"took": 164,
"timed_out": false,
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 0,
"max_score": null,
"hits": []
}
}
2、allow_no_indices
如果一个通配符没有任何匹配的索引存在，如果设置 allow_no_indices 为 true ，则可以阻止抛出错误
例如，假如 Elasticsearch 集群中不存在 PHP* 的索引，那么下面的查询请求将不会报错
POST http://localhost:9200/PHP*/_search?allow_no_indices=true&pretty
请求正文
{
"query":{
"match_all":{}
}
}
返回响应 ( 没有报错 )
{
"took": 0,
"timed_out": false,
"_shards": {
"total": 0,
"successful": 0,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 0,
"max_score": 0,
"hits": []
}
}
3、expand_wildcards
expand_wildcards 用于设置是否需要扩展通配符以打开索引或封闭索引或两者
该参数的指可以是
| 值 | 说明 |
|---|---|
| open | 打开索引 |
| close | 关闭索引 |
| none | 未定义，使用系统默认 |
| all | 全部打开 |
例如我们先使用下面的请求关闭索引 user
POST http://localhost:9200/user/_close?pretty
返回响应
{
"acknowledged": true
}
然后使用下面的请求来查询
POST http://localhost:9200/user*/_search?expand_wildcards=closed
请求正文
{
"query":{
"match_all":{}
}
}
返回响应如下
{
"error": {
"root_cause": [
{
"type": "index_closed_exception",
"reason": "closed",
"index_uuid": "VYLD0ybxRLeVB_KsJ8ZjDw",
"index": "user"
}
],
"type": "index_closed_exception",
"reason": "closed",
"index_uuid": "VYLD0ybxRLeVB_KsJ8ZjDw",
"index": "user"
},
"status": 400
}
索引名称中的日期数学运算支持
Elasticsearch 提供了根据日期和时间搜索索引的功能
当然，我们需要使用特定的日期和时间格式，例如，accountdetail-2015.12.30 索引用于存储 2015 年 12 月 30 日的银行账户详细信息
Elasticsearch 还允许执行数学运算以获取特定日期或日期和时间范围的详细信息
例如下面的语句用于格式化索引中的日期
<static_name{date_math_expr{date_format|time_zone}}>
http://localhost:9200/<accountdetail-{now-2d{YYYY.MM.dd|utc}}>/_search
| 参数 | 说明 |
|---|---|
| static_name | 是表达式的一部分，它在每个包含了日期的索引 ( 如帐户详细信息 ) 中保持不变 |
| date_math_expr | 动态地确定日期和时间的数学表达式，如 now-2d |
| date_format | 生成的日期的格式，如 YYYY.MM.dd例如今天的日期是 2018 年 6 月 27 日，那么 <accountdetail-{now-2d{YYYY.MM.dd}}> 将返回 accountdetail-2018.06.25 |
相关的范例如下
| 表达式 | 结果 |
|---|---|
| <accountdetail-{now-d}> | accountdetail-2018.06.26 |
| <accountdetail-{now-M}> | accountdetail-2018.05.27 |
| <accountdetail-{now{YYYY.MM}}> | accountdetail-2018.06 |
响应参数
接下来我们将介绍一些 Elasticsearch 中常用的用于定制响应的参数
1、pretty=true
通过添加 pretty=true 参数，返回的 JSON 数据将具有良好的格式以方便阅读
例如下面的请求
POST http://localhost:9200/user_admin/_search?pretty=true
请求正文
{
"query":{
"match_all":{}
}
}
返回的响应为
{
"took": 13,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 3,
"max_score": 1,
"hits": [
{
"_index": "user_admin",
"_type": "user",
"_id": "2",
"_score": 1,
"_source": {
"nickname": "雅少",
"description": "虚怀若谷",
"street": "四川大学",
"city": "Chengdu",
"state": "Sichuan",
"zip": "610044",
"location": [
104.094537,
30.640174
],
"money": 68023,
"tags": [
"Python",
"HTML"
],
"vitality": "7.8"
}
},
{
"_index": "user_admin",
"_type": "user",
"_id": "1",
"_score": 1,
"_source": {
"nickname": "站长",
"description": "创业是的天赋是天生的，而我偏偏是后生的",
"street": "东四十条",
"city": "Beijing",
"state": "Beijing",
"zip": "100007",
"location": [
116.432727,
39.937732
],
"money": 5201314,
"tags": [
"PHP",
"Python"
],
"vitality": "9.0"
}
},
{
"_index": "user_admin",
"_type": "user",
"_id": "3",
"_score": 1,
"_source": {
"nickname": "歌者",
"description": "程序设计也是设计，研发新菜也是研发",
"street": "五道口",
"city": "Beijing",
"state": "Beijing",
"zip": "100083",
"location": [
116.346346,
39.999333
],
"money": 71128,
"tags": [
"Java",
"Scala"
],
"vitality": "6.9"
}
}
]
}
}
2、human=true
通过添加 human=true 参数，可以格式化返回结果中的数字，默认值为 false
假如返回的响应存在某个字段 distance_kilometer，保存的值为 20000
- 如果 human=true，那么将返回
distance_kilometer=20KM - 如果 human=false，那么将返回
distance_meter=20000
3、filter_path
该参数用于筛选响应中的字段
例如下面的请求
POST http://localhost:9200/user/_search?filter_path=hits.total
请求正文
{
"query":{
"match_all":{}
}
}
那么返回结果就只会包含下面的内容
{
"hits": {
"total": 3
}
}
干货推荐
附录：Elasticsearch 教程 系列文章
- 一、Elasticsearch 教程： 基础教程
- 二、Elasticsearch 教程： 简介
- 三、Elasticsearch 教程： 安装前准备工作
- 四、Elasticsearch 教程： 安装 ( Windows )
- 五、Elasticsearch 教程： 安装 ( Unix )
- 六、Elasticsearch 教程： 术语
- 七、Elasticsearch 教程： RESTful API
- 八、Elasticsearch 教程： 初体验 – 分词
- 九、Elasticsearch 教程： 中文分词 – 结巴分词
- 十、Elasticsearch 教程： 准备数据
- 十一、Elasticsearch 教程： 填充数据
- 十二、Elasticsearch 教程： API 约定
- 十三、Elasticsearch 教程： 文档 API
- 十四、Elasticsearch 教程： 搜索 API
- 十五、Elasticsearch 教程： 聚合计算
- 十六、Elasticsearch 教程： 索引 API
- 十七、Elasticsearch 教程： 集群管理 API
- 十八、Elasticsearch 教程： 查询描述语言
- 十九、Elasticsearch 教程： 映射 ( Mapping )
- 二十、Elasticsearch 教程： 分析 ( Analysis )
- 二十一、Elasticsearch 教程： 模块 ( Modules )
- 二十二、Elasticsearch 教程： 测试
- 二十三、Elasticsearch 教程： 版本升级
- 二十四、Elasticsearch 教程： 总结
