Current File : /home/opti/optisoftcom-new/perl/usr/man/man3/MongoDB::Collection.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MongoDB::Collection 3"
.TH MongoDB::Collection 3 "2018-11-30" "perl v5.16.3" "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::Collection \- A MongoDB Collection
.SH "VERSION"
.IX Header "VERSION"
version v2.0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # get a Collection via the Database object
\& $coll = $db\->get_collection("people");
\&
\& # insert a document
\& $coll\->insert_one( { name => "John Doe", age => 42 } );
\&
\& # insert one or more documents
\& $coll\->insert_many( \e@documents );
\&
\& # delete a document
\& $coll\->delete_one( { name => "John Doe" } );
\&
\& # update a document
\& $coll\->update_one( { name => "John Doe" }, { \*(Aq$inc\*(Aq => { age => 1 } } );
\&
\& # find a single document
\& $doc = $coll\->find_one( { name => "John Doe" } )
\&
\& # Get a MongoDB::Cursor for a query
\& $cursor = $coll\->find( { age => 42 } );
\&
\& # Cursor iteration
\& while ( my $doc = $cursor\->next ) {
\& ...
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class models a MongoDB collection and provides an \s-1API\s0 for interacting
with it.
.PP
Generally, you never construct one of these directly with \f(CW\*(C`new\*(C'\fR. Instead, you
call \f(CW\*(C`get_collection\*(C'\fR on a MongoDB::Database object.
.SH "USAGE"
.IX Header "USAGE"
.SS "Error handling"
.IX Subsection "Error handling"
Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs. The error types are documented in MongoDB::Error.
.PP
To catch and handle errors, the Try::Tiny and Safe::Isa modules
are recommended:
.PP
.Vb 2
\& use Try::Tiny;
\& use Safe::Isa; # provides $_isa
\&
\& try {
\& $coll\->insert_one( $doc )
\& }
\& catch {
\& if ( $_\->$_isa("MongoDB::DuplicateKeyError" ) {
\& ...
\& }
\& else {
\& ...
\& }
\& };
.Ve
.PP
To retry failures automatically, consider using Try::Tiny::Retry.
.SS "Transactions"
.IX Subsection "Transactions"
To conduct operations in a transactions, get a MongoDB::ClientSession
from \*(L"start_session\*(R" in MongoDB::MongoClient. Start the transaction on the
session using \f(CW\*(C`start_transaction\*(C'\fR and pass the session as an option to all
operations. Then call \f(CW\*(C`commit_transaction\*(C'\fR or \f(CW\*(C`abort_transaction\*(C'\fR on the
session. See the MongoDB::ClientSession for options and usage details.
.PP
For detailed instructions on using transactions with MongoDB, see the
MongoDB manual page:
Transactions <https://docs.mongodb.com/master/core/transactions>.
.SS "Terminology"
.IX Subsection "Terminology"
\fIDocument\fR
.IX Subsection "Document"
.PP
A collection of key-value pairs. A Perl hash is a document. Array
references with an even number of elements and Tie::IxHash objects may also
be used as documents.
.PP
\fIOrdered document\fR
.IX Subsection "Ordered document"
.PP
Many MongoDB::Collection method parameters or options require an \fBordered
document\fR: an ordered list of key/value pairs. Perl's hashes are \fBnot\fR
ordered and since Perl v5.18 are guaranteed to have random order. Therefore,
when an ordered document is called for, you may use an array reference of pairs
or a Tie::IxHash object. You may use a hash reference if there is only
one key/value pair.
.PP
\fIFilter expression\fR
.IX Subsection "Filter expression"
.PP
A filter expression provides the query
criteria <http://docs.mongodb.org/manual/tutorial/query-documents/> to select a
document for deletion. It must be an \*(L"Ordered document\*(R".
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "database"
.IX Subsection "database"
The MongoDB::Database representing the database that contains
the collection.
.SS "name"
.IX Subsection "name"
The name of the collection.
.SS "read_preference"
.IX Subsection "read_preference"
A MongoDB::ReadPreference object. It may be initialized with a string
corresponding to one of the valid read preference modes or a hash reference
that will be coerced into a new MongoDB::ReadPreference object.
By default it will be inherited from a MongoDB::Database object.
.SS "write_concern"
.IX Subsection "write_concern"
A MongoDB::WriteConcern object. It may be initialized with a hash
reference that will be coerced into a new MongoDB::WriteConcern object.
By default it will be inherited from a MongoDB::Database object.
.SS "read_concern"
.IX Subsection "read_concern"
A MongoDB::ReadConcern object. May be initialized with a hash
reference or a string that will be coerced into the level of read
concern.
.PP
By default it will be inherited from a MongoDB::Database object.
.SS "max_time_ms"
.IX Subsection "max_time_ms"
Specifies the default maximum amount of time in milliseconds that the
server should use for working on a query.
.PP
\&\fBNote\fR: this will only be used for server versions 2.6 or greater, as that
was when the \f(CW$maxTimeMS\fR meta-operator was introduced.
.SS "bson_codec"
.IX Subsection "bson_codec"
An object that provides the \f(CW\*(C`encode_one\*(C'\fR and \f(CW\*(C`decode_one\*(C'\fR methods, such
as from \s-1BSON\s0. It may be initialized with a hash reference that
will be coerced into a new \s-1BSON\s0 object. By default it will be
inherited from a MongoDB::Database object.
.SH "METHODS"
.IX Header "METHODS"
.SS "client"
.IX Subsection "client"
.Vb 1
\& $client = $coll\->client;
.Ve
.PP
Returns the MongoDB::MongoClient object associated with this
object.
.SS "full_name"
.IX Subsection "full_name"
.Vb 1
\& $full_name = $coll\->full_name;
.Ve
.PP
Returns the full name of the collection, including the namespace of the
database it's in prefixed with a dot character. E.g. collection \*(L"foo\*(R" in
database \*(L"test\*(R" would result in a \f(CW\*(C`full_name\*(C'\fR of \*(L"test.foo\*(R".
.SS "indexes"
.IX Subsection "indexes"
.Vb 1
\& $indexes = $collection\->indexes;
\&
\& $collection\->indexes\->create_one( [ x => 1 ], { unique => 1 } );
\& $collection\->indexes\->drop_all;
.Ve
.PP
Returns a MongoDB::IndexView object for managing the indexes associated
with the collection.
.SS "clone"
.IX Subsection "clone"
.Vb 1
\& $coll2 = $coll1\->clone( write_concern => { w => 2 } );
.Ve
.PP
Constructs a copy of the original collection, but allows changing
attributes in the copy.
.SS "with_codec"
.IX Subsection "with_codec"
.Vb 2
\& $coll2 = $coll1\->with_codec( $new_codec );
\& $coll2 = $coll1\->with_codec( prefer_numeric => 1 );
.Ve
.PP
Constructs a copy of the original collection, but clones the \f(CW\*(C`bson_codec\*(C'\fR.
If given an object that does \f(CW\*(C`encode_one\*(C'\fR and \f(CW\*(C`decode_one\*(C'\fR, it is
equivalent to:
.PP
.Vb 1
\& $coll2 = $coll1\->clone( bson_codec => $new_codec );
.Ve
.PP
If given a hash reference or a list of key/value pairs, it is equivalent
to:
.PP
.Vb 3
\& $coll2 = $coll1\->clone(
\& bson_codec => $coll1\->bson_codec\->clone( @list )
\& );
.Ve
.SS "insert_one"
.IX Subsection "insert_one"
.Vb 3
\& $res = $coll\->insert_one( $document );
\& $res = $coll\->insert_one( $document, $options );
\& $id = $res\->inserted_id;
.Ve
.PP
Inserts a single document into the database and returns a
MongoDB::InsertOneResult or MongoDB::UnacknowledgedResult object.
.PP
If no \f(CW\*(C`_id\*(C'\fR field is present, one will be added when a document is
serialized for the database without modifying the original document.
The generated \f(CW\*(C`_id\*(C'\fR may be retrieved from the result object.
.PP
An optional hash reference of options may be given.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.SS "insert_many"
.IX Subsection "insert_many"
.Vb 2
\& $res = $coll\->insert_many( [ @documents ] );
\& $res = $coll\->insert_many( [ @documents ], { ordered => 0 } );
.Ve
.PP
Inserts each of the documents in an array reference into the
database and returns a MongoDB::InsertManyResult or
MongoDB::UnacknowledgedResult. This is syntactic sugar for doing a
MongoDB::BulkWrite operation.
.PP
If no \f(CW\*(C`_id\*(C'\fR field is present, one will be added when a document is
serialized for the database without modifying the original document.
The generated \f(CW\*(C`_id\*(C'\fR may be retrieved from the result object.
.PP
An optional hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`ordered\*(C'\fR X when true, the server will halt insertions after the first error (if any). When false, all documents will be processed and any error will only be thrown after all insertions are attempted. The default is true.
.PP
On MongoDB servers before version 2.6, \f(CW\*(C`insert_many\*(C'\fR bulk operations are
emulated with individual inserts to capture error information. On 2.6 or
later, this method will be significantly faster than individual \f(CW\*(C`insert_one\*(C'\fR
calls.
.SS "delete_one"
.IX Subsection "delete_one"
.Vb 3
\& $res = $coll\->delete_one( $filter );
\& $res = $coll\->delete_one( { _id => $id } );
\& $res = $coll\->delete_one( $filter, { collation => { locale => "en_US" } } );
.Ve
.PP
Deletes a single document that matches a filter expression and returns a
MongoDB::DeleteResult or MongoDB::UnacknowledgedResult object.
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.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`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.SS "delete_many"
.IX Subsection "delete_many"
.Vb 3
\& $res = $coll\->delete_many( $filter );
\& $res = $coll\->delete_many( { name => "Larry" } );
\& $res = $coll\->delete_many( $filter, { collation => { locale => "en_US" } } );
.Ve
.PP
Deletes all documents that match a filter expression
and returns a MongoDB::DeleteResult or MongoDB::UnacknowledgedResult
object.
.PP
Valid options include:
.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`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.SS "replace_one"
.IX Subsection "replace_one"
.Vb 2
\& $res = $coll\->replace_one( $filter, $replacement );
\& $res = $coll\->replace_one( $filter, $replacement, { upsert => 1 } );
.Ve
.PP
Replaces one document that matches a filter expression and returns a MongoDB::UpdateResult or
MongoDB::UnacknowledgedResult object.
.PP
The replacement document must not have any field-update operators in it (e.g.
\&\f(CW$set\fR).
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.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`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`upsert\*(C'\fR X defaults to false; if true, a new document will be added if one is not found
.SS "update_one"
.IX Subsection "update_one"
.Vb 2
\& $res = $coll\->update_one( $filter, $update );
\& $res = $coll\->update_one( $filter, $update, { upsert => 1 } );
.Ve
.PP
Updates one document that matches a filter expression
and returns a MongoDB::UpdateResult or MongoDB::UnacknowledgedResult
object.
.PP
The update document must have only field-update operators in it (e.g.
\&\f(CW$set\fR).
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`arrayFilters\*(C'\fR \- An array of filter documents that determines which array elements to modify for an update operation on an array field. Only available for MongoDB servers of version 3.6+.
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.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`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`upsert\*(C'\fR X defaults to false; if true, a new document will be added if one is not found by taking the filter expression and applying the update document operations to it prior to insertion.
.SS "update_many"
.IX Subsection "update_many"
.Vb 2
\& $res = $coll\->update_many( $filter, $update );
\& $res = $coll\->update_many( $filter, $update, { upsert => 1 } );
.Ve
.PP
Updates one or more documents that match a filter expression and returns a MongoDB::UpdateResult or
MongoDB::UnacknowledgedResult object.
.PP
The update document must have only field-update operators in it (e.g.
\&\f(CW$set\fR).
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`arrayFilters\*(C'\fR \- An array of filter documents that determines which array elements to modify for an update operation on an array field. Only available for MongoDB servers of version 3.6+.
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.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`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`upsert\*(C'\fR X defaults to false; if true, a new document will be added if one is not found by taking the filter expression and applying the update document operations to it prior to insertion.
.SS "find"
.IX Subsection "find"
.Vb 2
\& $cursor = $coll\->find( $filter );
\& $cursor = $coll\->find( $filter, $options );
\&
\& $cursor = $coll\->find({ i => { \*(Aq$gt\*(Aq => 42 } }, {limit => 20});
.Ve
.PP
Executes a query with a filter expression and returns a
\&\fBlazy\fR \f(CW\*(C`MongoDB::Cursor\*(C'\fR object. (The query is not immediately
issued to the server; see below for details.)
.PP
The query can be customized using MongoDB::Cursor methods, or with an
optional hash reference of options.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`allowPartialResults\*(C'\fR \- get partial results from a mongos if some shards are down (instead of throwing an error).
.IP "\(bu" 4
\&\f(CW\*(C`batchSize\*(C'\fR X the number of documents to return per batch.
.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`comment\*(C'\fR X attaches a comment to the query.
.IP "\(bu" 4
\&\f(CW\*(C`cursorType\*(C'\fR X indicates the type of cursor to use. It must be one of three string values: \f(CW\*(Aqnon_tailable\*(Aq\fR (the default), \f(CW\*(Aqtailable\*(Aq\fR, and \f(CW\*(Aqtailable_await\*(Aq\fR.
.IP "\(bu" 4
\&\f(CW\*(C`hint\*(C'\fR X specify an index to use <http://docs.mongodb.org/manual/reference/command/count/#specify-the-index-to-use>; must be a string, array reference, hash reference or Tie::IxHash object.
.IP "\(bu" 4
\&\f(CW\*(C`limit\*(C'\fR X the maximum number of documents to return.
.IP "\(bu" 4
\&\f(CW\*(C`max\*(C'\fR X specify the \fBexclusive\fR upper bound for a specific index.
.IP "\(bu" 4
\&\f(CW\*(C`maxAwaitTimeMS\*(C'\fR X the maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. This only applies to a \f(CW\*(C`cursorType\*(C'\fR of 'tailable_await'; the option is otherwise ignored. (Note, this will be ignored for servers before version 3.2.)
.IP "\(bu" 4
\&\f(CW\*(C`maxScan\*(C'\fR X (\s-1DEPRECATED\s0) maximum number of documents or index keys to scan.
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR X the maximum amount of time to allow the query to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`min\*(C'\fR X specify the \fBinclusive\fR lower bound for a specific index.
.IP "\(bu" 4
\&\f(CW\*(C`modifiers\*(C'\fR X (\s-1DEPRECATED\s0) a hash reference of dollar-prefixed query modifiers <http://docs.mongodb.org/manual/reference/operator/query-modifier/> modifying the output or behavior of a query. Top-level options will always take precedence over corresponding modifiers. Supported modifiers include \f(CW$comment\fR, \f(CW$hint\fR, \f(CW$maxScan\fR, \f(CW$maxTimeMS\fR, \f(CW$max\fR, \f(CW$min\fR, \f(CW$orderby\fR, \f(CW$returnKey\fR, \f(CW$showDiskLoc\fR, and \f(CW$snapshot\fR. Some options may not be supported by newer server versions.
.IP "\(bu" 4
\&\f(CW\*(C`noCursorTimeout\*(C'\fR X if true, prevents the server from timing out a cursor after a period of inactivity.
.IP "\(bu" 4
\&\f(CW\*(C`projection\*(C'\fR \- a hash reference defining fields to return. See "limit fields to return <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>" in the MongoDB documentation for details.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`returnKey\*(C'\fR X Only return the index field or fields for the results of the query <https://docs.mongodb.com/manual/reference/operator/meta/returnKey/>.
.IP "\(bu" 4
\&\f(CW\*(C`showRecordId\*(C'\fR X modifies the output of a query by adding a field \f(CW$recordId\fR <https://docs.mongodb.com/manual/reference/method/cursor.showRecordId/> that uniquely identifies a document in a collection.
.IP "\(bu" 4
\&\f(CW\*(C`skip\*(C'\fR X the number of documents to skip before returning.
.IP "\(bu" 4
\&\f(CW\*(C`sort\*(C'\fR X an ordered document defining the order in which to return matching documents. See the \f(CW$orderby\fR documentation <https://docs.mongodb.com/manual/reference/operator/meta/orderby/> for examples.
.PP
For more information, see the Read Operations
Overview <http://docs.mongodb.org/manual/core/read-operations-introduction/> in
the MongoDB documentation.
.PP
\&\fBNote\fR, a MongoDB::Cursor object holds the query and does not issue the
query to the server until the result method is
called on it or until an iterator method like next
is called. Performance will be better directly on a
MongoDB::QueryResult object:
.PP
.Vb 1
\& my $query_result = $coll\->find( $filter )\->result;
\&
\& while ( my $next = $query_result\->next ) {
\& ...
\& }
.Ve
.SS "find_one"
.IX Subsection "find_one"
.Vb 2
\& $doc = $collection\->find_one( $filter, $projection );
\& $doc = $collection\->find_one( $filter, $projection, $options );
.Ve
.PP
Executes a query with a filter expression and returns a
single document.
.PP
If a projection argument is provided, it must be a hash reference specifying
fields to return. See Limit fields to
return <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>
in the MongoDB documentation for details.
.PP
If only a filter is provided or if the projection document is an empty hash
reference, all fields will be returned.
.PP
.Vb 2
\& my $doc = $collection\->find_one( $filter );
\& my $doc = $collection\->find_one( $filter, {}, $options );
.Ve
.PP
A hash reference of options may be provided as a third argument. Valid keys
include:
.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`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`sort\*(C'\fR X an ordered document defining the order in which to return matching documents. If \f(CW$orderby\fR also exists in the modifiers document, the sort field overwrites \f(CW$orderby\fR. See docs for \f(CW$orderby\fR <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
.PP
See also core documentation on querying:
<http://docs.mongodb.org/manual/core/read/>.
.SS "find_id"
.IX Subsection "find_id"
.Vb 3
\& $doc = $collection\->find_id( $id );
\& $doc = $collection\->find_id( $id, $projection );
\& $doc = $collection\->find_id( $id, $projection, $options );
.Ve
.PP
Executes a query with a filter expression of \f(CW\*(C`{ _id
=> $id }\*(C'\fR and returns a single document.
.PP
See the find_one documentation for details on the \f(CW$projection\fR and \f(CW$options\fR parameters.
.PP
See also core documentation on querying:
<http://docs.mongodb.org/manual/core/read/>.
.SS "find_one_and_delete"
.IX Subsection "find_one_and_delete"
.Vb 2
\& $doc = $coll\->find_one_and_delete( $filter );
\& $doc = $coll\->find_one_and_delete( $filter, $options );
.Ve
.PP
Given a filter expression, this deletes a document from
the database and returns it as it appeared before it was deleted.
.PP
A hash reference of options may be provided. Valid keys include:
.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`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`projection\*(C'\fR \- a hash reference defining fields to return. See "limit fields to return <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>" in the MongoDB documentation for details.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`sort\*(C'\fR X an ordered document defining the order in which to return matching documents. See docs for \f(CW$orderby\fR <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
.SS "find_one_and_replace"
.IX Subsection "find_one_and_replace"
.Vb 2
\& $doc = $coll\->find_one_and_replace( $filter, $replacement );
\& $doc = $coll\->find_one_and_replace( $filter, $replacement, $options );
.Ve
.PP
Given a filter expression and a replacement document,
this replaces a document from the database and returns it as it was either
right before or right after the replacement. The default is 'before'.
.PP
The replacement document must not have any field-update operators in it (e.g.
\&\f(CW$set\fR).
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.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`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run.
.IP "\(bu" 4
\&\f(CW\*(C`projection\*(C'\fR \- a hash reference defining fields to return. See "limit fields to return <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>" in the MongoDB documentation for details.
.IP "\(bu" 4
\&\f(CW\*(C`returnDocument\*(C'\fR X either the string \f(CW\*(Aqbefore\*(Aq\fR or \f(CW\*(Aqafter\*(Aq\fR, to indicate whether the returned document should be the one before or after replacement. The default is \f(CW\*(Aqbefore\*(Aq\fR.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`sort\*(C'\fR X an ordered document defining the order in which to return matching documents. See docs for \f(CW$orderby\fR <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
.IP "\(bu" 4
\&\f(CW\*(C`upsert\*(C'\fR X defaults to false; if true, a new document will be added if one is not found
.SS "find_one_and_update"
.IX Subsection "find_one_and_update"
.Vb 2
\& $doc = $coll\->find_one_and_update( $filter, $update );
\& $doc = $coll\->find_one_and_update( $filter, $update, $options );
.Ve
.PP
Given a filter expression and a document of update
operators, this updates a single document and returns it as it was either right
before or right after the update. The default is 'before'.
.PP
The update document must contain only field-update operators (e.g. \f(CW$set\fR).
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`arrayFilters\*(C'\fR \- An array of filter documents that determines which array elements to modify for an update operation on an array field. Only available for MongoDB servers of version 3.6+.
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.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`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`projection\*(C'\fR \- a hash reference defining fields to return. See "limit fields to return <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>" in the MongoDB documentation for details.
.IP "\(bu" 4
\&\f(CW\*(C`returnDocument\*(C'\fR X either the string \f(CW\*(Aqbefore\*(Aq\fR or \f(CW\*(Aqafter\*(Aq\fR, to indicate whether the returned document should be the one before or after replacement. The default is \f(CW\*(Aqbefore\*(Aq\fR.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.IP "\(bu" 4
\&\f(CW\*(C`sort\*(C'\fR X an ordered document defining the order in which to return matching documents. See docs for \f(CW$orderby\fR <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
.IP "\(bu" 4
\&\f(CW\*(C`upsert\*(C'\fR X defaults to false; if true, a new document will be added if one is not found
.SS "watch"
.IX Subsection "watch"
Watches for changes on this collection\-
.PP
Perform an aggregation with an implicit initial \f(CW$changeStream\fR stage
and returns a MongoDB::ChangeStream result which can be used to
iterate over the changes in the collection. This functionality is
available since MongoDB 3.6.
.PP
.Vb 3
\& my $stream = $collection\->watch();
\& my $stream = $collection\->watch( \e@pipeline );
\& my $stream = $collection\->watch( \e@pipeline, \e%options );
\&
\& while (1) {
\&
\& # This inner loop will only run until no more changes are
\& # available.
\& while (my $change = $stream\->next) {
\& # process $change
\& }
\& }
.Ve
.PP
The returned stream will not block forever waiting for changes. If you
want to respond to changes over a longer time use \f(CW\*(C`maxAwaitTimeMS\*(C'\fR and
regularly call \f(CW\*(C`next\*(C'\fR in a loop.
.PP
\&\fBNote\fR: Using this helper method is preferred to manually aggregating
with a \f(CW$changeStream\fR stage, since it will automatically resume when
the connection was terminated.
.PP
The optional first argument must be an array-ref of
aggregation pipeline <http://docs.mongodb.org/manual/core/aggregation-pipeline/>
documents. Each pipeline document must be a hash reference. Not all
pipeline stages are supported after \f(CW$changeStream\fR.
.PP
The optional second argument is a hash reference with options:
.IP "\(bu" 4
\&\f(CW\*(C`fullDocument\*(C'\fR \- The fullDocument to pass as an option to the \f(CW$changeStream\fR stage. Allowed values: \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`updateLookup\*(C'\fR. Defaults to \f(CW\*(C`default\*(C'\fR. When set to \f(CW\*(C`updateLookup\*(C'\fR, the change notification for partial updates will include both a delta describing the changes to the document, as well as a copy of the entire document that was changed from some time after the change occurred.
.IP "\(bu" 4
\&\f(CW\*(C`resumeAfter\*(C'\fR \- The logical starting point for this change stream. This value can be obtained from the \f(CW\*(C`_id\*(C'\fR field of a document returned by \*(L"next\*(R" in MongoDB::ChangeStream. Cannot be specified together with \f(CW\*(C`startAtOperationTime\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`maxAwaitTimeMS\*(C'\fR \- The maximum number of milliseconds for the server to wait before responding.
.IP "\(bu" 4
\&\f(CW\*(C`startAtOperationTime\*(C'\fR \- A BSON::Timestamp specifying at what point in time changes will start being watched. Cannot be specified together with \f(CW\*(C`resumeAfter\*(C'\fR. Plain values will be coerced to BSON::Timestamp objects.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
See \*(L"aggregate\*(R" for more available options.
.PP
See the manual section on Change Streams <https://docs.mongodb.com/manual/changeStreams/>
for general usage information on change streams.
.PP
See the Change Streams specification <https://github.com/mongodb/specifications/blob/master/source/change-streams.rst>
for details on change streams.
.SS "aggregate"
.IX Subsection "aggregate"
.Vb 4
\& @pipeline = (
\& { \*(Aq$group\*(Aq => { _id => \*(Aq$state,\*(Aq totalPop => { \*(Aq$sum\*(Aq => \*(Aq$pop\*(Aq } } },
\& { \*(Aq$match\*(Aq => { totalPop => { \*(Aq$gte\*(Aq => 10 * 1000 * 1000 } } }
\& );
\&
\& $result = $collection\->aggregate( \e@pipeline );
\& $result = $collection\->aggregate( \e@pipeline, $options );
.Ve
.PP
Runs a query using the MongoDB 2.2+ aggregation framework and returns a
MongoDB::QueryResult object.
.PP
The first argument must be an array-ref of aggregation
pipeline <http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents.
Each pipeline document must be a hash reference.
.PP
\&\fBNote\fR: Some pipeline documents have ordered arguments, such as \f(CW$sort\fR.
Be sure to provide these argument using Tie::IxHash. E.g.:
.PP
.Vb 1
\& { \*(Aq$sort\*(Aq => Tie::IxHash\->new( age => \-1, posts => 1 ) }
.Ve
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`allowDiskUse\*(C'\fR X if, true enables writing to temporary files.
.IP "\(bu" 4
\&\f(CW\*(C`batchSize\*(C'\fR X the number of documents to return per batch.
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled. (Note, this will be ignored for servers before version 3.2.)
.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`explain\*(C'\fR X if true, return a single document with execution information.
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`hint\*(C'\fR \- An index to use for this aggregation. (Only compatible with servers above version 3.6.) For more information, see the other aggregate options here: <https://docs.mongodb.com/manual/reference/command/aggregate/index.html>
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
\&\fBNote\fR MongoDB 2.6+ added the '$out' pipeline operator. If this operator is
used to write aggregation results directly to a collection, an empty result
will be returned. Create a new collection> object to query the generated result
collection. When \f(CW$out\fR is used, the command is treated as a write operation
and read preference is ignored.
.PP
See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the MongoDB manual
for more information on how to construct aggregation queries.
.PP
\&\fBNote\fR The use of aggregation cursors is automatic based on your server
version. However, if migrating a sharded cluster from MongoDB 2.4 to 2.6
or later, you must upgrade your mongod servers first before your mongos
routers or aggregation queries will fail. As a workaround, you may
pass \f(CW\*(C`cursor => undef\*(C'\fR as an option.
.SS "count_documents"
.IX Subsection "count_documents"
.Vb 2
\& $count = $coll\->count_documents( $filter );
\& $count = $coll\->count_documents( $filter, $options );
.Ve
.PP
Returns a count of documents matching a filter expression.
To return a count of all documents, use an empty hash reference as the filter.
.PP
\&\fB\s-1NOTE\s0\fR: this may result in a scan of all documents in the collection.
.PP
A hash reference of options may be provided. Valid keys include:
.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`hint\*(C'\fR X specify an index to use; must be a string, array reference, hash reference or Tie::IxHash object. (Requires server version 3.6 or later.)
.IP "\(bu" 4
\&\f(CW\*(C`limit\*(C'\fR X the maximum number of documents to count.
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`skip\*(C'\fR X the number of documents to skip before counting documents.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
\&\fB\s-1NOTE\s0\fR: When upgrading from the deprecated \f(CW\*(C`count\*(C'\fR method, some legacy
operators are not supported and must be replaced:
.PP
.Vb 9
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | Legacy | Modern Replacement |
\& +=============+================================+
\& | $where | $expr (Requires MongoDB 3.6+) |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | $near | $geoWithin with $center |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\& | $nearSphere | $geoWithin with $centerSphere |
\& +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.SS "estimated_document_count"
.IX Subsection "estimated_document_count"
.Vb 2
\& $count = $coll\->estimated_document_count();
\& $count = $coll\->estimated_document_count($options);
.Ve
.PP
Returns an estimated count of documents based on collection metadata.
.PP
\&\fB\s-1NOTE\s0\fR: this method does not support sessions or transactions.
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.SS "distinct"
.IX Subsection "distinct"
.Vb 3
\& $result = $coll\->distinct( $fieldname );
\& $result = $coll\->distinct( $fieldname, $filter );
\& $result = $coll\->distinct( $fieldname, $filter, $options );
.Ve
.PP
Returns a MongoDB::QueryResult object that will provide distinct values for
a specified field name.
.PP
The query may be limited by an optional filter expression.
.PP
A hash reference of options may be provided. Valid keys include:
.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`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 2.6.)
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
See documentation for the distinct
command <http://docs.mongodb.org/manual/reference/command/distinct/> for
details.
.SS "parallel_scan"
.IX Subsection "parallel_scan"
.Vb 2
\& @result_objs = $collection\->parallel_scan(10);
\& @result_objs = $collection\->parallel_scan(10, $options );
.Ve
.PP
Returns one or more MongoDB::QueryResult objects to scan the collection in
parallel. The argument is the maximum number of MongoDB::QueryResult objects
to return and must be a positive integer between 1 and 10,000.
.PP
As long as the collection is not modified during scanning, each document will
appear only once in one of the cursors' result sets.
.PP
\&\fBNote\fR: the server may return fewer cursors than requested, depending on the
underlying storage engine and resource availability.
.PP
A hash reference of options may be provided. Valid keys include:
.IP "\(bu" 4
\&\f(CW\*(C`maxTimeMS\*(C'\fR X the maximum amount of time in milliseconds to allow the command to run. (Note, this will be ignored for servers before version 3.4.)
.SS "rename"
.IX Subsection "rename"
.Vb 1
\& $newcollection = $collection\->rename("mynewcollection");
.Ve
.PP
Renames the collection. If a collection already exists with the new collection
name, this method will throw an exception.
.PP
A hashref of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
It returns a new MongoDB::Collection object corresponding to the renamed
collection.
.SS "drop"
.IX Subsection "drop"
.Vb 1
\& $collection\->drop;
.Ve
.PP
Deletes a collection as well as all of its indexes.
.SS "ordered_bulk"
.IX Subsection "ordered_bulk"
.Vb 5
\& $bulk = $coll\->ordered_bulk;
\& $bulk\->insert_one( $doc1 );
\& $bulk\->insert_one( $doc2 );
\& ...
\& $result = $bulk\->execute;
.Ve
.PP
Returns a MongoDB::BulkWrite object to group write operations into fewer network
round-trips. This method creates an \fBordered\fR operation, where operations halt after
the first error. See MongoDB::BulkWrite for more details.
.PP
The method \f(CW\*(C`initialize_ordered_bulk_op\*(C'\fR may be used as an alias.
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.SS "unordered_bulk"
.IX Subsection "unordered_bulk"
This method works just like \*(L"ordered_bulk\*(R" except that the order that
operations are sent to the database is not guaranteed and errors do not halt processing.
See MongoDB::BulkWrite for more details.
.PP
The method \f(CW\*(C`initialize_unordered_bulk_op\*(C'\fR may be used as an alias.
.PP
A hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.SS "bulk_write"
.IX Subsection "bulk_write"
.Vb 1
\& $res = $coll\->bulk_write( [ @requests ], $options )
.Ve
.PP
This method provides syntactic sugar to construct and execute a bulk operation
directly, without using \f(CW\*(C`initialize_ordered_bulk\*(C'\fR or
\&\f(CW\*(C`initialize_unordered_bulk\*(C'\fR to generate a MongoDB::BulkWrite object and
then calling methods on it. It returns a MongoDB::BulkWriteResponse object
just like the MongoDB::BulkWrite execute method.
.PP
The first argument must be an array reference of requests. Requests consist
of pairs of a MongoDB::Collection write method name (e.g. \f(CW\*(C`insert_one\*(C'\fR,
\&\f(CW\*(C`delete_many\*(C'\fR) and an array reference of arguments to the corresponding
method name. They may be given as pairs, or as hash or array
references:
.PP
.Vb 7
\& # pairs \-\- most efficient
\& @requests = (
\& insert_one => [ { x => 1 } ],
\& replace_one => [ { x => 1 }, { x => 4 } ],
\& delete_one => [ { x => 4 } ],
\& update_many => [ { x => { \*(Aq$gt\*(Aq => 5 } }, { \*(Aq$inc\*(Aq => { x => 1 } } ],
\& );
\&
\& # hash references
\& @requests = (
\& { insert_one => [ { x => 1 } ] },
\& { replace_one => [ { x => 1 }, { x => 4 } ] },
\& { delete_one => [ { x => 4 } ] },
\& { update_many => [ { x => { \*(Aq$gt\*(Aq => 5 } }, { \*(Aq$inc\*(Aq => { x => 1 } } ] },
\& );
\&
\& # array references
\& @requests = (
\& [ insert_one => [ { x => 1 } ] ],
\& [ replace_one => [ { x => 1 }, { x => 4 } ] ],
\& [ delete_one => [ { x => 4 } ] ],
\& [ update_many => [ { x => { \*(Aq$gt\*(Aq => 5 } }, { \*(Aq$inc\*(Aq => { x => 1 } } ] ],
\& );
.Ve
.PP
Valid method names include \f(CW\*(C`insert_one\*(C'\fR, \f(CW\*(C`insert_many\*(C'\fR, \f(CW\*(C`delete_one\*(C'\fR,
\&\f(CW\*(C`delete_many\*(C'\fR \f(CW\*(C`replace_one\*(C'\fR, \f(CW\*(C`update_one\*(C'\fR, \f(CW\*(C`update_many\*(C'\fR.
.PP
An optional hash reference of options may be provided.
.PP
Valid options include:
.IP "\(bu" 4
\&\f(CW\*(C`bypassDocumentValidation\*(C'\fR \- skips document validation, if enabled; this is ignored for MongoDB servers older than version 3.2.
.IP "\(bu" 4
\&\f(CW\*(C`ordered\*(C'\fR X when true, the bulk operation is executed like \*(L"initialize_ordered_bulk\*(R". When false, the bulk operation is executed like \*(L"initialize_unordered_bulk\*(R". The default is true.
.IP "\(bu" 4
\&\f(CW\*(C`session\*(C'\fR \- the session to use for these operations. If not supplied, will use an implicit session. For more information see MongoDB::ClientSession
.PP
See MongoDB::BulkWrite for more details on bulk writes. Be advised that
the legacy Bulk \s-1API\s0 method names differ slightly from MongoDB::Collection
method names.
.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) 2018 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Apache License, Version 2.0, January 2004
.Ve
Mini Shell