File Coverage

blib/lib/MongoDB/IndexView.pm

Criterion	Covered	Total	%
statement	36	96	37.5
branch	0	30	0.0
condition	0	6	0.0
subroutine	12	24	50.0
pod	5	5	100.0
total	53	161	32.9

#  Copyright 2015 - present MongoDB, Inc.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

use strict;
use warnings;
package MongoDB::IndexView;

# ABSTRACT: Index management for a collection

use version;
our $VERSION = 'v2.2.0';

use Moo;
use MongoDB::Error;
use MongoDB::Op::_CreateIndexes;
use MongoDB::Op::_DropIndexes;
use MongoDB::ReadPreference;
use MongoDB::_Types qw(
    BSONCodec
    IxHash
    is_IndexModelList
    is_OrderedDoc
);
use Types::Standard qw(
    InstanceOf
    Str
    is_Str
);
use boolean;
use namespace::clean -except => 'meta';

#pod =attr collection
#pod
#pod The L for which indexes are being created or viewed.
#pod
#pod =cut

#--------------------------------------------------------------------------#
# constructor attributes
#--------------------------------------------------------------------------#

has collection => (
    is       => 'ro',
    isa      => InstanceOf( ['MongoDB::Collection'] ),
    required => 1,
);

#--------------------------------------------------------------------------#
# private attributes
#--------------------------------------------------------------------------#

has _bson_codec => (
    is      => 'lazy',
    isa     => BSONCodec,
    builder => '_build__bson_codec',
);

sub _build__bson_codec {
    my ($self) = @_;
    return $self->collection->bson_codec->clone( ordered => 1 );
}

has _client => (
    is      => 'lazy',
    isa     => InstanceOf( ['MongoDB::MongoClient'] ),
    builder => '_build__client',
);

sub _build__client {
    my ($self) = @_;
    return $self->collection->client;
}

has _coll_name => (
    is      => 'lazy',
    isa     => Str,
    builder => '_build__coll_name',
);

sub _build__coll_name {
    my ($self) = @_;
    return $self->collection->name;
}

has _db_name => (
    is      => 'lazy',
    isa     => Str,
    builder => '_build__db_name',
);

sub _build__db_name {
    my ($self) = @_;
    return $self->collection->database->name;
}

has _write_concern => (
    is      => 'lazy',
    isa     => InstanceOf( ['MongoDB::WriteConcern'] ),
    builder => '_build__write_concern',
);

sub _build__write_concern {
    my ($self) = @_;
    return $self->collection->write_concern;
}

#--------------------------------------------------------------------------#
# public methods
#--------------------------------------------------------------------------#

#pod =method list
#pod
#pod     $result = $indexes->list;
#pod
#pod     while ( my $index = $result->next ) {
#pod         ...
#pod     }
#pod
#pod     for my $index ( $result->all ) {
#pod         ...
#pod     }
#pod
#pod This method returns a L which can be used to
#pod retrieve index information either one at a time (with C) or
#pod all at once (with C).
#pod
#pod If the list can't be retrieved, an exception will be thrown.
#pod
#pod =cut

my $list_args;

sub list {
    my ($self) = @_;

    my $op = MongoDB::Op::_ListIndexes->_new(
        client              => $self->_client,
        db_name             => $self->_db_name,
        full_name           => '',                                # unused
        coll_name           => $self->_coll_name,
        bson_codec          => $self->_bson_codec,
        monitoring_callback => $self->_client->monitoring_callback,
        read_preference     => MongoDB::ReadPreference->new( mode => 'primary' ),
        session             => $self->_client->_maybe_get_implicit_session,
    );

    return $self->_client->send_retryable_read_op($op);
}

#pod =method create_one
#pod
#pod     $name = $indexes->create_one( [ x => 1 ] );
#pod     $name = $indexes->create_one( [ x => 1, y => 1 ] );
#pod     $name = $indexes->create_one( [ z => 1 ], { unique => 1 } );
#pod
#pod This method takes an ordered index specification document and an optional
#pod hash reference of index options and returns the name of the index created.
#pod It will throw an exception on error.
#pod
#pod The index specification document is an ordered document (array reference,
#pod L object, or single-key hash reference) with index keys and
#pod direction/type.
#pod
#pod See L for important information about index specifications
#pod and options.
#pod
#pod The following additional options are recognized:
#pod
#pod =for :list
#pod * C — maximum time in milliseconds before the operation will
#pod   time out.
#pod
#pod =cut

my $create_one_args;

sub create_one {
    my ( $self, $keys, $opts ) = @_;

    MongoDB::UsageError->throw("Argument to create_one must be an ordered document")
      unless is_OrderedDoc($keys);

    my $global_opts = {};
    if (exists $opts->{maxTimeMS}) {
        $global_opts->{maxTimeMS} = delete $opts->{maxTimeMS};
    }

    my ($name) = $self->create_many(
        { keys => $keys, ( $opts ? ( options => $opts ) : () ) },
        $global_opts,
    );
    return $name;
}

#pod =method create_many
#pod
#pod     @names = $indexes->create_many(
#pod         { keys => [ x => 1, y => 1 ] },
#pod         { keys => [ z => 1 ], options => { unique => 1 } }
#pod     );
#pod
#pod     @names = $indexes->create_many(
#pod         { keys => [ x => 1, y => 1 ] },
#pod         { keys => [ z => 1 ], options => { unique => 1 } }
#pod         \%global_options,
#pod     );
#pod
#pod This method takes a list of index models (given as hash references)
#pod and returns a list of index names created.  It will throw an exception
#pod on error.
#pod
#pod If the last value is a hash reference without a C entry, it will
#pod be assumed to be a set of global options. See below for a list of
#pod accepted global options.
#pod
#pod Each index module is described by the following fields:
#pod
#pod =for :list
#pod * C (required) — an index specification as an ordered document (array
#pod   reference, L object, or single-key hash reference)
#pod   with index keys and direction/type.  See below for more.
#pod * C — an optional hash reference of index options.
#pod
#pod The C document needs to be ordered.  You are B encouraged
#pod to get in the habit of specifying index keys with an array reference.
#pod Because Perl randomizes the order of hash keys, you may B use a hash
#pod reference if it contains a single key.
#pod
#pod The form of the C document differs based on the type of index (e.g.
#pod single-key, multi-key, text, geospatial, etc.).
#pod
#pod For single and multi-key indexes, the value is "1" for an ascending index
#pod and "-1" for a descending index.
#pod
#pod     [ name => 1, votes => -1 ] # ascending on name, descending on votes
#pod
#pod See L in the
#pod MongoDB Manual for instructions for other index types.
#pod
#pod The C hash reference may have a mix of general-purpose and
#pod index-type-specific options.  See L
#pod Options|http://docs.mongodb.org/manual/reference/method/db.collection.createIndex/#options>
#pod in the MongoDB Manual for specifics.
#pod
#pod Some of the more commonly used options include:
#pod
#pod =for :list
#pod * C — when true, index creation won't block but will run in the
#pod   background; this is strongly recommended to avoid blocking other
#pod   operations on the database.
#pod * C - a L defining the collation for this operation.
#pod   See docs for the format of the collation document here:
#pod   L.
#pod * C — enforce uniqueness when true; inserting a duplicate document
#pod   (or creating one with update modifiers) will raise an error.
#pod * C — a name (string) for the index; one will be generated if this is
#pod   omitted.
#pod
#pod Global options specified as the last value can contain the following
#pod keys:
#pod
#pod =for :list
#pod * C — maximum time in milliseconds before the operation will
#pod   time out.
#pod
#pod =cut

my $create_many_args;

sub create_many {
    my ( $self, @models ) = @_;

    my $opts;
    if (@models and ref $models[-1] eq 'HASH' and not exists $models[-1]{keys}) {
        $opts = pop @models;
    }

    MongoDB::UsageError->throw("Argument to create_many must be a list of index models")
      unless is_IndexModelList(\@models);

    my $indexes = [ map __flatten_index_model($_), @models ];
    my $op = MongoDB::Op::_CreateIndexes->_new(
        db_name             => $self->_db_name,
        coll_name           => $self->_coll_name,
        full_name           => '',                                # unused
        bson_codec          => $self->_bson_codec,
        indexes             => $indexes,
        write_concern       => $self->_write_concern,
        monitoring_callback => $self->_client->monitoring_callback,
        (defined($opts->{maxTimeMS})
            ? (max_time_ms   => $opts->{maxTimeMS})
            : ()
        ),
    );

    # succeed or die; we don't care about response document
    $self->_client->send_write_op($op);

    return map $_->{name}, @$indexes;
}

#pod =method drop_one
#pod
#pod     $output = $indexes->drop_one( $name );
#pod     $output = $indexes->drop_one( $name, \%options );
#pod
#pod This method takes the name of an index and drops it.  It returns the output
#pod of the dropIndexes command (a hash reference) on success or throws a
#pod exception if the command errors.  However, if the index does not exist, the
#pod command output will have the C field as a false value, but no exception
#pod will e thrown.
#pod
#pod Valid options are:
#pod
#pod =for :list
#pod * C — maximum time in milliseconds before the operation will
#pod   time out.
#pod
#pod =cut

my $drop_one_args;

sub drop_one {
    my ( $self, $name, $opts ) = @_;

    MongoDB::UsageError->throw("Argument to drop_one must be a string")
      unless is_Str($name);

    if ( $name eq '*' ) {
        MongoDB::UsageError->throw("Can't use '*' as an argument to drop_one");
    }

    my $op = MongoDB::Op::_DropIndexes->_new(
        db_name             => $self->_db_name,
        coll_name           => $self->_coll_name,
        full_name           => '',                                 # unused
        bson_codec          => $self->_bson_codec,
        write_concern       => $self->_write_concern,
        index_name          => $name,
        monitoring_callback => $self->_client->monitoring_callback,
        (defined($opts->{maxTimeMS})
            ? (max_time_ms   => $opts->{maxTimeMS})
            : ()
        ),
    );

    $self->_client->send_write_op($op)->output;
}

#pod =method drop_all
#pod
#pod     $output = $indexes->drop_all;
#pod     $output = $indexes->drop_all(\%options);
#pod
#pod This method drops all indexes (except the one on the C<_id> field).  It
#pod returns the output of the dropIndexes command (a hash reference) on success
#pod or throws a exception if the command fails.
#pod
#pod Valid options are:
#pod
#pod =for :list
#pod * C — maximum time in milliseconds before the operation will
#pod   time out.
#pod
#pod =cut

my $drop_all_args;

sub drop_all {
    my ($self, $opts) = @_;

    my $op = MongoDB::Op::_DropIndexes->_new(
        db_name             => $self->_db_name,
        coll_name           => $self->_coll_name,
        full_name           => '',                                 # unused
        bson_codec          => $self->_bson_codec,
        write_concern       => $self->_write_concern,
        index_name          => '*',
        monitoring_callback => $self->_client->monitoring_callback,
        (defined($opts->{maxTimeMS})
            ? (max_time_ms   => $opts->{maxTimeMS})
            : ()
        ),
    );

    $self->_client->send_write_op($op)->output;
}

#--------------------------------------------------------------------------#
# private functions
#--------------------------------------------------------------------------#

sub __flatten_index_model {
    my ($model) = @_;

    my ( $keys, $orig ) = @{$model}{qw/keys options/};

    $keys = IxHash->coerce($keys);

    # copy the original so we don't modify it
    my $opts = { $orig ? %$orig : () };

    for my $k (qw/keys key/) {
        MongoDB::UsageError->throw("Can't specify '$k' in options to index creation")
          if exists $opts->{$k};
    }

    # add name if not provided
    $opts->{name} = __to_index_string($keys)
      unless defined $opts->{name};

    # convert some things to booleans
    for my $k (qw/unique background sparse dropDups/) {
        next unless exists $opts->{$k};
        $opts->{$k} = boolean( $opts->{$k} );
    }

    # return is document ready for the createIndexes command
    return { key => $keys, %$opts };
}

# utility function to generate an index name by concatenating key/value pairs
sub __to_index_string {
    my $keys = shift;

    if ( ref $keys eq 'Tie::IxHash' ) {
        my @name;
        my @ks = $keys->Keys;
        my @vs = $keys->Values;

        for ( my $i = 0; $i < $keys->Length; $i++ ) {
            push @name, $ks[$i];
            push @name, $vs[$i];
        }

        return join( "_", @name );
    }
    else {
        MongoDB::InternalError->throw("expected Tie::IxHash for __to_index_string");
    }

}


1;


# vim: set ts=4 sts=4 sw=4 et tw=75:

__END__