Elasticsearch 入门实战(3)--REST API 使用-CFANZ编程社区

本文主要介绍 Elasticsearch REST API 的使用，相关的环境及软件信息如下：CentOS 7.6.1810、Elasticsearch 8.2.2。

1、REST API 使用方法

curl -X <VERB> '<PROTOCOL>://<HOST>:<PORT>/<PATH>?<QUERY_STRING>' ‐d '<BODY>'

说明：

参数	说明
<VERB>	请求方法，如：GET，POST，PUT，HEAD 或 DELETE
<PROTOCOL>	协议，http 或 https
<HOST>	主机
<PORT>	Elasticsearch 服务端口，默认为9200
<PATH>	API 端点
<QUERY_STRING>	请求参数
<BODY>	JSON 格式的请求体

2、Compact and aligned text (CAT) APIs

cat API 是提供给人在 Kibana 控制台或命令行中使用的，不适合应用程序调用。

2.1、查看集群健康状况

curl -X GET "http://10.49.196.11:9200/_cat/health?v=true"

2.2、查看集节点信息

curl -X GET "http://10.49.196.11:9200/_cat/nodes?v=true"

3、Index APIs

3.1、创建索引

同时设置了 setting 和 mapping 信息；setting 里面包含分片和副本信息，mapping 里包含字段设置的详细信息。

curl -X PUT -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index' -d '
{
  "settings": {
    "index": {
      "number_of_shards": 2,
      "number_of_replicas": 1
      }
  },
  "mappings": {
    "properties": {
      "age": {
        "type": "integer"
      },
      "name": {
        "type": "keyword"
      },
      "poems": {
        "type": "text",
        "analyzer": "ik_max_word",
        "search_analyzer": "ik_max_word"
      },
      "about": {
        "type": "text",
        "analyzer": "ik_max_word",
        "search_analyzer": "ik_max_word"
      },
      "success": {
        "type": "text",
        "analyzer": "ik_max_word",
        "search_analyzer": "ik_max_word"
      }
    }
  }
}'

3.2、修改 _mapping 信息

字段可以新增，已有的字段只能修改字段的 search_analyze r属性。

curl -X PUT -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index' -d '
{
  "properties": {
    "name": {
      "type": "text",
      "analyzer": "ik_max_word",
      "search_analyzer": "ik_max_word"
    },
    "age": {
      "type": "integer"
    },
    "desc": {
      "type": "text",
      "analyzer": "ik_max_word",
      "search_analyzer": "ik_smart"
    }
  }
}'

3.3、删除索引

curl -X DELETE 'http://10.49.196.11:9200/poet-index'

3.4、查询索引列表

curl -X GET "http://10.49.196.11:9200/*"

或

curl -X GET "http://10.49.196.11:9200/_all"

3.5、查询索引详情

curl -X GET 'http://10.49.196.11:9200/poet-index'

4、Document APIs

4.1、新增文档

A、设置 id 为 1

curl -X POST -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_create/1' -d '
{
  "age": 30,
  "name": "李白",
  "poems": "静夜思",
  "about": "字太白",
  "success": "创造了古代浪漫主义文学高峰、歌行体和七绝达到后人难及的高度"
}'

B、不设置 id，将自动生成

curl -X POST -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_doc' -d '
{
  "age": 31,
  "name": "杜甫",
  "poems": "登高",
  "about": "字子美",
  "success": "唐代伟大的现实主义文学作家，唐诗思想艺术的集大成者"
}'

C、批量新增文档

curl -X POST -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_bulk' -d '
{"index":{"_id":"11"}}
{"age": 30,"name": "杜甫11","poems": "登高","about": "字子美","success": "唐代伟大的现实主义文学作家，唐诗思想艺术的集大成者"}
{"index":{"_id":"12"}}
{"age": 30,"name": "杜甫12","poems": "登高","about": "字子美","success": "唐代伟大的现实主义文学作家，唐诗思想艺术的集大成者"}

'

注：最后的空行是需要的，否则会报错。

4.2、删除文档

curl -X DELETE 'http://10.49.196.11:9200/poet-index/_doc/1'

4.3、更新文档

只更新参数设置的字段。

curl -X POST -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_update/1' -d '
{
  "doc": {
    "age": 32,
    "poems": "望庐山瀑布"
  }
}'

4.4、新增或覆盖文档

没有对应 id 的文档就创建，有就覆盖更新所有的字段(相当于先删除再新增)。

curl -X PUT -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_doc/1' -d '
{
  "age": 31,
  "name": "李白",
  "poems": "静夜思",
  "about": "字太白"
}'

5、Search APIs

5.1、查询一个索引的所有文档

curl -X GET 'http://10.49.196.11:9200/poet-index/_search'

5.2、根据 id 查询文档

curl -X GET 'http://10.49.196.11:9200/poet-index/_doc/1'

5.3、term 查询

term 查询不会对输入的内容进行分词处理，而是作为一个整体来查询。

A、查询单个词

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "term": {
      "name": {
        "value": "李白"
      }
    }
  }
}'

B、查询多个词

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "terms": {
      "name": ["李白", "杜甫"]
    }
  }
}'

5.4、range 查询

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "range": {
      "age": {
        "gte": 20,
        "lte": 35
      }
    }
  }
}'

5.5、全文查询

5.5.1、match

对输入的内容进行分词处理，再根据分词查询。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "match": {
      "success": "理想主义"
    }
  },
  "from": 0,
  "size": 10,
  "sort": [{
    "name": {
      "order": "asc"
    }
  }]
}'

5.5.2、multi_match

多字段匹配。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "multi_match": {
      "query": "太白",
      "fields": ["about", "success"]
    }
  }
}'

5.5.3、match_phrase

匹配整个查询字符串。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "match_phrase": {
      "success": "文学作家"
    }
  }
}'

5.5.4、match_all

查询所有数据。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "match_all": {
     }
  }
}'

5.5.5、query_string

query_string 可以同时实现前面几种查询方法。

A、类似 match

curl -X GET  -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "default_field": "success",
      "query": "古典文学"
    }
  }
}'

B、类似 mulit_match

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "query": "古典文学",
      "fields": ["about", "success"]
    }
  }
}'

C、类似 match_phrase

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "default_field": "success",
      "query": "\"古典文学\""
    }
  }
}'

D、带运算符查询，运算符两边的词不再分词

1、查询同时包含 ”文学“ 和 ”伟大“ 的文档

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "default_field": "success",
      "query": "文学 AND 伟大"
    }
  }
}'

或

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "fields": ["success"],
      "query": "文学 伟大",
      "default_operator": "AND"
    }
  }
}'

2、查询 name 或 success 字段包含"文学"和"伟大"这两个单词，或者包含"李白"这个单词的文档。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "query_string": {
      "query": "(文学 AND 伟大) OR 李白",
      "fields": ["name", "success"]
    }
  }
}'

5.5.6、simple_query_string

类似 query_string，主要区别如下：

1、不支持AND OR NOT ，会当做字符处理；使用 + 代替 AND，| 代替OR，- 代替 NOT
2、会忽略错误的语法

查询同时包含 ”文学“ 和 ”伟大“ 的文档：

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "simple_query_string": {
      "fields": ["success"],
      "query": "文学 + 伟大"
    }
  }
}'

5.6、模糊查询

模糊查询时使用的参数：

fuzziness	允许的最大编辑距离，默认不开启模糊查询，相当于 fuzziness=0。支持的格式 1、可以是数字（0、1、2）代表固定的最大编辑距离 2、自动模式，AUTO:[low],[high] 查询词长度在 [0-low)范围内编辑距离为 0（即强匹配) 查询词长度在 [low, high) 范围内允许编辑 1 次查询词长度 >high 允许编辑 2 次
prefix_length	控制两个字符串匹配的最小相同的前缀大小，也就是前 n 个字符不允许编辑，必须与查询词相同，默认是 0，大于 0 时可以显著提升查询性能
max_expansions	产生的最大模糊选项
transpositions	相邻位置字符互换是否算作 1 次编辑距离，全文查询不支持该参数

A、全文查询时使用模糊参数

先分词再计算模糊选项。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "match": {
        "success": {
         "query": "古典文化",
        "fuzziness": 1,
        "prefix_length": 0,
        "max_expansions": 5
        }
    }
  }
}'

B、使用 fuzzy query

对输入不分词，直接计算模糊选项。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "fuzzy": {
      "success": {
        "value": "理想",
        "fuzziness": 1,
        "prefix_length": 0,
        "transpositions": true
      }
    }
  }
}'

5.7、组合查询

组合查询使用 bool 来组合多个查询条件。

条件	说明
must	同时满足
should	满足其中任意一个
must_not	同时不满足
filter	过滤搜索，不计算得分

A、查询 success 包含 “思想” 且 age 在 [20-40] 之间的文档：

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "bool": {
      "must": [{
        "simple_query_string": {
          "query": "思想",
          "fields": ["success"]
        }
      }, {
        "range": {
          "age": {
            "gte": 20,
            "lte": 40
          }
        }
      }]
    }
  }
}'

B、过滤出 success 包含 “思想” 且 age 在 [20-40] 之间的文档，不计算得分：

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "bool": {
      "filter": [{
        "simple_query_string": {
          "query": "思想",
          "fields": ["success"]
        }
      }, {
        "range": {
          "age": {
            "gte": 20,
            "lte": 40
          }
        }
      }]
    }
  }
}'

5.8、聚合查询

A、求和

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "aggs": {
    "age_sum": {
      "sum": {
        "field": "age"
      }
    }
  }
}'

B、类似 select count distinct(age) from poet-index

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/test-index/_search' -d '
{
  "aggs": {
    "age_count": {
      "cardinality": {
        "field": "age"
      }
    }
  }
}'

C、数量、最大、最小、平均、求和

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "aggs": {
    "age_stats": {
      "stats": {
        "field": "age"
      }
    }
  },
  "size": 0
}'

D、类似 select name,count(*) from poet-index group by name

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "aggs": {
    "name_terms": {
      "terms": {
        "field": "name"
      }
    }
  },
  "size": 0
}'

E、类似 select name,age, count(*) from poet-index group by name,age

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "aggs": {
    "name_terms": {
      "terms": {
        "field": "name"
      },
      "aggs": {
        "age_terms": {
          "terms": {
            "field": "age"
          }
        }
      }
    }
  },
  "size": 0
}'

F、类似 select avg(age) from poet-indexwhere name='李白'

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "bool": {
      "filter": {
        "term": {
          "name": "李白"
        }
      }
    }
  },
  "aggs": {
    "age_avg": {
      "avg": {
        "field": "age"
      }
    }
  },
  "size": 0
}'

5.9、推荐搜索

如果希望 Elasticsearch 能够根据我们的搜索内容给一些推荐的搜索选项，可以使用推荐搜索。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "suggest": {
    "success_suggest": {
      "text": "思考",
      "term": {
        "field": "success",
        "analyzer": "ik_max_word",
        "suggest_mode": "always",
        "min_word_length":2
      }
    }
  }
}'

推荐模式 suggest_mode:

推荐模式	说明
popular	推荐词频更高的一些搜索
missing	当没有要搜索的结果的时候才推荐
always	无论什么情况下都进行推荐

5.10、高亮显示

对搜索结果中的关键字高亮显示。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/poet-index/_search' -d '
{
  "query": {
    "match": {
      "success": "思想"
    }
  },
  "highlight": {
    "pre_tags": "<span color='red'>",  
    "post_tags": "</span>",        
    "fields": {            
      "success": {}
    }
  }
}'

5.11、SQL 查询

Elasticsearch 支持通过 SQL 查询数据。

curl -X GET -H 'Content-Type:application/json' 'http://10.49.196.11:9200/_sql' -d '
{
  "query": "SELECT * FROM \"poet-index\" limit 3"
}'

详细的 Elasticsearch REST API 使用说明，请参考官网文档：https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html。