NAME

Elastic::Model::UID - The Unique ID of a document in an Elasticsearch cluster

VERSION

version 0.29_2

SYNOPSIS

$doc = $domain->new_doc(
    $type => {
        id      => $id,             # optional
        routing => $routing,        # optional
        ....
    }
);

$doc = $domain->get( $type => $id                      );
$doc = $domain->get( $type => $id, routing => $routing );

$uid = $doc->uid;

$index   = $uid->index;
$type    = $uid->type;
$id      = $uid->id;
$version = $uid->version;
$routing = $uid->routing;

DESCRIPTION

To truly identify a document as unique in Elasticsearch, you need to know the index where it is stored, the type of the document, its id, and possibly its routing value (which defaults to the ID). Also, each object has a "version" number which is incremented on every change. Elastic::Model::UID wraps up all of these details into an object.

ATTRIBUTES

index

The index (or domain) name. When you create a new document, its UID will set index to $domain->name, which may be an index or an index alias. However, when you save the document, the "index" will be updated to reflect the actual index name.

type

The type of the document, eg user.

id

The string id of the document - if not set when creating a new document, then a unique ID is auto-generated when the document is saved.

routing

The routing string is used to determine in which shard the document lives. If not specified, then Elasticsearch generates a routing value using a hash of the ID. If you use a custom routing value, then you can't change that value as the new routing may point to a new shard. Instead, you should delete the old doc, and create a new doc with the new routing value.

version

The version is an integer representing the current version of the document. Each write operation will increment the version, and attempts to update an older version of the document will throw an exception.

from_store

A boolean value indicating whether the UID was loaded from Elasticsearch (true) or created via "new()".

is_partial

A boolean value indicating whether the UID represents a partial or full object. Partial objects cannot be saved.

cache_key

A generated string combining the "type" and the "id"

METHODS

new()

$uid = Elastic::Model::Uid->new(
    index   => $domain->name,               # required
    type    => $type,                       # required
    id      => $id,                         # optional
    routing => $routing,                    # optional
);

Creates a new UID with "from_store" set to false.

new_from_store()

$uid = Elastic::Model::UID->new_from_store(
    _index   => $index,
    _type    => $type,
    _id      => $id,
    _version => $version,
    fields   => { routing => $routing }
);

This is called when creating a new UID for a doc that has been loaded from Elasticsearch. You shouldn't need to use this method directly.

new_partial()

$uid = Elastic::Model::UID->new_partial(
    _index   => $index,
    _type    => $type,
    _id      => $id,
    _version => $version,
    fields   => { routing => $routing }
);

This is called when creating a new UID for a partial doc that has been loaded from Elasticsearch. You shouldn't need to use this method directly.

clone()

$new_uid = $uid->clone();

Clones an existing UID.

update_from_store()

$uid->update_from_store(
    _index   => $index,
    _id      => $id,
    _version => $version,
);

When a doc is saved, we update the UID to use the real index name (as opposed to an alias or domain name), the ID (in case it has been auto-generated) and the current version number. It also sets the "from_store" attribute to true. You shouldn't need to use this method directly.

update_from_uid()

$uid->update_from_uid($new_uid);

Updates the "index", "routing" and "id" parameters of one UID from a newer UID. You shouldn't need to use this method directly.

read_params()

$params = $uid->read_params()

Returns a hashref containing "index", "type", "id" and "routing" values.

write_params()

$params = $uid->write_params()

Returns a hashref containing "index", "type", "id", "routing" and "version" values.

AUTHOR

Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.

cpanm Elastic::Model

perl -MCPAN -e shell
install Elastic::Model