ES 学习之路-indices APIs（1）

ES 学习之indices APIs

1.关闭通配符，_all等操作

在index api 中可以使用_all或者逗号操作符，或者是通配符*，但是这些操作可能会导致误操作，所有我们可以通过在配置文件中配置如下属性，这样api中将不能使用像_all这样的操作

action.destructive_requires_name=true

2.判断index是已经存在

可以通过api的方式判断一个index是否存在，如果index存在将会api调用将会返回200，如果不存在将会返回404，但是如果有别名和你查询的名称相同的时候，也会返回200，所以说这个api判断是index或者是别名是否存在。遗憾的是我在elasticsearch-head中调用这个api的时候，一直提示正在请求…，没有任何结果

HEAD /index_name

3.关闭/开启index

索引可以被关闭/开启， 一个关闭的索引的在集群中基本不需要什么开销，除了维护其元数据需要的开销，关闭的index后不能进行读写操作;这个API可以同时开启或者是关闭多个index，但是默认情况下， 如果遇到index不存在，将会抛出异常，我们可以通过在配置文件中配置ignore_unavailable=true方式忽略这样的问题，下边是开启、关闭api样例：

POST /my_index/_close
POST /my_index/_open

ignore_unavailable=true

关闭index可能会消耗大量的磁盘空间，同时引发一下别的问题，elasticsearch官方描述是如下：

​ Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be disabled via the cluster settings API by setting cluster.indices.close.enable to false. The default is true.

可以通过通过配置cluster.indices.close.enable=false的方式是index不可被关闭

cluster.indices.close.enable=false

4.等待分片操作

Because opening an index allocates its shards, the wait_for_active_shards setting on index creation applies to the index opening action as well. The default value for the wait_for_active_shards setting on the open index API is 0, which means that the command won’t wait for the shards to be allocated.

5.压缩index（shrink index）

我们知道一个index的shards是不可以调整的， 但是我们可以通过shrink index api将一个index压缩到一个新的index中， 但是这个api有很多要求：

• the target index must not exist
• The index must have more primary shards than the target index.
• The number of primary shards in the target index must be a factor of the number of primary shards in the source index. The source index must have more primary shards than the target index.
• The index must not contain more than 2,147,483,519 documents in total across all shards that will be shrunk into a single shard on the target index as this is the maximum number of docs that can fit into a single shard.
• The node handling the shrink process must have sufficient free disk space to accommodate a second copy of the existing index.

然后我们看看压缩操作过程

• First, it creates a new target index with the same definition as the source index, but with a smaller number of primary shards.
• Then it hard-links segments from the source index into the target index. (If the file system doesn’t support hard-linking, then all segments are copied into the new index, which is a much more time consuming process.)
• Finally, it recovers the target index as though it were a closed index which had just been re-opened.

要执行要是， 源index必须是只读的，而且健康值是green

In order to shrink an index, the index must be marked as read-only, and a (primary or replica) copy of every shard in the index must be relocated to the same node and have health green.

执行样例：

POST my_source_index/_shrink/my_target_index
{
  "settings": {
    "index.number_of_replicas": 1,
    "index.number_of_shards": 1, 
    "index.codec": "best_compression" 
  },
  "aliases": {
    "my_search_indices": {}
  }
}

该api调用后会立即返回， 不会等待压缩执行过程，但是可以查询其执行状态，详情请看：https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html#indices-shrink-index

6.rollover index(翻新index)

这个API可以从一个别名对应的index中翻新出一个新的index， 当你认为原来的index太旧或者是数据量太大时。这个api需要接收一个别名，还有一些判断条件，而且这个别名必须只对应一个index，当满足这些判断条件的时候， 新的index在执行这个API会被创建

PUT /logs-000001 
{
  "aliases": {
    "logs_write": {}
  }
}

# Add > 1000 documents to logs-000001

如果没有自己定义新index的名称， elasticsearch会给你定义一个
POST /logs_write/_rollover 
{
  "conditions": {
    "max_age":   "7d",
    "max_docs":  1000,
    "max_size":  "5gb"
  }
}

这个api调用时自己给出新index的名称
POST /my_alias/_rollover/my_new_index_name
{
  "conditions": {
    "max_age":   "7d",
    "max_docs":  1000,
    "max_size": "5gb"
  }
}

参数中不只是可以接收判断条件，同时还可以接收新index的一些设置，mappings,alias等等， 就像在创建create index的api一样
POST /logs_write/_rollover
{
  "conditions" : {
    "max_age": "7d",
    "max_docs": 1000,
    "max_size": "5gb"
  },
  "settings": {
    "index.number_of_shards": 2
  }
}
实际样例：
POST http://192.168.199.103:9200/log_write/_rollover/log-1/
{
  "conditions": {
    "max_docs": 100
  },
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 2
  },
  "mappings": {
    "log": {
      "properties": {
        "name": {
          "type": "text",
          "index": true
        },
        "message": {
          "type": "text",
          "index": true
        }
      }
    }
  },
  "aliases": {
    "log-1-write": {}
  }
}

{
"old_index": "logs",
"new_index": "log-1",
"rolled_over": true,
"dry_run": false,
"acknowledged": true,
"shards_acknowledged": true,
"conditions": {
"[max_docs: 100]": true
}
}

需要注意的是，如果在参数中不指定这些的话，那么创建出来的新的index将什么数据都不包含，mapping也是空的

7.PUT Mapping

put mapping API 允许我们给一个已经存在的index添加新的fields或者是改变现有字段的搜索模式。样例：

PUT twitter 
{}
创建一个什么都没有的index，命名为twitter

PUT twitter/_mapping/_doc 
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}
给twitter index 添加一个类型为_doc,同时给_doc添加一个属性email,类型为keyword

put mapping 可以支持多index(multi-index)参数， 也就是同时调整多个index的mapping，样例：

# Create the two indices
PUT twitter-1
PUT twitter-2

# Update both mappings
PUT /twitter-1,twitter-2/_mapping/_doc 
{
  "properties": {
    "user_name": {
      "type": "text"
    }
  }
}

实际上在elasticsearch中通过put mapping只能给现有的属性进行补充， 不能对现有的属性进行更改，否则会抛出异常，例如：

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "mapper [name] of different type, current_type [text], merged_type [long]"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "mapper [name] of different type, current_type [text], merged_type [long]"
  },
  "status": 400
}
这是更新一个field 为name的类型， 原来为text,改为long，结果执行api的时候抛出以上异常。

8.GET Mapping

get mapping api可以查询一个或多个index的mapping信息， 语法如下：

host:port/{index}/_mapping/{type}

样例：查询所有index中type为log的mapping,实际上没有index都只有一个type
GET /_all/_mapping/log

结果：
{
  "log-1": {
    "mappings": {
      "log": {
        "properties": {
          "email": {
            "type": "text"
          },
          "name": {
            "type": "text"
          }
        }
      }
    }
  }
}

9.GET Field Mapping

get field mapping API可以用来查询index中指定的一个或多个field信息， 而不是一次性查询一个index或多个index的所有mapping信息

创建一个publications index
PUT publications
{
    "mappings": {
        "_doc": {
            "properties": {
                "id": { "type": "text" },
                "title":  { "type": "text"},
                "abstract": { "type": "text"},
                "author": {
                    "properties": {
                        "id": { "type": "text" },
                        "name": { "type": "text" }
                    }
                }
            }
        }
    }
}

获取publications index 中_doc type 的title field 信息， 同时显示返回结果
GET publications/_mapping/_doc/field/title
{
   "publications": {
      "mappings": {
         "_doc": {
            "title": {
               "full_name": "title",
               "mapping": {
                  "title": {
                     "type": "text"
                  }
               }
            }
         }
      }
   }
}

get field mapping API 支持一次查询多个field或者是查询多个index的多个field

，它支持逗号运算符，_all, *号匹配等

如：

GET /twitter,kimchy/_mapping/field/message

GET /_all/_mapping/_doc,tweet,book/field/message,user.id

GET /_all/_mapping/_do*/field/*.id

GET publications/_mapping/_doc/field/a*

参考来源：https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html