Index API

Index API 用於在指定索引中添加或更新類型化的JSON文檔,使其成爲可搜索的。 如下示例將JSON文檔插入「twitter」索引中,類型名爲「_doc」,ID爲1:html

PUT twitter/_doc/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

返回結果以下:數據庫

{
  "_index": "twitter",
  "_type": "_doc",
  "_id": "1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

_shards頭提供關於索引操做的複製過程的信息。api

  • total - 表示執行索引操做的分片副本(主和副本分片)的數量。
  • successful - 表示索引操做成功的分片數量。
  • failed - 在副本分片上的索引操做失敗的狀況下,包含複製相關錯誤的數組。

在successful至少爲1的狀況下,索引操做纔會成功。數組

當索引操做成功返回時(默認狀況下,只須要主分片,但能夠更改此行爲),副本分片可能不會都啓動。 在這種狀況下,總數將等於number_of_replicas設置的總分片數,成功數將等於啓動的分片數(primary + replicas)。 若是沒有失敗,失敗將爲0。併發

自動建立索引

若是以前沒有建立索引,索引操做會自動建立一個索引(查看create index API 瞭解如何手動建立索引)。還會爲指定類型自動建立(查看put mapping API瞭解如何手動建立類型映射)一個動態類型映射(若是還沒有建立的話)。app

映射自己很是靈活而且無模式(schema-free)。新的字段和對象將自動添加到指定類型的映射定義中。查看映射部分以獲取更多關於映射定義的信息。
自動索引建立能夠經過在全部節點的配置文件中設置 action.auto_create_index=false 來禁用。設置 index.mapper.dynamic=false能夠禁用自動建立映射。異步

自動索引建立能夠包括基於模式的白/黑名單,例如,設置  action.auto_create_index 爲+aaa*, -bbb*,+ccc*,-*(+表示容許,- 意爲不容許)。elasticsearch

版本控制

每一個索引文檔都有一個版本號。 關聯的版本號做爲響應的一部分返回。 當指定版本參數時,索引API能夠選擇性地容許進行樂觀併發控制。 這就能夠控制將要執行的操做的文檔版本。版本控制一個很好的例子就是執行事務(讀取而後更新)。 指定最初讀取的文檔中的版本可確保在此期間未發生任何更改(若是讀取是爲了更新,建議在查詢時設置preference=_primary)。 例如:ide

PUT twitter/_doc/1?version=2
{
    "message" : "elasticsearch now has versioning support, double cool!"
}
GET twitter/_doc/1?preference=_primary

注意:版本控制是徹底實時的,而且不受搜索操做的近實時方面的影響。若是沒有提供版本,則操做在沒有任何版本檢查的狀況下執行。函數

默認狀況下,使用內部版本控制,從1開始,每次增長或刪除就加1。版本號也能夠用外部值補充(例如保存在數據庫中)。要啓用此功能,應設置 version_type=external 。提供的值必須是numeric, long類型的,且值必須是大於或等於0且小於大約9.2e + 18的。在使用外部版本類型時,系統會檢查傳遞給索引請求的版本號是否大於當前存儲的文檔的版本號,而不是檢查是否匹配版本號。若是爲true,則文檔將被索引並使用新版本號。若是提供的值小於或等於存儲文檔的版本號,則會發生版本衝突,索引操做將失敗。

外部版本控制支持將值0做爲有效的版本號。 這容許版本與外部版本控制系統同步(好比版本號從0開始而不是1的系統)。壞處是版本號等於零的文檔不能使用Update-By-Query API更新,也不能使用Delete By Query API進行刪除。

好處是隻要使用源數據庫的版本號,就不須要因源數據庫更改而執行的異步索引操做進行嚴格排序。 若是使用外部版本控制,即便是使用數據庫中的數據更新Elasticsearch索引也會獲得簡化,由於若是索引操做出現故障,則只會使用最新版本。

版本類型

上面已經解釋了internal & external 版本類型,Elasticsearch還支持針對特定用例的其餘類型。如下是不一樣版本類型及其語義的概述。
internal:若是給定版本與存儲文檔的版本相同,則索引文檔。
external or external_gt:若是給定版本嚴格高於存儲文檔的版本或者文檔不存在,則索引文檔。 給定的版本將用做新版本,並將與新文檔一塊兒存儲。 提供的版本必須是非負數長整數。
external_gte:若是給定版本等於或高於存儲文檔的版本,則索引文檔。 若是文檔不存在,操做也會成功。 給定的版本將用做新版本,並將與新文檔一塊兒存儲。 提供的版本必須是非負數長整數。
注:external_gte版本類型只適用於特殊用途,應謹慎使用。 若是使用不當,可能會致使數據丟失。 還有另外一個選項force,因爲它可能致使主分片和副本分片不一致,所以不推薦使用。

操做類型

索引操做還接受可用於強制執行建立操做的op_type,從而容許「若是不存在就添加」行爲。 使用create時,若是索引中已存在由該id建立的文檔,則索引操做將失敗。

如下是使用op_type參數的示例:

PUT twitter/_doc/1?op_type=create
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

也能夠像下面這樣指定create:

PUT twitter/_doc/1/_create
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

自動生成ID

索引操做能夠在不指定id的狀況下執行。 它會自動生成一個id。 另外,op_type會自動設置爲create。 如下是一個例子(注意使用POST而不是PUT):

POST twitter/_doc/
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

結果以下:

{
  "_index": "twitter",
  "_type": "_doc",
  "_id": "gplwqWIB8vjrkQCAPbbJ",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

路由

默認狀況下,分片放置或路由經過文檔的id值的hash進行控制。 爲了更明確的控制,路由使用的哈希函數中引入的值可使用路由參數直接指定。 例如:

POST twitter/_doc?routing=kimchy
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

在上面的示例中,「_doc」文檔根據提供的路由參數:「kimchy」 被路由到一個分片。

設置顯式映射時,能夠選擇使用_routing字段來指示索引操做從文檔自己提取路由值。 這會額外增長文檔解析開銷,不過成本很是小。 若是_routing映射被定義並被設置爲必需的,那麼若是路由值未提供或未提取到路由值,則索引操做將失敗。

分步式

索引操做根據其路由(參見上面的路由部分)指向主分片,並在包含此分片的實際節點上執行。 在主分片完成操做後,若是須要,更新將分發到相應的副本。

等待活動分片

爲了提升寫入系統的靈活性,索引操做能夠配置爲在繼續操做以前等待必定數量的活動分片副本。 若是所需數量的活動分片副本不可用,則寫入操做必須等待並重試,直到必要的分片副本已啓動或發生超時。 默認狀況下,寫入操做僅等待主分片在進行以前處於活動狀態(即wait_for_active_shards = 1)。 經過設置index.write.wait_for_active_shards,能夠在索引設置中動態覆蓋此默認值。 要改變每一個操做的這種行爲,可使用wait_for_active_shards請求參數。

有效值爲所有或任何正整數,直到索引中每一個分片的配置副本總數(即number_of_replicas + 1)。指定負值或大於分片數量的數字將引起錯誤。

例如,假設咱們有一個由三個節點A,B和C組成的集羣,而且咱們建立了一個索引index,其副本數設置爲3(致使4個分片副本,比節點多一個副本)。若是咱們嘗試進行索引操做:
一、默認狀況下,操做只會確保每一個分片的主分片可用,而後才能繼續。這意味着,即便B和C發生故障,而且A託管了主分片副本,索引操做仍然會繼續執行這惟一的一個數據副本。
二、若是請求中的wait_for_active_shards設置爲3(而且全部3個節點都在運行),那麼索引操做在繼續以前須要3個活動分片副本,知足要求,由於集羣中有3個活動節點,每一個節點持有分片的副本。
三、若是咱們將wait_for_active_shards設置爲all(或者4也同樣),則索引操做將不會繼續,由於咱們沒有在索引中激活每一個分片的全部4個副本。該操做將超時,除非在集羣中引入新節點來託管分片的第四個副本。
值得注意的是,這種設置大大下降了寫操做不寫入所需數量的分片副本的可能性,但它並不能徹底消除這種可能性,由於在寫操做開始以前就會發生這種檢查。 一旦寫入操做正在進行,複製仍然有可能在任意數量的分片副本上失敗,但仍然能夠在主分片上成功。 寫操做響應的_shards部分會顯示覆製成功/失敗的分片副本的數量。

{
    "_shards" : {
        "total" : 2,
        "failed" : 0,
        "successful" : 2
    }
}

刷新

控制此請求所作的更改對搜索是否可見。 請參閱刷新

Noop Updates

使用索引api更新文檔時,即便文檔未更改,也始終建立新版本的文檔。 若是不想這樣,可使用_update api,把detect_noop設置爲true。 這個選項在索引api上不可用,由於索引api沒有獲取舊的數據,也沒法將它與新的數據進行比較。

關於Noop Updates什麼時候不可接受,並無一條硬性規定。 這是多種因素的結合,例如數據源發送更新的頻率其實是noops,以及Elasticsearch每秒接收更新時在分片上運行的查詢數量。

Timeout

執行索引操做時,分配用於執行索引操做的主分片可能不可用。 形成這種狀況的一些緣由多是主分片正在從網關恢復或正在進行遷移。 默認狀況下,索引操做將在主分片上等待最多1分鐘,而後若是失敗則響應並顯示錯誤。 timeout參數可用於顯式指定它等待的時間。 如下是將其設置爲5分鐘的示例:

PUT twitter/_doc/1?timeout=5m
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}

官方文檔:https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html

相關文章
相關標籤/搜索