.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::IndexView 3pm"
.TH MongoDB::IndexView 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::IndexView \- Index management for a collection
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $indexes = $collection\->indexes;
\&
\&    # listing indexes
\&
\&    @names = map { $_\->{name} } $indexes\->list\->all;
\&
\&    my $result = $indexes\->list;
\&
\&    while ( my $index_doc = $result\->next ) {
\&        # do stuff with each $index_doc
\&    }
\&
\&    # creating indexes
\&
\&    $name = $indexes\->create_one( [ x => 1, y => \-1 ], { unique => 1 } );
\&
\&    @names = $indexes\->create_many(
\&        { keys => [ x => 1, y => \-1 ], options => { unique => 1 } },
\&        { keys => [ z => 1 ] },
\&    );
\&
\&    # dropping indexes
\&
\&    $indexes\->drop_one( "x_1_y_\-1" );
\&
\&    $indexes\->drop_all;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class models the indexes on a MongoDB::Collection so you can
create, list or drop them.
.PP
For more on MongoDB indexes, see the MongoDB Manual pages on
indexing <http://docs.mongodb.org/manual/core/indexes/>
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "collection"
.IX Subsection "collection"
The MongoDB::Collection for which indexes are being created or viewed.
.SH "METHODS"
.IX Header "METHODS"
.SS "list"
.IX Subsection "list"
.Vb 1
\&    $result = $indexes\->list;
\&
\&    while ( my $index = $result\->next ) {
\&        ...
\&    }
\&
\&    for my $index ( $result\->all ) {
\&        ...
\&    }
.Ve
.PP
This method returns a MongoDB::QueryResult which can be used to
retrieve index information either one at a time (with \f(CW\*(C`next\*(C'\fR) or
all at once (with \f(CW\*(C`all\*(C'\fR).
.PP
If the list can't be retrieved, an exception will be thrown.
.SS "create_one"
.IX Subsection "create_one"
.Vb 3
\&    $name = $indexes\->create_one( [ x => 1 ] );
\&    $name = $indexes\->create_one( [ x => 1, y => 1 ] );
\&    $name = $indexes\->create_one( [ z => 1 ], { unique => 1 } );
.Ve
.PP
This method takes an ordered index specification document and an optional
hash reference of index options and returns the name of the index created.
It will throw an exception on error.
.PP
The index specification document is an ordered document (array reference,
Tie::IxHash object, or single-key hash reference) with index keys and
direction/type.
.PP
See \*(L"create_many\*(R" for important information about index specifications
and options.
.PP
The following additional options are recognized:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR — maximum time in milliseconds before the operation will time out.
.SS "create_many"
.IX Subsection "create_many"
.Vb 4
\&    @names = $indexes\->create_many(
\&        { keys => [ x => 1, y => 1 ] },
\&        { keys => [ z => 1 ], options => { unique => 1 } }
\&    );
\&
\&    @names = $indexes\->create_many(
\&        { keys => [ x => 1, y => 1 ] },
\&        { keys => [ z => 1 ], options => { unique => 1 } }
\&        \e%global_options,
\&    );
.Ve
.PP
This method takes a list of index models (given as hash references)
and returns a list of index names created.  It will throw an exception
on error.
.PP
If the last value is a hash reference without a \f(CW\*(C`keys\*(C'\fR entry, it will
be assumed to be a set of global options. See below for a list of
accepted global options.
.PP
Each index module is described by the following fields:
.IP "\(bu" 4
\&\f(CW\*(C`keys\*(C'\fR (required) — an index specification as an ordered document (array reference, Tie::IxHash object, or single-key hash reference) with index keys and direction/type.  See below for more.
.IP "\(bu" 4
\&\f(CW\*(C`options\*(C'\fR — an optional hash reference of index options.
.PP
The \f(CW\*(C`keys\*(C'\fR document needs to be ordered.  You are \fB\s-1STRONGLY\s0\fR encouraged
to get in the habit of specifying index keys with an array reference.
Because Perl randomizes the order of hash keys, you may \fB\s-1ONLY\s0\fR use a hash
reference if it contains a single key.
.PP
The form of the \f(CW\*(C`keys\*(C'\fR document differs based on the type of index (e.g.
single-key, multi-key, text, geospatial, etc.).
.PP
For single and multi-key indexes, the value is \*(L"1\*(R" for an ascending index
and \*(L"\-1\*(R" for a descending index.
.PP
.Vb 1
\&    [ name => 1, votes => \-1 ] # ascending on name, descending on votes
.Ve
.PP
See Index Types <http://docs.mongodb.org/manual/core/index-types/> in the
MongoDB Manual for instructions for other index types.
.PP
The \f(CW\*(C`options\*(C'\fR hash reference may have a mix of general-purpose and
index-type-specific options.  See Index
Options <http://docs.mongodb.org/manual/reference/method/db.collection.createIndex/#options>
in the MongoDB Manual for specifics.
.PP
Some of the more commonly used options include:
.IP "\(bu" 4
\&\f(CW\*(C`background\*(C'\fR — when true, index creation won't block but will run in the background; this is strongly recommended to avoid blocking other operations on the database.
.IP "\(bu" 4
\&\f(CW\*(C`collation\*(C'\fR \- a document defining the collation for this operation. See docs for the format of the collation document here: <https://docs.mongodb.com/master/reference/collation/>.
.IP "\(bu" 4
\&\f(CW\*(C`unique\*(C'\fR — enforce uniqueness when true; inserting a duplicate document (or creating one with update modifiers) will raise an error.
.IP "\(bu" 4
\&\f(CW\*(C`name\*(C'\fR — a name (string) for the index; one will be generated if this is omitted.
.PP
Global options specified as the last value can contain the following
keys:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR — maximum time in milliseconds before the operation will time out.
.SS "drop_one"
.IX Subsection "drop_one"
.Vb 2
\&    $output = $indexes\->drop_one( $name );
\&    $output = $indexes\->drop_one( $name, \e%options );
.Ve
.PP
This method takes the name of an index and drops it.  It returns the output
of the dropIndexes command (a hash reference) on success or throws a
exception if the command errors.  However, if the index does not exist, the
command output will have the \f(CW\*(C`ok\*(C'\fR field as a false value, but no exception
will e thrown.
.PP
Valid options are:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR — maximum time in milliseconds before the operation will time out.
.SS "drop_all"
.IX Subsection "drop_all"
.Vb 2
\&    $output = $indexes\->drop_all;
\&    $output = $indexes\->drop_all(\e%options);
.Ve
.PP
This method drops all indexes (except the one on the \f(CW\*(C`_id\*(C'\fR field).  It
returns the output of the dropIndexes command (a hash reference) on success
or throws a exception if the command fails.
.PP
Valid options are:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR — maximum time in milliseconds before the operation will time out.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve