NAME

Elastic::Manual::Delta - Important changes in Elastic::Model

VERSION

version 0.52

DESCRIPTION

This documents any important or noteworthy changes in Elastic::Model, with a focus on things that affect backwards compatibility. This does duplicate data from the Changes file, but aims to provide more details and when possible workarounds.

0.52

Elastic::Model is not compatible with Elasticsearch 2.x. Search::Elasticsearch, however, defaults to using a 2.x compatible client: 2_0::Direct. You should specify the client version explicitly when creating a Search::Elasticsearch instance:

use Search::Elasticsearch;
use MyApp;

my $es = Search::Elasticsearch->new(
    client => '1_0::Direct', #### explicit client ####
    nodes  => [ "192.168.1.100:9200", "192.168.1.101:9200"]
);

my $model = MyApp->new( es => $es )

0.51

Requires Search::Elasticsearch v1.20 or above. Tested on Elasticsearch v1.6

0.50

This is the first version which supports the 1.x releases of Elasticsearch, and it provides a migration path from the 0.90.x releases of Elasticsearch.

Search::Elasticsearch

You can no longer use the temporary Search::Elasticsearch::Compat client with Elastic::Model. Instead, use the official Search::Elasticsearch client:

use Search::Elasticsearch;
use MyApp;

my $es = Search::Elasticsearch->new(
    client => '1_0::Direct',
    nodes  => [ "192.168.1.100:9200", "192.168.1.101:9200"]
);

my $model = MyApp->new( es => $es )

Migrating from 0.90.x to 1.x

You cannot mix nodes from 0.90.x with nodes from 1.x. This leaves you with two options:

• Shutdown the 0.90.x cluster and replace it with a 1.x cluster.

• Run two clusters in parallel during the transition period.

Either way, the migration path available in Elastic::Model v0.50 will help you through the transition.

You can enable a "compatibility mode" which will allow you to use the same code on 0.90.x and on 1.x by telling the Search::Elasticsearch module to use the 0_90::Client:

use Search::Elasticsearch;
use MyApp;

my $es = Search::Elasticsearch->new(
    nodes  => [ "192.168.1.100:9200", "192.168.1.101:9200"],
    client => '0_90::Client'
);

my $model = MyApp->new( es => $es )

If you are planning on running two clusters in parallel, then you can specify a mixture of nodes from the 0.90.x cluster and the 1.x cluster in the nodes list. The client will use whatever nodes are available. This allows you to start with just the 0.90.x cluster, bring up the 1.x cluster (it will talk to both clusters), then take down the 0.90.x cluster.

Once the migration is finished, remove the `0_90::Client` and the 0.90.x nodes and the compatibility mode will be disabled.

IMPORTANT: If you writing to your index during transition, it is up to you to ensure that writes go to both clusters. A safer approach is to only allow reads during the transition phase.

NOTE: While compatibility mode is enabled, include_paths and exclude_paths (see "include_paths / exclude_paths" in Elastic::Model::View) will be ignored. Instead of retrieving just the paths specified, it will retrieve the whole document.

ignore_missing

The ignore_missing parameter is deprecated and should be replaced by, eg:

$namespace->index('foo')->delete(ignore => 404);

For now, ignore_missing will be translated to ignore => 404 but will warn about deprecation.

omit_norms and omit_term_freq_and_positions

These two options have been removed from Elasticsearch and replaced by the following mapping:

{ "my_string_field": {
  "type":          "string",
  "norms":       { "enabled": "false" },
  "index_options": "docs"
}}

These options were most useful for not_analyzed fields, but they are no longer required as they are now the default settings for not_analyzed fields. If you want to apply these settings to an analyzed string field, you can do so as follows:

has 'name' => (
    is      => 'rw',
    isa     => 'Str',
    type    => 'string',
    mapping => {
        norms         => { enabled => 0 },
        index_options => 'docs'
    }
);

Responses from Elasticsearch

Some response formats have changed in Elasticsearch. The structure of the get-mapping and get-settings responses have changed, responses no longer include the ok key, and the exists has been replaced by found. The field values are now returned as arrays rather than scalars.

Compatibility mode makes some effort to normalize responses between 0.90.x and 1.x, but you should test your code on 1.x before migrating.

Scripting

Mvel is no longer enabled by default in Elasticsearch, and in 1.4 it will be removed. However, the new scripting language (Groovy, which is available in 1.3 and will become the default in 1.4) is not available in 0.90.x. To aid migration, you should reenable Mvel scripting during transition. Once complete, update all scripts to use Groovy instead.

See http://www.elasticsearch.org/blog/scripting/ for more.

Queries

Some queries have been removed in 1.x. The text, text_phrase, and text_phrase_prefix queries have been replaced by match, match_phrase, and match_phrase_prefix.

The custom_score, custom_boost_factor, and custom_filters_score queries have been replaced by the function_score query.

The numeric_range filter no longer exists.

Elastic::Model::SearchBuilder supports the match* queries but still needs to be updated to support the function_score query. In the meantime, you can use the "raw" syntax. See "RAW-ELASTICSEARCH-QUERY-DSL" in ElasticSearch::SearchBuilder.

Aggregations

Aggregations are now supported (see "aggs" in Elastic::Model::View) but only in Elasticsearch 1.0 and above.

Field attribute deprecations

The following attribute deprecations are deprecated and will be removed in a future version:

• field boost

• index_name

• precision_step

• path

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Clinton Gormley.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.