[toc]
单文档Index API
1. 索引一个文档
PUT /weibo/_doc/1
{
"user": "niewj",
"post_date": "2020-11-20T17:00:00",
"message": "trying out Elasticsearch"
}output:
{
"_index" : "weibo",
"_type" : "_doc",
"_id" : "1",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 0,
"_primary_term" : 1
}- 索引如果不存在, 会自动创建一个索引;
- 如果不存在dynamic mapping, index时会创建一个;
- 如果需要, 新的字段和对象会自动加入到mapping 定义中;
2. 可选项op_type或_create(put_if_absent)
put默认是覆盖的; 但是如果使用一个op_type选项, 可以改变这个逻辑:
PUT /customer/_doc/5?op_type=create
{
"name": "niewj5"
}如果没有id=5的doc了, 索引成功; 如果已有, 就会失败;
另一种写法:
PUT /customer/_create/5
{
"name": "niewj5"
}output:
{
"error": {
"root_cause": [
{
"type": "version_conflict_engine_exception",
"reason": "[5]: version conflict, document already exists (current version [7])",
"index_uuid": "NjlJEQ5nS5e-PZQd_n2_Rw",
"shard": "0",
"index": "customer"
}
],
"type": "version_conflict_engine_exception",
"reason": "[5]: version conflict, document already exists (current version [7])",
"index_uuid": "NjlJEQ5nS5e-PZQd_n2_Rw",
"shard": "0",
"index": "customer"
},
"status": 409
}3. 不指定id时的post和put
# 不指定索引id时, 自动生成
POST twitter/_doc/
{
"user" : "kimchy",
"post_date" : "2009-11-15T14:12:12",
"message" : "trying out Elasticsearch"
}不指定id的post, 每次都生成新的随机id, output: "FPOw9HUB7InhghdESz3n"
{
"_index" : "twitter",
"_type" : "_doc",
"_id" : "FPOw9HUB7InhghdESz3n",
"_version" : 1,
"result" : "created",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 3,
"_primary_term" : 1
}但是不指定id的put会报错:
# 下面的操作会报错405: 不带ID的put=报错405
PUT twitter/_doc/
{
"user" : "kimchy",
"post_date" : "2009-11-15T14:12:12",
"message" : "trying out Elasticsearch"
}output:
{
"error": "Incorrect HTTP method for uri [/twitter/_doc/?pretty] and method [PUT], allowed: [POST]",
"status": 405
}4. 索引的乐观并发控制
if_seq_no和if_primary_term索引操作可以是通过有条件才触发的, 通过附带这两个参数的赋值;比如
PUT products/_doc/1567?if_seq_no=362&if_primary_term=2这个操作就会在版本序号对应的条件下才实施索引动作的执行;
参见: Optimistic concurrency control
5. 索引分片的路由
默认, 索引分片的路由, 是通过文档 id 的 hash 来确定文档路由到哪个分片的; 但是可以通过制定参数 routing=xxx来显式控制; 例如: 下面的文档, 会按照提供的参数:“kimchy”来路由分片
POST twitter/_doc?routing=kimchy
{
"user" : "kimchy",
"post_date" : "2009-11-15T14:12:12",
"message" : "trying out Elasticsearch"
}注意: 如果在mapping中定义了 _routing 且声明为 required , 此时如果索引时没有制定 routing值, 将会发生失败!
索引操作将会被定位到路由到的主分片, 并在主分片的节点上执行; (如果需要), 主分片执行完后, 将会分发到相应的副本(replicas).
6. 关于索引写操作的参数
wait_for_active_shards=1 默认索引的写操作只等待主分片, 只要它处于活动状态后就可写; 这个是可以修改的: 可以指定一个具体的数字N, 这样, 就会等待N个分片处于活跃时才进行写索引的操作; 如果没有N个, 就一直等到所需的副本数启动(或一直等到超时).
这个默认值可以通过设置
index.write.wait_for_active_shards 在索引设置中动态覆盖。
7. 索引操作与版本数
internal
只有给定版本与存储文档的版本相同时，才索引文档
external 或 external_gt
只有在给定版本严格高于存储文档的版本(或没有现有文档)时，才索引文档: 给定版本将作为新版本与新文档存储在一起。