elasticsearch-elixir/guides/upgrading/0.2.x_to_0.3.x.md

Upgrading from 0.2.x to 0.3.x

Version 0.3.0 dropped support for some Elasticsearch 5.x features that have been deprecated or removed in Elasticsearch 6.x.

Rationale

As noted in the Elasticsearch document "Removal of mapping types", Elasticsearch no longer supports multiple document types per index.

Instead, each index is expected to have a single type, _doc, and handle parent/child relationships with the new join field.

To support this, version 0.3.0 of this client library makes some breaking changes. You should still be able to use 0.3.0 with Elasticsearch 5.x, but you will need to convert your indexes over to the 6.x style if they aren't designed that way already.

Changes

BREAKING: Removed type and parent functions from Elasticsearch.Document protocol.

BREAKING: Required cluster as an argument to Index.Bulk.encode functions.

BREAKING: mix elasticsearch.build, Index.hot_swap/5 and Bulk.upload/5 will post documents to /index_name/_doc/_bulk, therefore assuming that your index's only type is named _doc. (As shown in all Elasticsearch sample documentation)

IMPROVED: Bulk.upload/5 now respects your cluster's :bulk_wait_interval setting. This allows you to space your requests to prevent overloading your Elasticsearch cluster.

IMPROVED: Test coverage was increased to 93%.

FIXED: Bulk.upload/5 now properly handles errors on repeated runs. See infinitered/elasticsearch-elixir#10

How to Update Your App

First, remove type and parent definitions from all your implementations of Elasticsearch.Document:

# BEFORE
defimpl Elasticsearch.Document, for: MyApp.Struct do
  def type(struct), do: "struct"
  def parent(_struct), do: false
  def id(struct), do: struct.id
  def encode(struct) do
    %{
      # ...
    }
  end
end

# AFTER
defimpl Elasticsearch.Document, for: MyApp.Struct do
  def id(struct), do: struct.id
  def encode(struct) do
    %{
      # ...
    }
  end
end

Next, if you call Bulk.encode functions manually, be sure to pass your cluster into them.

# BEFORE
Bulk.encode(%MyApp.Struct{}, "index_name")

# AFTER
Bulk.encode(MyApp.ElasticsearchCluster, %MyApp.Struct{}, "index_name")

Next, update your index structure to no longer have multiple types per index in your index settings .json files. Also, rename your type to _doc.

# BEFORE
{
  "mappings": {
    "post": {
      "properties": {
        "title": {
          "type": "text"
        },
        "author": {
          "type": "text"
        }
      }
    }
  }
}

# AFTER
{
  "mappings": {
    "_doc": {
      "properties": {
        "title": {
          "type": "text"
        },
        "author": {
          "type": "text"
        }
      }
    }
  }
}