elasticSearch(3) - restfulApi-天翼云

此章内容比较简单，是官方的一个主要API，精选了一些日常开发中需要使用的，罗列一下。本文档介绍的API分为两类：1、resutful；2、sql。建议大家使用restful方式，因为通用性比较好。

一、通用规则

操作原则

索引操作：索引建议只增不改，因为修改过程相当于删除+重索引；
更新数据：这是一个先查询确认文档存在、修改内容、删除旧文档、在原有位置重新索引的过程。ES默认是采用版本号的方式来控制的
删除数据：

删除文档：ES会先标记，再异步物理删除；
删除索引：直接删除整个文件；
关闭索引：类似删除，但会在磁盘上保留文件；

RestfulAPI格式

通用格式：curl -X<VERB> '<PROTOCOL>://<HOST>/<PATH>?<QUERY_STRING>' -d '<BODY>'

VERB HTTP方法: GET , POST , PUT , HEAD , DELETE
PROTOCOL http或者https协议(只有在Elasticsearch前面有https代理的时候可用)
HOST Elasticsearch集群中的任何一个节点的主机名，如果是在本地的节点，那么就叫localhost
PORT Elasticsearch HTTP服务所在的端口，默认为9200
QUERY_STRING 一些可选的查询请求参数，例如 ?pretty 参数将使请求返回更加美观易读的JSON数据 BODY 一个JSON格式的请求主体(如果请求需要的话)

curl -XGET 'http://localhost:9200/_count?pretty' -d ' {
"query": { "match_all": {}
} }

Restful-API可用的查询参数

URL参数名称	用法	body查询时是否支持
q	查询字符串
df	在查询中未定义字段前缀时使用的默认字段
analyzer	分析查询字符串时使用的分析器名称
analyze_wildcard	是否应分析通配符和前缀查询，默认为flase
batched_reduce_size	设置一次查询可查询的最大分片的数量	是
default_operator	要使用的默认运算符，默认为or，可以为and
lenient	格式控制，默认为false，不建议改为true
explain	性能分析，主要对每个结果分析得分情况
_source	是否输出source中内容，默认为true
stored_fields	要返回的文档的存储字段，用逗号分隔，不指定则不返回值
sort	排序，格式为fieldName:desc\|asc，可以有多个
track_sorces	是否计算相关性分数，建议用true
track_total_hits	值可以为false或正整数，当为false时返回值永远为1。当不为false时表示精确命中的文档数，默认值为10000，所以小于等于10000时为精确计数，否则要把此值设置很大。
timeout	默认为无超时，不建议设置	是
terminate_after	查询时每个分片可收集的最大文档数，默认无限制	是
from	默认0，表示结果的偏移量	是
size	默认10，表示结果的数量	是
search_type	可选值有：dfs_query_then_fetch、query_then_fetch（默认值），第一个性能会好一点，但相对的资源占用会比较大	是
allow_partial_search_results	默认为true，表示异常时可以返回部分数据	是
result_cache	是否允许size=0的请求	是

查询结果示例

{
  "_scroll_id": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFEk1bWdRSUFCQWh1VUxxTFZGUDB5AAAAAAAAADMWSi1Jc3M2NnNTbWVkN3dkLVZqVC1sZw==",
  "took": 3, #总耗时
  "timed_out": false, 
  "_shards": { #分片信息
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {  #结果信息
    "total": {
      "value": 1000,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [  #详细数据
      { 
        "_index": "customer",
        "_type": "_doc",
        "_id": "0",
        "_score": null,
        "_source": {
          "account_number": 0,
          "firstname": "Bradshaw"
        },
        "sort": [
          0
        ]
      }
    ]
  }
}

查询参数-格式控制

?v ：带列的详细输出
?help：api帮助
?pretty ：返回结果是格式化后的JSON格式
?format=yaml ：返回结果是格式化后的yaml格式
flat_settings=true：返回结果平铺展开
如果用postman则body设置成raw, json/(application/json)
human=false：关闭可读性，适用于API程序处理
?h=xx,xx：只显示特定的列

元数据过滤

filter_path=took, hits.hits._id：用来过滤不必要的元数据（_source过滤原始数据），表示这这些节点不值不返回，但只用于范围查询语句中，也支持通配符:

*：排除某个字段，比如metadata.indices.*.stat*
-：排除某个字段
**：匹配某个字段

_source=false：不返回source内容，默认开启
字段过滤：可以用_source_includes、_source_excludes，可以使用通配符

CRUD涉及的API都是单索引的，其它的bulk、 multi 、reindex可以跨多个索引执行，多个索引用逗号分隔。也可以使用通配符来匹配索引，比如test*等

get /customer, king/_search?q=tag:wow

ignore_unavailable：是否忽略不可用索引
allow_no_nidices：如果为true时，当找不到索引时请求会失败，防止搜索到索引别名

索引名称快捷

索引名称支持日期解析，但只支持两天内的数据，目的是优化全索引扫描

调试参数

error_trace=true：查看具体错误的语句的地方

日期快捷

now是一个关键字，可用以下来快捷设置时间。

now+1h
now-1h
//其它单位还有y, M, w, d, h, H, m, s，例子
1、now-10M/M  当前时间减去10个月并四舍五入到月初，注意这里/M的意思
2、now/d   四舍五入到一天的开始

二、集群概要信息查看

查看子目录

get http://localhost:9200/_cat  //相当于一个帮助，列出可用的url

集群健康度

get localhost:9200/_cat/health?v  //集群健康度，如果status

green：主副分片全部正常工作；
yellow：副本分片丢失，可以查看unassigned_shards值来确定其严重性；
red：主分片丢失或存在未分配的分片，此时有些数据不可用，需尽快修复；

节点信息

GET localhost:9200/_cat/nodes?v //所有结点
GET localhost:9200/_cat/master?v  //主节点
GET localhost:9200/_cat/recovery?v  //恢复情况
GET localhost:9200/_cat/thread_pool?v //节点线程池

查询别名

http://localhost:9200/_cat/aliases?v

查询分片

http://localhost:9200/_cat/allocation?v
http://localhost:9200/_cat/shards?v

查询分段

http://localhost:9200/_cat/segments?v

三、操作节点

GET localhost:9200/_nodes
GET localhost:9200/_nodes/_all
GET localhost:9200/_nodes/_local
GET localhost:9200/_nodes/_master
GET localhost:9200/_nodes/nodeName //实际的节点名称，可用通配符
GET localhost:9200/_nodes/10.0.0.3,10.0.4
GET localhost:9200/_nodes/10.0.0.*
GET localhost:9200/_nodes/stats
GET localhost:9200/_nodes/nodeid1, nodeid2/stats

四、操作集群

GET localhost:9200/_cluster/health
GET localhost:9200/_cluster/state
GET localhost:9200/_cluster/state?human&pretty //查看统计信息
GET localhost:9200/_cluster/settings  //查看和更新，如果带body就是更新操作

五、操作索引

索引建议只增不改，因为修改过程相当于删除+重索引；

列表

get localhost:9200/_cat/indices?v

创建

有es中创建索引后，不需要再手动创建映射，当填写新字段时在action.auto_create_index=true时则会自动添加新字段到映射定义中，这个设置默认为true，但不建议这么来做。索引名称原则上采用全小写字母，不能包含符号和数字

put localhost:9200/customer?pretty   //创建一个名为customer的索引
或 curl -XPUT "localhost:9200/customer?pretty"
//返回值如下：
{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "index" : "customer"
}

查询索引是否存在

HEAD customer

打开或关闭索引

POST /customer/_close
POST /customer/_open

删除

delete localhost:9200/customer?pretty

查询设置

get localhost:9200/bank/_settings?flat_settings=true

查询集群和索引文档总数

http://localhost:9200/_cat/count?v  //集群文档
http://localhost:9200/_cat/count/customer?v  //单个索引

查询字段内存占用情况

http://localhost:9200/_cat/fieldate?v
http://localhost:9200/_cat/fieldate?v&fields=a

设置索引

put customer 
{"settings":{
    "index":{
        "number_of_shards":3,
        "number_of_replicas":2
    }
 }
}

收缩索引

将现有索引收缩下分片数量，不是很常用。

查看映射

get /king/_mapping/
{
  "king": {
    "mappings": {
      "properties": {
        "address": {
          "type": "text"
        },
        "age": {
          "type": "long"
        },
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}

六、操作文档

创建

//创建时会指定一个id值，可用于查询，如果没有指定则会随机生成一个,但一定要用post来提交
put localhost:9200/customer/_doc/1?pretty   body = {"name":"John Doe"}
post localhost:9200/customer/_doc/?pretty
//显性的设置分片路由，比如:
post localhost:9200/customer/_doc/?routing=kimchy  body={"user":"kimchy", "age":"man"}

{
    "_index": "customer",
    "_type": "_doc",
    "_id": "1",
    "_version": 2,
    "result": "updated",
    "_shards": {
        "total": 2,  #索引应该在多少个分片上执行
        "successful": 1, #实际操作成功执行的分片数
        "failed": 0
    },
    "_seq_no": 1000,
    "_primary_term": 2
}

更新

文档在Elasticsearch中是不可变的——我们不能修改他们，它其实是先创建再删除的过程，过程如下：1. 从旧文档中检索JSON 2. 修改它 3. 删除旧文档 4. 索引新文档

post localhost:9200/customer/_doc/1?pretty  body = {"doc":{"name":"jack ld"}}

添加字段

post localhost:9200/customer/_doc/1?pretty  body = {"doc":{"name":"jack ld", "age":20}}

查询byId

//这里的id是上面的例子中生成的
get localhost:9200/customer/_doc/1?pretty
//显性的设置分片路由，性能会比较快，比如:
get localhost:9200/customer/_doc/1?routing=kimchy

删除

不会立刻删除，只是把需要删除的文档的ID记录到了一个列表中，当段合并时才会真正把源文件删除。

delete localhost:9200/customer/_doc/2?pretty

列表查询

get localhost:9200/bank/_search?q=*&sort=account_number:asc/1?pretty
bank：索引名称
q=*：指匹配所有文档
sort=account_number:asc：排序

{
    "took": 16, #总执行时间ms
    "timed_out": false, #搜索过程是否超时
    "_shards": {
        "total": 1, #总共搜索了多少分片，以及成功和失败了共多少
        "successful": 1, 
        "skipped": 0,
        "failed": 0
    },
    "hits": {  #实际的搜索结果
        "total": { 
            "value": 1000,   #总共返回1000条，但这个值是个参数值，只有relation=eq时此值才是准确的
            "relation": "eq"
        },
        "max_score": 1,
        "hits": [ #结果数据
            {
                "_index": "bank",
                "_type": "_doc",
                "_id": "1",
                "_score": 1, #查询相似度
                "_source": {
                    "account_number": 1,
                    "balance": 39225,
                    "firstname": "Amber",
                    "lastname": "Duke",
                    "age": 32,
                    "gender": "M",
                    "address": "880 Holmes Lane",
                    "employer": "Pyrami",
                    "email": "amberduke@pyrami.com",
                    "city": "Brogan",
                    "state": "IL"
                }
            }
        ]
    }
}

查询数据分片归属

GET /_search_shards
GET /_search_shards?routing=liudong //查询某个索引在哪个分片上
{
  "nodes": {
    "J-Iss66sSmed7wd-VjT-lg": {
      "name": "5fc8e72b7ef3",
      "ephemeral_id": "wtLSy11WSbWAPtsjYUoELw",
      "transport_address": "172.17.0.2:9300",
      "attributes": {
        "ml.machine_memory": "4125892608",
        "xpack.installed": "true",
        "transform.node": "true",
        "ml.max_open_jobs": "20"
      }
    }
  },
  "indices": {
    "customer": {}
  },
  "shards": [
    [
      {
        "state": "STARTED",
        "primary": true,
        "node": "J-Iss66sSmed7wd-VjT-lg",
        "relocating_node": null,
        "shard": 0,
        "index": "customer",
        "allocation_id": {
          "id": "xotuBCQvR1CGHU-bhjl_Tg"
        }
      }
    ]
  ]
}

七、批量操作

执行过程中整个批量请求会加载到协调结点里，所以一次批量的文档最好在1000~5000个文档之间，大小最好在5M~15M之间。

批量查询（读）

合并多个请求可以避免每个请求单独的网络开销。如果你需要从Elasticsearch中检索多个文档，相对于一个一个的检索，更快的方式是在一个请求中使用multi-get或者 mget API。

GET /_mget 
{
  "docs" : [ 
    {
      "_index" : "website",
      "_type" : "blog",
      "_id" : 2
    }, 
    {
      "_index" : "website",
      "_type" : "pageviews",
      "_id" : 1,
      "_source" : "views"
    } 
  ]
}

GET /website/blog/_mget 
{
   "ids" : [ "2", "1" ] 
}

批量操作(写)

批量操作时，如果不会存在事务性的那种全成功才算成功的操作，它会把成功和失败的结果全部返回，供使用者查询

post localhost:9200/customer/_bulk?pretty
{"index":{"_id":"1"} }
{"name":"john doe"}
{"index":{"_id":"2"} }
{"name":"john doe"}
//数据格式有要求的，必须要换行，而且最后一行也要换行
post localhost:9200/customer/_bulk?pretty
{"update":{"_id":"1"} }
{"doc":{"name":"john doe becoemes jane doe"} }
{"delete":{"_id":"2"} }
//下面的create也可换成index、update、delete，不同的是如果文档已存在则create会报错
post localhost:9200/customer/_bulk?pretty
{ "create" : { "_index" : "customer", "_id" : "3" } }
{ "name" : "Alice" }
{ "create" : { "_index" : "customer", "_id" : "4" } }
{ "name" : "Smith" }

数据结构如下，在索引中会有1000条数据，建立在bank索引上：

"account_number": 1,
"balance": 39225,
"firstname": "Amber",
"lastname": "Duke",
"age": 32,
"gender": "M",
"address": "880 Holmes Lane",
"employer": "Pyrami",
"email": "amberduke@pyrami.com",
"city": "Brogan",
"state": "IL"

八、Query SQL

统计-count

GET /_count
{
  "count": 1000,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

分组-group by

{
     "size": 0,  #设置后不返回具体数据
     "aggs": {
          "group_by_state": {
               "terms": {
                    "field": "state.keyword"  # state是一个字段，keyword是一个关键字
               }
          }
     }
}

terms：相当于count，只有这个在field的字段后要加keyword，其它的聚合函数而不需要

分段分组

"aggs": {
                    "group_by_age": {
                         "range": {
                              "filed": "age",
                              "ranges": [
                                   {
                                        "from": 20,
                                        "to": 30
                                   }
                              ]
                         }
                    }
               }

集合查询-limit

{
     "query": {
          "match_all": {}
     },
     "size": 10 #默认值为10
}

分页查询-limit from

最大不能超为index.max_result_window的值，默认为10000

{
     "query": {
          "match_all": {}
     },
     "from": 2,
     "size": 10
}

字段排序-order by

{
     "query": {
          "match_all": {}
     },
     "sort": [
          {
               "account_number": "asc"  #这个排序值最好是唯一值
          }
     ]
}
//如果在排序的字段有多个值，还可以指定mode属性，可选的有：min, max, sum, avg, median。比如price中有多个价格，如果按当中最大值排序的话，查询语句要这样配置
     "sort": [
          {"price": {"order":"asc", "mode":"max"}
     ]
//如果某些文档没有排序字段，可以指定其位置
     {"price": {"order":"asc", "mode":"max", "missing":"_last||_first"}

查询特定字段

"_source": [
          "account_number","age"
     ]
 或
 "_source": {
    "includes": [ "account_number",  "firstname"],
    "excludes": ["*.price"]
    },

按特定字段匹配查询-where

"query": {
          "match": {"account_number"：1}
     },

按特定字段匹配查询-where多条件

GET customer/_search
{"query":{
    "match":{
        "text":{
            "query":"ld",
            "operator":"and"
        }
    }
}
}

按特定字段匹配查询多条件bool查询-or || and || not

bool下可以有多个子句，也可以在子句中嵌套bool查询。

//address的值必须同时包含Holmes和Lane
{
     "query": {
          "bool": {
               "must": [
                    { "match": {  "address": "Holmes" }  },
                    { "match": {  "address": "Lane" }  },
               ]
          }
     }
}

must：相对于and
should：相当于or
must not：and的相反

过滤-filter

它不计算score分值，其性能会更好一些。

"filter": {
                    "range": {
                         "balance": {
                              "glt": 10000,
                              "lte": 30000
                         }
                    }
               }

活动

应用商城

合作伙伴

开发者

支持与服务

了解天翼云

elasticSearch(3) - restfulApi

elasticSearch(3) - restfulApi

一、通用规则

操作原则

RestfulAPI格式

查询结果示例

查询参数-格式控制

元数据过滤

索引名称快捷

调试参数

日期快捷

二、集群概要信息查看

查看子目录

集群健康度

节点信息

查询别名

查询分片

查询分段

三、操作节点

四、操作集群

五、操作索引

查询索引是否存在

打开或关闭索引

删除

查询设置

查询集群和索引文档总数

设置索引

收缩索引

查看映射

六、操作文档

创建

更新

添加字段

查询byId

删除

列表查询

查询数据分片归属

七、批量操作

批量查询（读）

批量操作(写)

八、Query SQL

统计-count

分组-group by

集合查询-limit

分页查询-limit from

字段排序-order by

查询特定字段

按特定字段匹配查询-where

按特定字段匹配查询-where多条件

按特定字段匹配查询多条件bool查询-or || and || not

过滤-filter

相关文章

elasticSearch(4) - mapping定义

elasticSearch(6) - 高级检索

作者介绍

最新文章

elasticSearch(4) - mapping定义

elasticSearch(6) - 高级检索

热门文章

elasticSearch(6) - 高级检索

elasticSearch(4) - mapping定义

热门标签

相关产品

弹性云主机

天翼云电脑（公众版）

对象存储

云硬盘

随机文章

elasticSearch(6) - 高级检索

elasticSearch(4) - mapping定义