Elasticsearch 简明教程

Elasticsearch - API Conventions

网络中的应用程序编程接口 (API) 是一组函数调用或其他编程指令，用于访问特定 Web 应用程序中的软件组件。例如，Facebook API 帮助开发人员通过访问 Facebook 中的数据或其他功能来创建应用程序；它可以是出生日期或状态更新。

Application Programming Interface (API) in web is a group of function calls or other programming instructions to access the software component in that particular web application. For example, Facebook API helps a developer to create applications by accessing data or other functionalities from Facebook; it can be date of birth or status update.

Elasticsearch 提供了一个 REST API，该 API 通过 HTTP 上的 JSON 进行访问。Elasticsearch 使用了一些约定，我们现在将讨论它们。

Elasticsearch provides a REST API, which is accessed by JSON over HTTP. Elasticsearch uses some conventions which we shall discuss now.

Multiple Indices

API 中的大多数操作（主要是搜索和其他操作）面向一个或多个索引。这使用户只需执行一次查询即可在多个位置或所有可用数据中进行搜索。使用许多不同的符号在多个索引中执行操作。我们将在本章中讨论其中的几个。

Most of the operations, mainly searching and other operations, in APIs are for one or more than one indices. This helps the user to search in multiple places or all the available data by just executing a query once. Many different notations are used to perform operations in multiple indices. We will discuss a few of them here in this chapter.

Comma Separated Notation

POST /index1,index2,index3/_search

Request Body

{
   "query":{
      "query_string":{
         "query":"any_string"
      }
   }
}

Response

包含 any_string 的 index1、index2、index3 中的 JSON 对象。

JSON objects from index1, index2, index3 having any_string in it.

_all Keyword for All Indices

POST /_all/_search

Request Body

{
   "query":{
      "query_string":{
         "query":"any_string"
      }
   }
}

Response

包含 any_string 的所有索引中的 JSON 对象。

JSON objects from all indices and having any_string in it.

Wildcards ( * , + , –)

POST /school*/_search

Request Body

{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

Response

在所有索引中包含“school”开头的包含 CBSE 的 JSON 对象。

JSON objects from all indices which start with school having CBSE in it.

或者，您也可以使用以下代码：-

Alternatively, you can use the following code as well −

POST /school*,-schools_gov /_search

Request Body

{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

Response

所有索引中包含“school”开头的但不包含 schools_gov 并且包含 CBSE 的 JSON 对象。

JSON objects from all indices which start with “school” but not from schools_gov and having CBSE in it.

还有一些 URL 查询字符串参数：-

There are also some URL query string parameters −

ignore_unavailable − No error will occur or no operation will be stopped, if the one or more index(es) present in the URL does not exist. For example, schools index exists, but book_shops does not exist.

POST /school*,book_shops/_search

Request Body

{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

Request Body

{
   "error":{
      "root_cause":[{
         "type":"index_not_found_exception", "reason":"no such index",
         "resource.type":"index_or_alias", "resource.id":"book_shops",
         "index":"book_shops"
      }],
      "type":"index_not_found_exception", "reason":"no such index",
      "resource.type":"index_or_alias", "resource.id":"book_shops",
      "index":"book_shops"
   },"status":404
}

考虑以下代码：-

Consider the following code −

POST /school*,book_shops/_search?ignore_unavailable = true

Request Body

{
   "query":{
      "query_string":{
         "query":"CBSE"
      }
   }
}

Response (no error)

在所有索引中包含“school”开头的包含 CBSE 的 JSON 对象。

JSON objects from all indices which start with school having CBSE in it.

allow_no_indices

true 此参数的值可防止错误，如果带通配符的 URL 导致没有索引。例如，没有以 schools_pri 开头的索引

true value of this parameter will prevent error, if a URL with wildcard results in no indices. For example, there is no index that starts with schools_pri −

POST /schools_pri*/_search?allow_no_indices = true

Request Body

{
   "query":{
      "match_all":{}
   }
}

Response (No errors)

{
   "took":1,"timed_out": false, "_shards":{"total":0, "successful":0, "failed":0},
   "hits":{"total":0, "max_score":0.0, "hits":[]}
}

expand_wildcards

这个参数决定了通配符是需要扩展成开指标还是闭指标，或同时执行这两种操作。此参数的值可以是 open 和 closed，也可以是 none 和 all。

This parameter decides whether the wildcards need to be expanded to open indices or closed indices or perform both. The value of this parameter can be open and closed or none and all.

例如，关闭索引学校：

For example, close index schools −

POST /schools/_close

Response

{"acknowledged":true}

考虑以下代码：-

Consider the following code −

POST /school*/_search?expand_wildcards = closed

Request Body

{
   "query":{
      "match_all":{}
   }
}

Response

{
   "error":{
      "root_cause":[{
         "type":"index_closed_exception", "reason":"closed", "index":"schools"
      }],
      "type":"index_closed_exception", "reason":"closed", "index":"schools"
   }, "status":403
}

Date Math Support in Index Names

Elasticsearch 提供一种按照日期和时间搜索索引的功能。我们需要使用特定格式指定日期和时间。例如，accountdetail-2015.12.30，索引将存储 2015 年 12 月 30 日的银行帐户详细信息。可以执行数学运算以获取特定日期或日期和时间范围的详细信息。

Elasticsearch offers a functionality to search indices according to date and time. We need to specify date and time in a specific format. For example, accountdetail-2015.12.30, index will store the bank account details of 30th December 2015. Mathematical operations can be performed to get details for a particular date or a range of date and time.

日期数学索引名称格式：

Format for date math index name −

<static_name{date_math_expr{date_format|time_zone}}>
/<accountdetail-{now-2d{YYYY.MM.dd|utc}}>/_search

static_name 是表达的一部分，在每个日期数学索引（如帐户详细信息）中保持不变。date_math_expr 包含确定日期和时间（如 now-2d）的数学表达式。date_format 包含日期在索引中写入的格式，如 YYYY.MM.dd。如果今天的日期是 2015 年 12 月 30 日，那么 <accountdetail-{now-2d{YYYY.MM.dd}}> 将返回 accountdetail-2015.12.28。

static_name is a part of expression which remains the same in every date math index like account detail. date_math_expr contains the mathematical expression that determines the date and time dynamically like now-2d. date_format contains the format in which the date is written in index like YYYY.MM.dd. If today’s date is 30th December 2015, then <accountdetail-{now-2d{YYYY.MM.dd}}> will return accountdetail-2015.12.28.

Expression

Resolves to

<accountdetail-{now-d}>

accountdetail-2015.12.29

<accountdetail-{now-M}>

accountdetail-2015.11.30

<accountdetail-{now{YYYY.MM}}>

accountdetail-2015.12

现在，我们将了解 Elasticsearch 中一些可用于以指定格式获取响应的常用选项。

We will now see some of the common options available in Elasticsearch that can be used to get the response in a specified format.

Pretty Results

只需追加 URL 查询参数（即 pretty = true）即可获得格式良好的 JSON 对象中的响应。

We can get response in a well-formatted JSON object by just appending a URL query parameter, i.e., pretty = true.

POST /schools/_search?pretty = true

Request Body

{
   "query":{
      "match_all":{}
   }
}

Response

……………………..
{
   "_index" : "schools", "_type" : "school", "_id" : "1", "_score" : 1.0,
   "_source":{
      "name":"Central School", "description":"CBSE Affiliation",
      "street":"Nagan", "city":"paprola", "state":"HP", "zip":"176115",
      "location": [31.8955385, 76.8380405], "fees":2000,
      "tags":["Senior Secondary", "beautiful campus"], "rating":"3.5"
   }
}
………………….

Human Readable Output

此选项可以将统计响应更改为人类可读形式（如果 human = true）或计算机可读形式（如果 human = false）。例如，如果 human = true，则 distance_kilometer = 20KM；如果 human = false，则 distance_meter = 20000（当需要另一个计算机程序使用响应时）。

This option can change the statistical responses either into human readable form (If human = true) or computer readable form (if human = false). For example, if human = true then distance_kilometer = 20KM and if human = false then distance_meter = 20000, when response needs to be used by another computer program.

Response Filtering

我们可以通过将字段添加到 field_path 参数中来过滤响应到更少的字段。例如，

We can filter the response to less fields by adding them in the field_path parameter. For example,

POST /schools/_search?filter_path = hits.total

Request Body

{
   "query":{
      "match_all":{}
   }
}

Response

{"hits":{"total":3}}