Elasticsearch
###################

服务概述
=============

Elasticsearch 是一款基于 Lucene 构建的开源分布式检索和分析引擎，通过 RESTful API 提供近实时的索引、搜索功能。

新浪云 Elasticsearch 是基于开源的 Elasticsearch 2.1 版本搭建的一个集群，运行在新浪云的内网环境。对外开放 https API, 通过 Basic Authentication 使用。在新浪云上，您不需要管理 Elasticsearch 集群，只需要创建自己的索引就可以通过 API 索引、搜索您的数据，免去您运维 Elasticsearch 集群的苦恼。

创建索引（Index）
==================

在控制台管理页面导航中点击『数据库与缓存／Elasticsearch』进入创建页面。

点击“创建索引”，输入索引名并选择容量后点“确定”，一个索引就创建好了。注意：索引是用户级别的。

点击“查看帐号”查看您索引的帐号和密码，通过 Basic Authentication 的官方 API 使用。

.. image:: /images/es-create.png

创建索引默认分片以及副本配置如下：

 - number_of_shards：5
 - number_of_replicas：1

使用索引（Index）
=================

您通过新浪云控制台创建了索引，就可以通过带 Basic Authentication 的 API 索引、搜索了。地址是： *https://es.sinacloud.com* 。Basic Authentication 的帐号和密码在 Elasticsearch 创建页点“查看帐号”查询。

例如：您在控制台创建了名为 `aktestes1234_hellosae` 的索引，您的帐号是 testes1234，密码是 i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc。就可以像下面一样通过 Elasticsearch 原生 API 索引、查询您的数据了。

.. code-block:: console

 $ curl 'https://es.sinacloud.com/aktestes1234_hellosae/people/_susan' -u 'testes1234:i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc' -d  '{"first_name": "susan","last_name": "lee","age": 19}'
 {"_index":"aktestes1234_hellosae","_type":"people","_id":"_susan","_version":2,"_shards":{"total":2,"successful":2,"failed":0},"created":false}

 $ curl 'https://es.sinacloud.com/aktestes1234_hellosae/people/_susan' -u 'testes1234:i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc'
 {"_index":"aktestes1234_hellosae","_type":"people","_id":"_susan","_version":2,"found":true,"_source":{"first_name": "susan","last_name": "lee","age": 19}}

Elasticsearch API
=========================

因不需要您运维 Elasticsearch 集群，我们对原生 `API <https://www.elastic.co/guide/en/elasticsearch/reference/2.1/index.html>`_ 进行了部分权限的回收。

开放的 API 和 Elasticsearch 的原生 API 是一致的。 下面是开放的常用原生 API：

+ `Document APIs <https://www.elastic.co/guide/en/elasticsearch/reference/2.1/docs.html>`_

 - Index API
 - Get API
 - Delete API
 - Update API
 - Multi Get API

+ `Indices APIs <https://www.elastic.co/guide/en/elasticsearch/reference/2.1/indices.html>`_

 - Get Index
 - Indices Exists
 - Get mapping
 - Types Exists
 - Get Settings
 - Indices Stats

+ cat APIs

 - cat count

+ `Search APIs <https://www.elastic.co/guide/en/elasticsearch/reference/2.1/search.html>`_

 - Search
 - URI Search
 - Request Body Search
 - Count API
 - Search Exists API
 - Explain API

+ `Query DSL <https://www.elastic.co/guide/en/elasticsearch/reference/2.1/query-dsl.html>`_

 - Query and filter context
 - Match All Query
 - Full text queries


插件
=========

当前我们的 Elasticsearch 集群内置了以下常用的插件，暂不支持用户自己安装。

+ `analysis-icu <https://github.com/elastic/elasticsearch-analysis-icu>`_ ：使用 ICU 实现的一个针对亚洲语言的分词器插件。

  .. code-block:: console

      $ curl -XGET 'https://es.sinacloud.com/aktestes1234_hellosae/_analyze?pretty' -d '{"tokenizer": "icu_tokenizer","text": "虫洞是宇宙中可能存在的连接两个不同时空的狭窄隧道"}' -u 'testes1234:i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc'

+ `analysis-smartcn <https://github.com/elastic/elasticsearch-analysis-smartcn>`_ ：针对中文或中英文混合的文本分词器插件。

  .. code-block:: console

      $ curl -XGET 'https://es.sinacloud.com/aktestes1234_hellosae/_analyze?pretty' -d '{"analyzer": "smartcn","text": "虫洞是宇宙中可能存在的连接两个不同时空的狭窄隧道"}' -u 'testes1234:i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc'

      # 也可以通过下述命令指定type某个字段的分词器
      $ curl -XPUT 'https://es.sinacloud.com/aktestes1234_hellosae/_mapping/people' -u'testes1234:i4mjh1hw4ds1103dk5m2d55l4ff44t424flkf4dc' -d'{"properties":{"msg":{"type":"string", "analyzer": "smartcn"}}}'

+ `elasticsearch-head <https://github.com/mobz/elasticsearch-head>`_ ：一个开源的 Web 管理工具。

  访问地址： https://es.sinacloud.com/_plugin/head/


错误说明
=========


+ 限制的功能会以如下形式的错误返回

.. code-block:: json

 {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"No feature for name [_search template]"}],"type":"illegal_argument_exception","reason":"No feature for name [_search template]"},"status":400}


+ 容量超配会以如下形式的错误返回

.. code-block:: json

 {"error":{"root_cause":[{"type":"index_over_quota_exception","reason":"Over quota for index [your index]"}],"type":"index_over_quota_exception","reason":"Over quota for index [your index]"},"status":400}