Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Track unique keys in ElasticSearch

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 t
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 Changes
Octocat-spinner-32 README.pod
Octocat-spinner-32 dist.ini
README.pod

DESCRIPTION

The only unique key available in Elasticsearch is the document ID. Typically, if you want a document to be unique, you use the unique value as the ID. However, sometimes you don't want to do this. For instance, you may want to use the email address as a unique identifier for your user accounts, but you also want to be able to link to a user account without exposing their email address.

ElasticSearchX::UniqueKey allows you to keep track of unique values by maintaining a dedicated index which can contain multiple types. Each type represents a different key name (so a single index can be used to track multiple unique keys).

SYNOPSIS

    use Search::Elasticsearch::Compat();
    use ElasticSearchX::UniqueKey();

    my $es   = Search::Elasticsearch::Compat->new();
    my $uniq = ElasticSearchX::UniqueKey->new( es => $es );

    $uniq->bootstrap();

    $created = $uniq->create( $key_name, $key_id );
    $deleted = $uniq->delete( $key_name, $key_id );
    $exists  = $uniq->exists( $key_name, $key_id );
    $updated = $uniq->update( $key_name, $old_id, $new_id );

    %failed  = $uniq->multi_create(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    );

    $uniq->multi_delete(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    )

    %failed = $uniq->multi_update(
        { key_1 => 'old', key_2 => 'old' },
        { key_1 => 'new', key_2 => 'new' },
    );

    %failed  = $uniq->multi_exists(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    );

    $uniq->delete_index;
    $uniq->delete_type( $key_name );

METHODS

new()

    my uniq = ElasticSearchX::UniqueKey->new(
        es      => $es,         # Search::Elasticsearch::Compat instance, required
        index   => 'index',     # defaults to 'unique_key',
    );

new() returns a new instance of ElasticSearchX::UniqueKey. The unique keys are stored in the specified index, which is setup to be very efficient for this purpose, but not useful for general storage.

You must call "bootstrap()" to create your index before first using it, otherwise it will not be setup correctly. See "bootstrap()" for how to initiate your index.

You don't need to setup your key_names (ie your types) - these will be created automatically.

create()

    $created = $uniq->create( $key_name, $key_id );

Returns true if the key_name/key_id combination didn't already exist and it has been able to create it. Returns false if it already exists.

delete()

    $deleted = $uniq->delete( $key_name, $key_id );

Returns true if the key_name/key_id combination existed and it has been able to delete it. Returns false if it didn't already exist.

exists()

    $exists = $uniq->exists( $key_name, $key_id );

Returns true or false depending on whether the key_name/key_id combination exists or not.

update()

    $updated = $uniq->update( $key_name, $old_id, $new_id );

First tries to create the new combination key_name/new_id, otherwise returns false. Once created, it then tries to delete the key_name/old_id, and returns true regardless of whether it existed previously or not.

multi_create()

    %failed = $uniq->multi_create(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    );

Use "multi_create()" to create several entries at the same time (each $key_name must be different). If it fails to create all the entries, then it will remove any entries that it succeeded in creating, and return a hash of the entries which failed.

multi_delete()

    $uniq->multi_delete(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    );

Use "multi_delete()" to delete several entries at the same time (each $key_name must be different). Returns 1 whether the entries exist or not.

multi_update()

    %failed = $uniq->multi_update( \%old, \%new );

"multi_update()" first tries to create the new keys, then deletes the old keys. Returns a hash of any entries that couldn't be created.

multi_delete()

    %failed = $uniq->multi_exists(
        $key_name_1 => $key_id_1,
        $key_name_2 => $key_id_2,
    );

Returns a hash of any entries that don't exist.

bootstrap()

    $uniq->bootstrap( %settings );

This method will create the index, if it doesn't already exist. By default, the index is setup with the following %settings:

    (
        number_of_shards     => 1,
        auto_expand_replicas => '0-all',
    )

In other words, it will have only a single primary shard (instead of the Elasticsearch default of 5), and a replica of that shard on every Elasticsearch node in your cluster.

If you pass in any %settings then the defaults will not be used at all.

See Index Settings for more.

delete_index()

    $uniq->delete_index()

Deletes the index. You will lose your data!

delete_type()

    $uniq->delete_type( $key_name )

Deletes the type associated with the key_name. You will lose your data!

index()

    $index = $uniq->index

Read-only getter for the index value

es()

    $es = $uniq->es

Read-only getter for the Search::Elasticsearch::Compat instance.

SEE ALSO

Search::Elasticsearch::Compat
Elastic::Model
http://www.elasticsearch.org

BUGS

This is a new module, so there will probably be bugs, and the API may change in the future.

If you have any suggestions for improvements, or find any bugs, please report them to http://github.com/clintongormley/ElasticSearchX-UniqueKey/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TEST SUITE

The full test suite requires a live Elasticsearch cluster to run. CPAN testers doesn't support this. You can see full test results here: http://travis-ci.org/#!/clintongormley/ElasticSearchX-UniqueKey/builds.

To run the full test suite locally, run it as:

    perl Makefile.PL
    ES_HOME=/path/to/elasticsearch make test

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc ElasticSearchX::UniqueKey

You can also look for information at:

Something went wrong with that request. Please try again.