NAME
    ElasticSearchX::UniqueKey - Track unique keys in ElasticSearch

VERSION
    version 0.05

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 );

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).

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
    <http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/i
    ndices-update-settings.html> 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:

    *   GitHub

        <http://github.com/clintongormley/ElasticSearchX-UniqueKey>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/ElasticSearchX-UniqueKey>

    *   Search MetaCPAN

        <https://metacpan.org/module/ElasticSearchX::UniqueKey>

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.