速查手册06-REST APIs

文档API
集群API
索引API
搜索API
脚本API

文档API

index

索引文旦时，并发控制见：ES并发控制

#格式
PUT /<target>/_doc/<_id>
POST /<target>/_doc/
PUT /<target>/_create/<_id>
POST /<target>/_create/<_id>
# eg:
PUT my_index/_create/1
{
  "name":"xiao"
}
PUT /my_index/_doc/2
{
  "name":"li"
}
# ID自动生成，只能用post，PUT会报错
PUT /my_index/_doc
{
  "name":"auto id"
}
POST /my_index/_doc
{
  "name":"auto id"
}

get

#格式
GET <index>/_doc/<_id>
HEAD <index>/_doc/<_id>
GET <index>/_source/<_id>
HEAD <index>/_source/<_id>
# 示例
GET my_index/_doc/1  // 文档数据
HEAD my_index/_doc/1 // 文档是否存在  200 or 404
GET my_index/_source/1 // 文档_source ，json
GET my-index-000001/_doc/0?_source=false
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
GET my-index-000001/_doc/2?routing=user1&stored_fields=user

delete

DELETE /my-index-000001/_doc/1?routing=shard-1&timeout=5m

delete_by_query

查询参数

参数	作用	默认值	示例
allow_no_indices	无对应索引名称，是否报错	TRUE
analyzer	查询字符串的分析器	standard
analyze_wildcard	通配符和前缀查询被分析。	FALSE
conflicts	查询删除遇到版本冲突该怎么办： abort或proceed	abort
default_operator	查询字符串查询的默认运算符：AND 或 OR。默认为OR.	OR
q和df	q查询的字段和值（Lucene语法）；df是在q未指定字段时的默认字段	无	GET my_index/_search?q=name:xiao GET my_index/_search?q=xiao&df=name
expand_wildcards	仅针对通配符查询index时，是否查询的的索引状态	open	#all,open,closed,hidden,none,默认 open
from	起始文档偏移量	0	GET my_index*/_search?q=name:xiao&expand_wildcards=open #查询closed
ignore_unavailable	如果true，响应中不包含缺失或关闭的索引	FALSE
lenient	如果true，基于格式的查询失败（例如向数字字段提供文本）将被忽略	FALSE
max_docs	要处理的最大文档数	所有文档
preference	定应在其上执行操作的节点或分片	随机
request_cache	定应在其上执行操作的节点或分片	索引级别设置
refresh	如果true，Elasticsearch 会在请求完成后刷新按查询删除涉及的所有分片	FALSE
requests_per_second	请求的限制（每秒子请求数）	默认为-1，无限制
routing	用于将操作路由到特定分片的自定义值。	hash/id
scroll	滚动查询时，两次滚动的scrollId的超时时间	1分钟	POST /my-index-000001/_search?scroll=1m
scroll_size	滚动查询时，一次文档大小	1000
search_type	搜索操作的类型	query_then_fetch	query_then_fetch dfs_query_then_fetch 差异在这里：https://www.yuque.com/timeasving/xovt29/sdebeg
search_timeout	每个搜索请求的显式超时	不超时
slices	任务并行	1
sort	排序	id
_source	是否_source内容	TRUE
_source_excludes	从source中排除的字段	无
_source_includes	source中包含的字段	全部
timeout	每个删除请求等待活动分片的时间段	一分钟
version	如果true，则返回文档版本作为命中的一部分	FALSE
wait_for_active_shards	在继续操作之前必须处于活动状态的分片副本数	all

eg：

# 1
POST /my-index-000001/_delete_by_query
{
  "query": {
    "match": {
      "user.id": "elkbee"
    }
  }
}
# 2 版本冲突处理，停止：abort，继续：proceed， 默认 abort
POST my-index-000001/_delete_by_query?conflicts=proceed
{
  "query": {
    "match_all": {}
  }
}

update

# 1
POST test/_update/1
{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}
# 2
POST test/_update/1
{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

_update_by_query

请求参数同_delete_by_query

POST my-index-000001/_update_by_query?conflicts=proceed
POST my-index-000001,my-index-000002/_update_by_query
POST my-index-000001/_update_by_query?routing=1
POST my-index-000001/_update_by_query?scroll_size=100

Multi get

# 1
GET /_mget
{
  "docs": [
    {
      "_index": "my-index-000001",
      "_id": "1"
    },
    {
      "_index": "my-index-000001",
      "_id": "2"
    }
  ]
}
# 2
    GET /_mget
{
  "docs": [
    {
      "_index": "test",
      "_type": "_doc",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_type": "_doc",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_type": "_doc",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}

bulk

POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }

reindex

请求url参数：

refresh：操作完成后refresh，默认false
timeout：超时时间 1分钟
wait_for_active_shards：：继续操作之前必须处于活动状态的分片副本数，默认all
wait_for_completion：如果true，请求将阻塞，直到操作完成；默认true
requests_per_second：每秒子请求数，默认不限制
require_alias：如果true，目标必须是索引别名
scroll：滚动搜索保持多长时间，默认1分钟
slices：并行度，默认1，无子任务
max_docs：要处理的最大文档数。默认为所有文档。

请求body参数：
conflicts：proceed即使存在冲突也继续重新索引，默认abort
source：
1. index：索引或别名的名称 ,支持多，逗号分隔
2. max_docs：索引的最大文档数
3. query：查询 DSL
4. remote：
  1. host：远程host
  2. username：远程用户名
  3. password：远程密码
  4. socket_timeout：socket超时，默认30s
  5. connect_timeout：链接超时，默认30s
5. size：一批的数量；远程时最大100M
6. slice：并行度，。设置 slices高于分片数通常不会提高效率并增加开销
  sort：排序字段,7.6已弃用，不建议使用
dest
1. index：目标索引名称
2. version_type：版本信息
3. op_type：当设置成 create 时，仅创建目标索引不存在的数据。默认是：index：创建或更新

eg：

# 默认
POST _reindex
{
  "source": {
    "index": "my_old_index1"
  },
  "dest": {
    "index": "my_new_index2"
  }
}
# 控制每秒请求1此，一次500
POST _reindex?requests_per_second=1 
    {
      "source": {
        "index": "my_old_index1",
        "size": 500
      },
      "dest": {
        "index": "my_new_index2"
      }
    }
# 远程时，A-->B 需要在B节点设置白名单 A  
#在elasticSearch.yml 添加 ：reindex.remote.whitelist: A:9200
POST _reindex
{
    "source":{
        "remote":{
            "host":"http://A:9200"
        },
        "index":"my_old_index1"
    },
    "dest":{
        "index":"my_new_index2"
    }
}

术语向量(分词效果)

GET /my-index-000001/_termvectors/1?fields=message

数据向量（多个）

POST /_mtermvectors
{
   "docs": [
      {
         "_index": "my-index-000001",
         "doc" : {
            "message" : "test test test"
         }
      },
      {
         "_index": "my-index-000001",
         "doc" : {
           "message" : "Another test ..."
         }
      }
   ]
}

?refresh

增删改后立即可见

乐观并发控制

eg：

PUT products/_doc/1567?if_seq_no=362&if_primary_term=2
{
  "product": "r2d2",
  "details": "A resourceful astromech droid",
  "tags": [ "droid" ]
}

更多乐观并发控制见：ES乐观并发控制

集群API

分配说明

请求参数：params

include_disk_info：磁盘信息
nclude_yes_decisions：解释信息

eg：

GET _cluster/allocation/explain?include_disk_info=true&human=true&include_yes_decisions=true

请求参数：body

current_node：
index
primary
shard

eg：

GET _cluster/allocation/explain
{
  "index": "my_index",
  "shard": 0,
  "primary": true,
  "current_node":"node-81"
}

获取setting

GET /_cluster/settings

集群健康

GET /_cluster/health

集群状态

GET /_cluster/state/_all/my_index

集群统计

GET /_cluster/stats

重新路由

POST /_cluster/reroute
{
  "commands": [
    {
      "move": {
        "index": "test", "shard": 0,
        "from_node": "node1", "to_node": "node2"
      }
    },
    {
      "allocate_replica": {
        "index": "test", "shard": 1,
        "node": "node3"
      }
    }
  ]
}

更新setting

eg：

PUT /_cluster/settings
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}

格式：

{
  ...
  "persistent" : {},
  "transient" : {}
}

节点使用次数

GET _nodes/usage

热点线程

GET /_nodes/hot_threads
GET /_nodes/<node_id>/hot_threads
#请求参数：ignore_idle_threads，interval，snapshots，threads，master_timeout，timeout，type

节点信息

GET /_nodes
GET /_nodes/<node_id>
GET /_nodes/<metric>
GET /_nodes/<node_id>/<metric>

节点统计

GET /_nodes/stats?human=true

任务管理

GET /_tasks/<task_id>
GET /_tasks

索引API

索引管理

创建

PUT /test
{
  "aliases": {
    "alias_1": {},
    "alias_2": {
      "filter": { // 指定符合查询条件的数据，才允许索引查询
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    }
  },
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "field1": {
        "type": "text"
      }
    }
  }
}

删除

DELETE /my-index-000001

获取

GET /my-index-000001

存在

HEAD my-index-000001 //返回404 或者 200

关闭

POST /my-index-000001/_close # 关闭后搜索不到

打开

POST /my-index-000001/_open

索引收缩

# 索引收缩（减少分片），条件：↓
    有满足以下要求才能收缩指数：
        目标索引不得存在。
        源索引必须比目标索引具有更多的主分片。
        目标索引中的主分片数必须是源索引中主分片数的一个因子。源索引必须比目标索引具有更多的主分片。
        索引中包含的2,147,483,519所有分片中的文档总数不得超过目标索引上的单个分片，因为这是可以放入单个分片的最大文档数。
        处理收缩过程的节点必须有足够的可用磁盘空间来容纳现有索引的第二个副本。
操作步骤 eg:
1):第一步，提前将副本设置0，再将索引的所有分片，移动到同一个节点，设置只读
PUT /old索引/_settings
{
  "settings": {
    "index.routing.allocation.require._name": "节点名称",
    "index.blocks.write": true
  }
}
2）：减少分片操作
POST old索引/_shrink/new索引
{
  "settings": {
    "index.routing.allocation.require._name": null,
    "index.blocks.write": null,
    "index.number_of_replicas": 0,
    "index.number_of_shards": 2
  },
  "aliases": {
    "new索引别名": {}
  }
实际操作，感觉使用reindex更方便一些。

拆分

# 先决条件
索引必须是只读的。
该集群的健康状态必须是绿色的。
# 1设置old索引只读
PUT /old索引/_settings
{
  "settings": {
    "index.blocks.write": true 
  }
}
# 2 执行拆分
POST old索引/_split/new索引
{
  "settings": {
    "index.number_of_shards": 2
  }
}
实际操作，感觉使用reindex更方便一些。

克隆

#条件
1：克隆索引，该索引必须标记为只读并且 集群健康状态为green。
2：目标索引不存在
POST /my_index_1/_clone/my_index_12
{
  "settings": {
    "index.number_of_shards": 5 
  },
  "aliases": {
    "my_search_indices": {}
  }
}

滚动

更多实例放到了：索引生命周期管理

POST my-write-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb"
  }
}

Mapping管理

更新索引

# 添加字段
PUT /my-index-000001/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}
# 修改索引 ignore（TIPS：索引类型不可修改）
PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}
# 增加别名，指向另一个字段
PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}

获取索引

GET /my-index-000001/_mapping

获取索引字段

GET publications/_mapping/field/author.id,abstract,name
GET /_all/_mapping/field/*.id

类型存在

# 7.0版本后删除type
HEAD my-index-000001/_mapping/message

分析磁盘使用率

# 此功能是实验性的，后续版本可能删除(7.x版本经过测试，不可用)
POST /my-index-000001/_disk_usage?run_expensive_tasks=true

别名管理

别名添加

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "test1",
        "alias": "alias1"
      }
    },
    {
      "remove": {
        "index": "test1",
        "alias": "alias1"
      }
    }
  ]
}

快速创建别名

POST my_index/_alias/my-alias3

获取别名

GET my_index/_alias/<alias>

别名存在

HEAD _alias/my-alias
HEAD my_index/_alias/my-alias

删除别名

DELETE my_index/_alias/my-alias

Setting管理

索引的setting的动态设置和静态设置，见：速查手册19-索引模块

更新Setting

# 修改副本数量
PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}
# 修改 refresh 为默认值
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : null
  }
}
# 修改 refresh 时间为1秒
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "1s"
  }
}
# 停止 refresh
PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "-1"
  }
}
# 添加分析器（索引必须关闭才能添加分析器），流程为：↓

POST /my-index-000001/_close?wait_for_active_shards=0

PUT /my-index-000001/_settings
{
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
}

POST /my-index-000001/_open

获取Setting

GET /my-index-000001/_settings

分析

GET /_analyze
{
  "analyzer" : "standard",
  "text" : "Quick Brown Foxes!"
}

索引模板

见：速查手册05-Mapping-索引模板

状态管理

清理缓存

POST /my-index-000001/_cache/clear?fielddata=true  
POST /my-index-000001/_cache/clear?query=true      
POST /my-index-000001/_cache/clear?request=true
POST /my-index-000001/_cache/clear?fields=foo,bar

refresh

POST /my-index-000001/_refresh

flush

POST / my-index-000001 / _flush

强制段合并

POST /my-index-000001/_forcemerge
POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1  #个人认为一般用于归档

搜索API

放到：速查手册07-QUERY DSL 具体讨论

脚本API

放到：速查手册10-script脚本具体讨论

文档API

index

get

delete

delete_by_query

_update_by_query

Multi get

bulk

reindex

请求url参数：

请求body参数：

术语向量(分词效果)

数据向量（多个）

?refresh

乐观并发控制

集群API

分配说明

获取setting

集群健康

集群状态

集群统计

重新路由

更新setting

节点使用次数

热点线程

节点信息

节点统计

任务管理

索引API

索引管理

创建

删除

获取

存在

关闭

打开

索引收缩

拆分

克隆

滚动

Mapping管理

更新索引

获取索引

获取索引字段

类型存在

分析磁盘使用率

别名管理

别名添加

快速创建别名

获取别名

别名存在

删除别名

Setting管理

更新Setting

获取Setting

分析

索引模板

状态管理

清理缓存

refresh

flush

强制段合并

搜索API

脚本API