The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Elastic-Model-0.51
River stage one • 1 direct dependent • 1 total dependent
10 ++
/ Elastic::Model::Role::Model

NAME

Elastic::Model::Role::Model - The role applied to your Model

VERSION

version 0.51

SYNOPSIS

    use MyApp;

    my $es         = Search::Elasticsearch->new( nodes => 'es.domain.com:9200' );
    my $model      = MyApp->new( es => $es );

    my $namespace  = $model->namespace('myapp');
    my $domain     = $model->domain('my_domain');
    my $view       = $model->view();

    my $scope      = $model->new_scope;

DESCRIPTION

A "Model" is the Boss Object, which ties an instance of your application to a particular Elasticsearch cluster. You can have multiple instances of your Model class which connect to different clusters.

Elastic::Model::Role::Model is applied to your Model class when you include the line:

    use Elastic::Model;

See Elastic::Model for more about how to setup your Model class.

COMMONLY USED METHODS

new()

Usually, the only parameter that you need to pass to new() is es, which contains your Search::Elasticsearch connection.

    $es    = Search::Elasticsearch->new( nodes => 'es1.domain.com:9200' );
    $model = MyApp->new( es => $es );

If the es parameter is omitted, then it will default to a Search::Elasticsearch connection to localhost:9200.

    $model = MyApp->new();   # localhost:9200

namespace()

    $namespace = $model->namespace($name);

Returns the Elastic::Model::Namespace instance corresponding to $name. The namespace must have been configured via "has_namespace" in Elastic::Model.

Use a $namespace to create, delete and update indices and index aliases.

domain()

    $domain = $model->domain($name);

Returns an Elastic::Model::Domain instance where $name is the name of an index or index alias (which points at a single index) and is known to one of the "namespaces".

Use a $domain to create, retrieve, update or delete individual objects/documents.

view()

    $view = $model->view(%args);

Creates a new Elastic::Model::View instance. Any args are passed on to "new()" in Elastic::Model::View.

Use a $view to query your documents. Views can be multi-domain and multi-type.

new_scope()

    $scope = $model->new_scope();

Creates a new Elastic::Model::Scope instance (in-memory cache). If there is an existing scope, then the new scope inherits from the existing scope.

    $scope = $model->new_scope();   # scope_1
    $scope = $model->new_scope();   # scope_2, inherits from scope_1
    undef $scope;                   # scope_2 and scope_1 are destroyed

Scopes are optional unless you have attributes which are weakened.

See Elastic::Model::Scoping and Elastic::Model::Scope to read more about how scopes work.

OTHER METHODS AND ATTRIBUTES

These methods and attributes, while public, are usually used only by internal modules. They are documented here for completeness.

CRUD

get_doc()

Normally, you want to use "get()" in Elastic::Model::Domain rather than this method.

    $doc = $model->get_doc(uid => $uid);
    $doc = $model->get_doc(uid => $uid, ignore => 404, ...);

get_doc() tries to retrieve the object corresponding to the $uid, first from the "current_scope()" (if there is one) or from any of its parents. Failing that, it tries to retrieve the doc from the "store". If it finds the doc, then it stores it in the current scope (again, if there is one), otherwise it throws an error.

get_doc() also accepts an optional $source parameter which is used internally for inflating search results. See Elastic::Model::Scope for a more detailed explanation.

Any other args are passed on to "get_doc()" in Elastic::Model::Store.

get_doc_source()

    $doc = $model->get_doc_source(uid => $uid);
    $doc = $model->get_doc_source(uid => $uid, ignore => 404, ...);

Calls "get_doc()" in Elastic::Model::Store and returns the raw source hashref as stored in Elasticsearch for the doc with the corresponding $uid. Throws an error if it doesn't exist.

Any other args are passed on to "get_doc()" in Elastic::Model::Store.

doc_exists()

    $bool = $model->doc_exists( uid => $uid, %args );

Calls "doc_exists()" in Elastic::Model::Role::Store to check whether the doc exists.

save_doc()

Normally, you want to use "save()" in Elastic::Model::Role::Doc rather than this method.

    $doc = $model->save_doc(doc => $doc, %args);

Saves $doc to Elasticsearch by calling "index_doc()" in Elastic::Model::Store (if the $doc was originally loaded from Elasticsearch), or "create_doc()" in Elastic::Model::Store, which will throw an error if a doc with the same index|type|id already exists.

Any %args are passed on to index_doc() or create_doc().

If there is a "current_scope()" then the object is also stored there.

Also see the "on_conflict" in Elastic::Model::Role::Doc and "on_unique" in Elastic::Model::Role::Doc parameters.

delete_doc()

    $uid = $model->delete_doc(uid => $uid, ignore => 404, ...)

Calls "delete_doc()" in Elastic::Model::Store and returns the updated Elastic::Model::UID object. Throws an error if it doesn't exist. If there is a "current_scope()" then an Elastic::Model::Deleted object is stored there.

search()

Normally, you want to use Elastic::Model::View rather than this method.

    $results = $model->search(%args)

Passes %args through to "search()" in Elastic::Model::Store

new_partial_doc()

    part_doc = $model->new_partial_doc(
        uid            => $uid,
        partial_source => \%source
    );

Creates an instance of a partial doc (ie an object which contains only some of the values stored in Elasticsearch). These partial docs are useful when your objects are large, and you need to display search results which require only a few attributes, instead of the whole object.

Attempting to save a partial doc will cause an error to be thrown.

You shouldn't need to call this method yourself.

bulk()

Returns a new instance of Elastic::Model::Bulk for fast indexing of multiple docs in batches.

    $bulk = $model->bulk(
        size        => 1000,
        on_conflict => sub {...},
        on_error    => sub {...},
        on_success  => sub {...}
    );

Miscellaneous

namespaces

    \%namespaces = $model->namespaces;

A hashref whose keys are the namespace names, and whose values are the corresponding Elastic::Model::Namespace instances.

namespace_for_domain()

    $namespace = $model->namespace_for_domain($domain_name)

Returns the Elastic::Model::Namespace object which corresponds to the $domain_name. If the index (or alias) name is not yet known to the $model, it will update the known domain list from the namespace objects.

all_live_indices()

    @indices = $model->all_live_indices();

Queries Elasticsearch to find all existing indices related to all namespaces known to the model.

es

    $es = $model->es

Returns the Search::Elasticsearch instance that was passed to "new()".

store

    $store = $model->store

Returns the Elastic::Model::Store instance.

Deflation, Inflation And Mapping

typemap

    $typemap_class = $model->typemap;

Elastic::Model uses Elastic::Model::TypeMap::Default (after wrapping it) to figure out how to deflate and inflate your objects, and how to configure (map) them in Elasticsearch.

You can specify your own type-map class in your model configuration with has_typemap. See Elastic::Model::TypeMap::Base for instructions on how to define your own type-map classes.

deflator_for_class()

    $deflator = $model->deflator_for_class($class);

Returns a code-ref that knows how to deflate a class which does Elastic::Model::Role::Doc, and caches the deflator in "deflators".

deflate_object()

    $hash = $model->deflate_object($object);

Uses the deflator returned by "deflator_for_class()" to deflate an object which does Elastic::Model::Role::Doc into a hash ref suitable for conversion to JSON.

deflators

    $deflators = $model->deflators

A hashref which caches all of the deflators which have been generated by "deflator_for_class()".

inflator_for_class()

    $inflator = $model->inflator_for_class($class);

Returns a code-ref that knows how to inflate a plain hashref into the correct attribute values for a class which does Elastic::Model::Role::Doc, and caches the inflator in "inflators".

inflate_object()

    $object = $model->inflate_object($object,$hash);

Uses the inflator returned by "inflator_for_class()" to inflate the attribute values of $object from the value stored in $hash.

inflators

    $inflators = $model->inflators

A hashref which caches all of the inflators which have been generated by "inflator_for_class()".

map_class()

    $mapping = $model->map_class($class);

Returns the type mapping / schema for a class which does Elastic::Model::Role::Doc, suitable for passing to Elasticsearch.

Scoping

Also see "new_scope()" and Elastic::Model::Scope.

current_scope()

    $scope = $model->current_scope($scope);

Read/write accessor for the current scope. Throws an exception if no scope is currently set.

detach_scope()

    $model->detach_scope($scope);

Removes the passed in $scope if it is the current scope. Replaces the current scope with its parent scope, if there is one. "detach_scope()" is called automatically when a scope goes out of scope:

    {
        my $scope = $model->new_scope;
        # do work
    }
    # current scope is removed

has_current_scope()

    $bool = $model->has_current_scope

Returns a true or false value signalling whether a "current_scope()" exists.

clear_current_scope()

    $model->clear_current_scope

Clears the "current_scope()"

Core classes

The following core classes are used internally by Elasticsearch, after being wrapped by "wrap_class()", which pins the new anonymous class to the current $model instance. An instance of the wrapped class can be created with, eg:

    $domain = $model->domain_class->new(%args);

If you would like to override any of the core classes, then you can specify them in your model setup using override_classes.

Default core classes:

wrap_class()

    $wrapped_class = $model->wrap_class($class)

Wraps a class in an anonymous class and adds two methods: model() (which returns the current $model instance, and original_class()), which returns the name of the wrapped class:

    $model = $wrapped_class->model
    $class = $wrapped_class->original_class;

wrap_doc_class()

Like "wrap_class()", but specifically for classes which do Elastic::Model::Role::Doc.

doc_class_wrappers

    $wrapped_classes = $model->doc_class_wrappers

A hashref of all wrapped doc classes (ie those classes which do Elastic::Model::Role::Doc). The keys are the original class names, and the values are the wrapped class names.

class_for()

    $wrapped_class = $model->class_for($class);

Returns the name of the wrapped class which corresponds to $class.

knows_class()

    $bool = $model->knows_class($class);

Returns a true or false value to signal whether doc $class has been wrapped.

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.