1MongoDB::Collection(3)User Contributed Perl DocumentationMongoDB::Collection(3)
2
6 MongoDB::Collection - A MongoDB Collection
7
9 version v2.2.2
10
12 # get a Collection via the Database object
13 $coll = $db->get_collection("people");
14 # insert a document
16 $coll->insert_one( { name => "John Doe", age => 42 } );
17 # insert one or more documents
19 $coll->insert_many( \@documents );
20 # delete a document
22 $coll->delete_one( { name => "John Doe" } );
23 # update a document
25 $coll->update_one( { name => "John Doe" }, { '$inc' => { age => 1 } } );
26 # find a single document
28 $doc = $coll->find_one( { name => "John Doe" } )
29 # Get a MongoDB::Cursor for a query
31 $cursor = $coll->find( { age => 42 } );
32 # Cursor iteration
34 while ( my $doc = $cursor->next ) {
35 ...
36 }
37
39 This class models a MongoDB collection and provides an API for
40 interacting with it.
41 Generally, you never construct one of these directly with "new".
43 Instead, you call "get_collection" on a MongoDB::Database object.
44
46 Error handling
47 Unless otherwise explicitly documented, all methods throw exceptions if
48 an error occurs. The error types are documented in MongoDB::Error.
49 To catch and handle errors, the Try::Tiny and Safe::Isa modules are
51 recommended:
52 use Try::Tiny;
54 use Safe::Isa; # provides $_isa
55 try {
57 $coll->insert_one( $doc )
58 }
59 catch {
60 if ( $_->$_isa("MongoDB::DuplicateKeyError" ) {
61 ...
62 }
63 else {
64 ...
65 }
66 };
67 To retry failures automatically, consider using Try::Tiny::Retry.
69 Transactions
71 To conduct operations in a transactions, get a MongoDB::ClientSession
72 from "start_session" in MongoDB::MongoClient. Start the transaction on
73 the session using "start_transaction" and pass the session as an option
74 to all operations. Then call "commit_transaction" or
75 "abort_transaction" on the session. See the MongoDB::ClientSession for
76 options and usage details.
77 For detailed instructions on using transactions with MongoDB, see the
79 MongoDB manual page: Transactions
80 <https://docs.mongodb.com/master/core/transactions>.
81 Terminology
83 Document
84 A collection of key-value pairs. A Perl hash is a document. Array
86 references with an even number of elements and Tie::IxHash objects may
87 also be used as documents.
88 Ordered document
90 Many MongoDB::Collection method parameters or options require an
92 ordered document: an ordered list of key/value pairs. Perl's hashes
93 are not ordered and since Perl v5.18 are guaranteed to have random
94 order. Therefore, when an ordered document is called for, you may use
95 an array reference of pairs or a Tie::IxHash object. You may use a
96 hash reference if there is only one key/value pair.
97 Filter expression
99 A filter expression provides the query criteria
101 <http://docs.mongodb.org/manual/tutorial/query-documents/> to select a
102 document for deletion. It must be an "Ordered document".
103
105 database
106 The MongoDB::Database representing the database that contains the
107 collection.
108 name
110 The name of the collection.
111 read_preference
113 A MongoDB::ReadPreference object. It may be initialized with a string
114 corresponding to one of the valid read preference modes or a hash
115 reference that will be coerced into a new MongoDB::ReadPreference
116 object. By default it will be inherited from a MongoDB::Database
117 object.
118 write_concern
120 A MongoDB::WriteConcern object. It may be initialized with a hash
121 reference that will be coerced into a new MongoDB::WriteConcern object.
122 By default it will be inherited from a MongoDB::Database object.
123 read_concern
125 A MongoDB::ReadConcern object. May be initialized with a hash
126 reference or a string that will be coerced into the level of read
127 concern.
128 By default it will be inherited from a MongoDB::Database object.
130 max_time_ms
132 Specifies the default maximum amount of time in milliseconds that the
133 server should use for working on a query.
134 Note: this will only be used for server versions 2.6 or greater, as
136 that was when the $maxTimeMS meta-operator was introduced.
137 bson_codec
139 An object that provides the "encode_one" and "decode_one" methods, such
140 as from BSON. It may be initialized with a hash reference that will be
141 coerced into a new BSON object. By default it will be inherited from a
142 MongoDB::Database object.
143
145 client
146 $client = $coll->client;
147 Returns the MongoDB::MongoClient object associated with this object.
149 full_name
151 $full_name = $coll->full_name;
152 Returns the full name of the collection, including the namespace of the
154 database it's in prefixed with a dot character. E.g. collection "foo"
155 in database "test" would result in a "full_name" of "test.foo".
156 indexes
158 $indexes = $collection->indexes;
159 $collection->indexes->create_one( [ x => 1 ], { unique => 1 } );
161 $collection->indexes->drop_all;
162 Returns a MongoDB::IndexView object for managing the indexes associated
164 with the collection.
165 clone
167 $coll2 = $coll1->clone( write_concern => { w => 2 } );
168 Constructs a copy of the original collection, but allows changing
170 attributes in the copy.
171 with_codec
173 $coll2 = $coll1->with_codec( $new_codec );
174 $coll2 = $coll1->with_codec( prefer_numeric => 1 );
175 Constructs a copy of the original collection, but clones the
177 "bson_codec". If given an object that does "encode_one" and
178 "decode_one", it is equivalent to:
179 $coll2 = $coll1->clone( bson_codec => $new_codec );
181 If given a hash reference or a list of key/value pairs, it is
183 equivalent to:
184 $coll2 = $coll1->clone(
186 bson_codec => $coll1->bson_codec->clone( @list )
187 );
188 insert_one
190 $res = $coll->insert_one( $document );
191 $res = $coll->insert_one( $document, $options );
192 $id = $res->inserted_id;
193 Inserts a single document into the database and returns a
195 MongoDB::InsertOneResult or MongoDB::UnacknowledgedResult object.
196 If no "_id" field is present, one will be added when a document is
198 serialized for the database without modifying the original document.
199 The generated "_id" may be retrieved from the result object.
200 An optional hash reference of options may be given.
202 Valid options include:
204 · "bypassDocumentValidation" - skips document validation, if enabled;
206 this is ignored for MongoDB servers older than version 3.2.
207 · "session" - the session to use for these operations. If not
209 supplied, will use an implicit session. For more information see
210 MongoDB::ClientSession
211 insert_many
213 $res = $coll->insert_many( [ @documents ] );
214 $res = $coll->insert_many( [ @documents ], { ordered => 0 } );
215 Inserts each of the documents in an array reference into the database
217 and returns a MongoDB::InsertManyResult or
218 MongoDB::UnacknowledgedResult. This is syntactic sugar for doing a
219 MongoDB::BulkWrite operation.
220 If no "_id" field is present, one will be added when a document is
222 serialized for the database without modifying the original document.
223 The generated "_id" may be retrieved from the result object.
224 An optional hash reference of options may be provided.
226 Valid options include:
228 · "bypassDocumentValidation" - skips document validation, if enabled;
230 this is ignored for MongoDB servers older than version 3.2.
231 · "session" - the session to use for these operations. If not
233 supplied, will use an implicit session. For more information see
234 MongoDB::ClientSession
235 · "ordered" – when true, the server will halt insertions after the
237 first error (if any). When false, all documents will be processed
238 and any error will only be thrown after all insertions are
239 attempted. The default is true.
240 On MongoDB servers before version 2.6, "insert_many" bulk operations
242 are emulated with individual inserts to capture error information. On
243 2.6 or later, this method will be significantly faster than individual
244 "insert_one" calls.
245 delete_one
247 $res = $coll->delete_one( $filter );
248 $res = $coll->delete_one( { _id => $id } );
249 $res = $coll->delete_one( $filter, { collation => { locale => "en_US" } } );
250 Deletes a single document that matches a filter expression and returns
252 a MongoDB::DeleteResult or MongoDB::UnacknowledgedResult object.
253 A hash reference of options may be provided.
255 Valid options include:
257 · "collation" - a document defining the collation for this operation.
259 See docs for the format of the collation document here:
260 <https://docs.mongodb.com/master/reference/collation/>.
261 · "session" - the session to use for these operations. If not
263 supplied, will use an implicit session. For more information see
264 MongoDB::ClientSession
265 delete_many
267 $res = $coll->delete_many( $filter );
268 $res = $coll->delete_many( { name => "Larry" } );
269 $res = $coll->delete_many( $filter, { collation => { locale => "en_US" } } );
270 Deletes all documents that match a filter expression and returns a
272 MongoDB::DeleteResult or MongoDB::UnacknowledgedResult object.
273 Valid options include:
275 · "collation" - a document defining the collation for this operation.
277 See docs for the format of the collation document here:
278 <https://docs.mongodb.com/master/reference/collation/>.
279 · "session" - the session to use for these operations. If not
281 supplied, will use an implicit session. For more information see
282 MongoDB::ClientSession
283 replace_one
285 $res = $coll->replace_one( $filter, $replacement );
286 $res = $coll->replace_one( $filter, $replacement, { upsert => 1 } );
287 Replaces one document that matches a filter expression and returns a
289 MongoDB::UpdateResult or MongoDB::UnacknowledgedResult object.
290 The replacement document must not have any field-update operators in it
292 (e.g. $set).
293 A hash reference of options may be provided.
295 Valid options include:
297 · "bypassDocumentValidation" - skips document validation, if enabled;
299 this is ignored for MongoDB servers older than version 3.2.
300 · "collation" - a document defining the collation for this operation.
302 See docs for the format of the collation document here:
303 <https://docs.mongodb.com/master/reference/collation/>.
304 · "session" - the session to use for these operations. If not
306 supplied, will use an implicit session. For more information see
307 MongoDB::ClientSession
308 · "upsert" – defaults to false; if true, a new document will be added
310 if one is not found
311 update_one
313 $res = $coll->update_one( $filter, $update );
314 $res = $coll->update_one( $filter, $update, { upsert => 1 } );
315 Updates one document that matches a filter expression and returns a
317 MongoDB::UpdateResult or MongoDB::UnacknowledgedResult object.
318 The update document must have only field-update operators in it (e.g.
320 $set).
321 A hash reference of options may be provided.
323 Valid options include:
325 · "arrayFilters" - An array of filter documents that determines which
327 array elements to modify for an update operation on an array field.
328 Only available for MongoDB servers of version 3.6+.
329 · "bypassDocumentValidation" - skips document validation, if enabled;
331 this is ignored for MongoDB servers older than version 3.2.
332 · "collation" - a document defining the collation for this operation.
334 See docs for the format of the collation document here:
335 <https://docs.mongodb.com/master/reference/collation/>.
336 · "session" - the session to use for these operations. If not
338 supplied, will use an implicit session. For more information see
339 MongoDB::ClientSession
340 · "upsert" – defaults to false; if true, a new document will be added
342 if one is not found by taking the filter expression and applying
343 the update document operations to it prior to insertion.
344 update_many
346 $res = $coll->update_many( $filter, $update );
347 $res = $coll->update_many( $filter, $update, { upsert => 1 } );
348 Updates one or more documents that match a filter expression and
350 returns a MongoDB::UpdateResult or MongoDB::UnacknowledgedResult
351 object.
352 The update document must have only field-update operators in it (e.g.
354 $set).
355 A hash reference of options may be provided.
357 Valid options include:
359 · "arrayFilters" - An array of filter documents that determines which
361 array elements to modify for an update operation on an array field.
362 Only available for MongoDB servers of version 3.6+.
363 · "bypassDocumentValidation" - skips document validation, if enabled;
365 this is ignored for MongoDB servers older than version 3.2.
366 · "collation" - a document defining the collation for this operation.
368 See docs for the format of the collation document here:
369 <https://docs.mongodb.com/master/reference/collation/>.
370 · "session" - the session to use for these operations. If not
372 supplied, will use an implicit session. For more information see
373 MongoDB::ClientSession
374 · "upsert" – defaults to false; if true, a new document will be added
376 if one is not found by taking the filter expression and applying
377 the update document operations to it prior to insertion.
378 find
380 $cursor = $coll->find( $filter );
381 $cursor = $coll->find( $filter, $options );
382 $cursor = $coll->find({ i => { '$gt' => 42 } }, {limit => 20});
384 Executes a query with a filter expression and returns a lazy
386 "MongoDB::Cursor" object. (The query is not immediately issued to the
387 server; see below for details.)
388 The query can be customized using MongoDB::Cursor methods, or with an
390 optional hash reference of options.
391 Valid options include:
393 · "allowPartialResults" - get partial results from a mongos if some
395 shards are down (instead of throwing an error).
396 · "batchSize" – the number of documents to return per batch.
398 · "collation" - a document defining the collation for this operation.
400 See docs for the format of the collation document here:
401 <https://docs.mongodb.com/master/reference/collation/>.
402 · "comment" – attaches a comment to the query.
404 · "cursorType" – indicates the type of cursor to use. It must be one
406 of three string values: 'non_tailable' (the default), 'tailable',
407 and 'tailable_await'.
408 · "hint" – specify an index to use
410 <http://docs.mongodb.org/manual/reference/command/count/#specify-
411 the-index-to-use>; must be a string, array reference, hash
412 reference or Tie::IxHash object.
413 · "limit" – the maximum number of documents to return.
415 · "max" – specify the exclusive upper bound for a specific index.
417 · "maxAwaitTimeMS" – the maximum amount of time for the server to
419 wait on new documents to satisfy a tailable cursor query. This only
420 applies to a "cursorType" of 'tailable_await'; the option is
421 otherwise ignored. (Note, this will be ignored for servers before
422 version 3.2.)
423 · "maxScan" – (DEPRECATED) maximum number of documents or index keys
425 to scan.
426 · "maxTimeMS" – the maximum amount of time to allow the query to run.
428 (Note, this will be ignored for servers before version 2.6.)
429 · "min" – specify the inclusive lower bound for a specific index.
431 · "modifiers" – (DEPRECATED) a hash reference of dollar-prefixed
433 query modifiers
434 <http://docs.mongodb.org/manual/reference/operator/query-modifier/>
435 modifying the output or behavior of a query. Top-level options will
436 always take precedence over corresponding modifiers. Supported
437 modifiers include $comment, $hint, $maxScan, $maxTimeMS, $max,
438 $min, $orderby, $returnKey, $showDiskLoc, and $snapshot. Some
439 options may not be supported by newer server versions.
440 · "noCursorTimeout" – if true, prevents the server from timing out a
442 cursor after a period of inactivity.
443 · "projection" - a hash reference defining fields to return. See
445 "limit fields to return
446 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
447 results/>" in the MongoDB documentation for details.
448 · "session" - the session to use for these operations. If not
450 supplied, will use an implicit session. For more information see
451 MongoDB::ClientSession
452 · "returnKey" – Only return the index field or fields for the results
454 of the query
455 <https://docs.mongodb.com/manual/reference/operator/meta/returnKey/>.
456 · "showRecordId" – modifies the output of a query by adding a field
458 $recordId
459 <https://docs.mongodb.com/manual/reference/method/cursor.showRecordId/>
460 that uniquely identifies a document in a collection.
461 · "skip" – the number of documents to skip before returning.
463 · "sort" – an ordered document defining the order in which to return
465 matching documents. See the $orderby documentation
466 <https://docs.mongodb.com/manual/reference/operator/meta/orderby/>
467 for examples.
468 For more information, see the Read Operations Overview
470 <http://docs.mongodb.org/manual/core/read-operations-introduction/> in
471 the MongoDB documentation.
472 Note, a MongoDB::Cursor object holds the query and does not issue the
474 query to the server until the result method is called on it or until an
475 iterator method like next is called. Performance will be better
476 directly on a MongoDB::QueryResult object:
477 my $query_result = $coll->find( $filter )->result;
479 while ( my $next = $query_result->next ) {
481 ...
482 }
483 find_one
485 $doc = $collection->find_one( $filter, $projection );
486 $doc = $collection->find_one( $filter, $projection, $options );
487 Executes a query with a filter expression and returns a single
489 document.
490 If a projection argument is provided, it must be a hash reference
492 specifying fields to return. See Limit fields to return
493 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
494 results/> in the MongoDB documentation for details.
495 If only a filter is provided or if the projection document is an empty
497 hash reference, all fields will be returned.
498 my $doc = $collection->find_one( $filter );
500 my $doc = $collection->find_one( $filter, {}, $options );
501 A hash reference of options may be provided as a third argument. Valid
503 keys include:
504 · "collation" - a document defining the collation for this operation.
506 See docs for the format of the collation document here:
507 <https://docs.mongodb.com/master/reference/collation/>.
508 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
510 the command to run. (Note, this will be ignored for servers before
511 version 2.6.)
512 · "session" - the session to use for these operations. If not
514 supplied, will use an implicit session. For more information see
515 MongoDB::ClientSession
516 · "sort" – an ordered document defining the order in which to return
518 matching documents. If $orderby also exists in the modifiers
519 document, the sort field overwrites $orderby. See docs for
520 $orderby
521 <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
522 See also core documentation on querying:
524 <http://docs.mongodb.org/manual/core/read/>.
525 find_id
527 $doc = $collection->find_id( $id );
528 $doc = $collection->find_id( $id, $projection );
529 $doc = $collection->find_id( $id, $projection, $options );
530 Executes a query with a filter expression of "{ _id => $id }" and
532 returns a single document.
533 See the find_one documentation for details on the $projection and
535 $options parameters.
536 See also core documentation on querying:
538 <http://docs.mongodb.org/manual/core/read/>.
539 find_one_and_delete
541 $doc = $coll->find_one_and_delete( $filter );
542 $doc = $coll->find_one_and_delete( $filter, $options );
543 Given a filter expression, this deletes a document from the database
545 and returns it as it appeared before it was deleted.
546 A hash reference of options may be provided. Valid keys include:
548 · "collation" - a document defining the collation for this operation.
550 See docs for the format of the collation document here:
551 <https://docs.mongodb.com/master/reference/collation/>.
552 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
554 the command to run. (Note, this will be ignored for servers before
555 version 2.6.)
556 · "projection" - a hash reference defining fields to return. See
558 "limit fields to return
559 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
560 results/>" in the MongoDB documentation for details.
561 · "session" - the session to use for these operations. If not
563 supplied, will use an implicit session. For more information see
564 MongoDB::ClientSession
565 · "sort" – an ordered document defining the order in which to return
567 matching documents. See docs for $orderby
568 <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
569 find_one_and_replace
571 $doc = $coll->find_one_and_replace( $filter, $replacement );
572 $doc = $coll->find_one_and_replace( $filter, $replacement, $options );
573 Given a filter expression and a replacement document, this replaces a
575 document from the database and returns it as it was either right before
576 or right after the replacement. The default is 'before'.
577 The replacement document must not have any field-update operators in it
579 (e.g. $set).
580 A hash reference of options may be provided. Valid keys include:
582 · "bypassDocumentValidation" - skips document validation, if enabled;
584 this is ignored for MongoDB servers older than version 3.2.
585 · "collation" - a document defining the collation for this operation.
587 See docs for the format of the collation document here:
588 <https://docs.mongodb.com/master/reference/collation/>.
589 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
591 the command to run.
592 · "projection" - a hash reference defining fields to return. See
594 "limit fields to return
595 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
596 results/>" in the MongoDB documentation for details.
597 · "returnDocument" – either the string 'before' or 'after', to
599 indicate whether the returned document should be the one before or
600 after replacement. The default is 'before'.
601 · "session" - the session to use for these operations. If not
603 supplied, will use an implicit session. For more information see
604 MongoDB::ClientSession
605 · "sort" – an ordered document defining the order in which to return
607 matching documents. See docs for $orderby
608 <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
609 · "upsert" – defaults to false; if true, a new document will be added
611 if one is not found
612 find_one_and_update
614 $doc = $coll->find_one_and_update( $filter, $update );
615 $doc = $coll->find_one_and_update( $filter, $update, $options );
616 Given a filter expression and a document of update operators, this
618 updates a single document and returns it as it was either right before
619 or right after the update. The default is 'before'.
620 The update document must contain only field-update operators (e.g.
622 $set).
623 A hash reference of options may be provided. Valid keys include:
625 · "arrayFilters" - An array of filter documents that determines which
627 array elements to modify for an update operation on an array field.
628 Only available for MongoDB servers of version 3.6+.
629 · "bypassDocumentValidation" - skips document validation, if enabled;
631 this is ignored for MongoDB servers older than version 3.2.
632 · "collation" - a document defining the collation for this operation.
634 See docs for the format of the collation document here:
635 <https://docs.mongodb.com/master/reference/collation/>.
636 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
638 the command to run. (Note, this will be ignored for servers before
639 version 2.6.)
640 · "projection" - a hash reference defining fields to return. See
642 "limit fields to return
643 <http://docs.mongodb.org/manual/tutorial/project-fields-from-query-
644 results/>" in the MongoDB documentation for details.
645 · "returnDocument" – either the string 'before' or 'after', to
647 indicate whether the returned document should be the one before or
648 after replacement. The default is 'before'.
649 · "session" - the session to use for these operations. If not
651 supplied, will use an implicit session. For more information see
652 MongoDB::ClientSession
653 · "sort" – an ordered document defining the order in which to return
655 matching documents. See docs for $orderby
656 <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.
657 · "upsert" – defaults to false; if true, a new document will be added
659 if one is not found
660 watch
662 Watches for changes on this collection-
663 Perform an aggregation with an implicit initial $changeStream stage and
665 returns a MongoDB::ChangeStream result which can be used to iterate
666 over the changes in the collection. This functionality is available
667 since MongoDB 3.6.
668 my $stream = $collection->watch();
670 my $stream = $collection->watch( \@pipeline );
671 my $stream = $collection->watch( \@pipeline, \%options );
672 while (1) {
674 # This inner loop will only run until no more changes are
676 # available.
677 while (my $change = $stream->next) {
678 # process $change
679 }
680 }
681 The returned stream will not block forever waiting for changes. If you
683 want to respond to changes over a longer time use "maxAwaitTimeMS" and
684 regularly call "next" in a loop.
685 Note: Using this helper method is preferred to manually aggregating
687 with a $changeStream stage, since it will automatically resume when the
688 connection was terminated.
689 The optional first argument must be an array-ref of aggregation
691 pipeline <http://docs.mongodb.org/manual/core/aggregation-pipeline/>
692 documents. Each pipeline document must be a hash reference. Not all
693 pipeline stages are supported after $changeStream.
694 The optional second argument is a hash reference with options:
696 · "fullDocument" - The fullDocument to pass as an option to the
698 $changeStream stage. Allowed values: "default", "updateLookup".
699 Defaults to "default". When set to "updateLookup", the change
700 notification for partial updates will include both a delta
701 describing the changes to the document, as well as a copy of the
702 entire document that was changed from some time after the change
703 occurred.
704 · "resumeAfter" - The logical starting point for this change stream.
706 This value can be obtained from the "_id" field of a document
707 returned by "next" in MongoDB::ChangeStream. Cannot be specified
708 together with "startAtOperationTime"
709 · "maxAwaitTimeMS" - The maximum number of milliseconds for the
711 server to wait before responding.
712 · "startAtOperationTime" - A BSON::Timestamp specifying at what point
714 in time changes will start being watched. Cannot be specified
715 together with "resumeAfter". Plain values will be coerced to
716 BSON::Timestamp objects.
717 · "session" - the session to use for these operations. If not
719 supplied, will use an implicit session. For more information see
720 MongoDB::ClientSession
721 See "aggregate" for more available options.
723 See the manual section on Change Streams
725 <https://docs.mongodb.com/manual/changeStreams/> for general usage
726 information on change streams.
727 See the Change Streams specification
729 <https://github.com/mongodb/specifications/blob/master/source/change-
730 streams.rst> for details on change streams.
731 aggregate
733 @pipeline = (
734 { '$group' => { _id => '$state,' totalPop => { '$sum' => '$pop' } } },
735 { '$match' => { totalPop => { '$gte' => 10 * 1000 * 1000 } } }
736 );
737 $result = $collection->aggregate( \@pipeline );
739 $result = $collection->aggregate( \@pipeline, $options );
740 Runs a query using the MongoDB 2.2+ aggregation framework and returns a
742 MongoDB::QueryResult object.
743 The first argument must be an array-ref of aggregation pipeline
745 <http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents.
746 Each pipeline document must be a hash reference.
747 Note: Some pipeline documents have ordered arguments, such as $sort.
749 Be sure to provide these argument using Tie::IxHash. E.g.:
750 { '$sort' => Tie::IxHash->new( age => -1, posts => 1 ) }
752 A hash reference of options may be provided. Valid keys include:
754 · "allowDiskUse" – if, true enables writing to temporary files.
756 · "batchSize" – the number of documents to return per batch.
758 · "bypassDocumentValidation" - skips document validation, if enabled.
760 (Note, this will be ignored for servers before version 3.2.)
761 · "collation" - a document defining the collation for this operation.
763 See docs for the format of the collation document here:
764 <https://docs.mongodb.com/master/reference/collation/>.
765 · "explain" – if true, return a single document with execution
767 information.
768 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
770 the command to run. (Note, this will be ignored for servers before
771 version 2.6.)
772 · "hint" - An index to use for this aggregation. (Only compatible
774 with servers above version 3.6.) For more information, see the
775 other aggregate options here:
776 <https://docs.mongodb.com/manual/reference/command/aggregate/index.html>
777 · "session" - the session to use for these operations. If not
779 supplied, will use an implicit session. For more information see
780 MongoDB::ClientSession
781 Note MongoDB 2.6+ added the '$out' pipeline operator. If this operator
783 is used to write aggregation results directly to a collection, an empty
784 result will be returned. Create a new collection> object to query the
785 generated result collection. When $out is used, the command is treated
786 as a write operation and read preference is ignored.
787 See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the
789 MongoDB manual for more information on how to construct aggregation
790 queries.
791 Note The use of aggregation cursors is automatic based on your server
793 version. However, if migrating a sharded cluster from MongoDB 2.4 to
794 2.6 or later, you must upgrade your mongod servers first before your
795 mongos routers or aggregation queries will fail. As a workaround, you
796 may pass "cursor => undef" as an option.
797 count_documents
799 $count = $coll->count_documents( $filter );
800 $count = $coll->count_documents( $filter, $options );
801 Returns a count of documents matching a filter expression. To return a
803 count of all documents, use an empty hash reference as the filter.
804 NOTE: this may result in a scan of all documents in the collection.
806 For a fast count of the total documents in a collection see
807 "estimated_document_count" instead.
808 A hash reference of options may be provided. Valid keys include:
810 · "collation" - a document defining the collation for this operation.
812 See docs for the format of the collation document here:
813 <https://docs.mongodb.com/master/reference/collation/>.
814 · "hint" – specify an index to use; must be a string, array
816 reference, hash reference or Tie::IxHash object. (Requires server
817 version 3.6 or later.)
818 · "limit" – the maximum number of documents to count.
820 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
822 the command to run. (Note, this will be ignored for servers before
823 version 2.6.)
824 · "skip" – the number of documents to skip before counting documents.
826 · "session" - the session to use for these operations. If not
828 supplied, will use an implicit session. For more information see
829 MongoDB::ClientSession
830 NOTE: When upgrading from the deprecated "count" method, some legacy
832 operators are not supported and must be replaced:
833 +-------------+--------------------------------+
835 | Legacy | Modern Replacement |
836 +=============+================================+
837 | $where | $expr (Requires MongoDB 3.6+) |
838 +-------------+--------------------------------+
839 | $near | $geoWithin with $center |
840 +-------------+--------------------------------+
841 | $nearSphere | $geoWithin with $centerSphere |
842 +-------------+--------------------------------+
843 estimated_document_count
845 $count = $coll->estimated_document_count();
846 $count = $coll->estimated_document_count($options);
847 Returns an estimated count of documents based on collection metadata.
849 NOTE: this method does not support sessions or transactions.
851 A hash reference of options may be provided. Valid keys include:
853 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
855 the command to run. (Note, this will be ignored for servers before
856 version 2.6.)
857 distinct
859 $result = $coll->distinct( $fieldname );
860 $result = $coll->distinct( $fieldname, $filter );
861 $result = $coll->distinct( $fieldname, $filter, $options );
862 Returns a MongoDB::QueryResult object that will provide distinct values
864 for a specified field name.
865 The query may be limited by an optional filter expression.
867 A hash reference of options may be provided. Valid keys include:
869 · "collation" - a document defining the collation for this operation.
871 See docs for the format of the collation document here:
872 <https://docs.mongodb.com/master/reference/collation/>.
873 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
875 the command to run. (Note, this will be ignored for servers before
876 version 2.6.)
877 · "session" - the session to use for these operations. If not
879 supplied, will use an implicit session. For more information see
880 MongoDB::ClientSession
881 See documentation for the distinct command
883 <http://docs.mongodb.org/manual/reference/command/distinct/> for
884 details.
885 rename
887 $newcollection = $collection->rename("mynewcollection");
888 Renames the collection. If a collection already exists with the new
890 collection name, this method will throw an exception.
891 A hashref of options may be provided.
893 Valid options include:
895 · "session" - the session to use for these operations. If not
897 supplied, will use an implicit session. For more information see
898 MongoDB::ClientSession
899 It returns a new MongoDB::Collection object corresponding to the
901 renamed collection.
902 drop
904 $collection->drop;
905 Deletes a collection as well as all of its indexes.
907 ordered_bulk
909 $bulk = $coll->ordered_bulk;
910 $bulk->insert_one( $doc1 );
911 $bulk->insert_one( $doc2 );
912 ...
913 $result = $bulk->execute;
914 Returns a MongoDB::BulkWrite object to group write operations into
916 fewer network round-trips. This method creates an ordered operation,
917 where operations halt after the first error. See MongoDB::BulkWrite for
918 more details.
919 The method "initialize_ordered_bulk_op" may be used as an alias.
921 A hash reference of options may be provided.
923 Valid options include:
925 · "bypassDocumentValidation" - skips document validation, if enabled;
927 this is ignored for MongoDB servers older than version 3.2.
928 unordered_bulk
930 This method works just like "ordered_bulk" except that the order that
931 operations are sent to the database is not guaranteed and errors do not
932 halt processing. See MongoDB::BulkWrite for more details.
933 The method "initialize_unordered_bulk_op" may be used as an alias.
935 A hash reference of options may be provided.
937 Valid options include:
939 · "bypassDocumentValidation" - skips document validation, if enabled;
941 this is ignored for MongoDB servers older than version 3.2.
942 bulk_write
944 $res = $coll->bulk_write( [ @requests ], $options )
945 This method provides syntactic sugar to construct and execute a bulk
947 operation directly, without using "initialize_ordered_bulk" or
948 "initialize_unordered_bulk" to generate a MongoDB::BulkWrite object and
949 then calling methods on it. It returns a MongoDB::BulkWriteResponse
950 object just like the MongoDB::BulkWrite execute method.
951 The first argument must be an array reference of requests. Requests
953 consist of pairs of a MongoDB::Collection write method name (e.g.
954 "insert_one", "delete_many") and an array reference of arguments to the
955 corresponding method name. They may be given as pairs, or as hash or
956 array references:
957 # pairs -- most efficient
959 @requests = (
960 insert_one => [ { x => 1 } ],
961 replace_one => [ { x => 1 }, { x => 4 } ],
962 delete_one => [ { x => 4 } ],
963 update_many => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ],
964 );
965 # hash references
967 @requests = (
968 { insert_one => [ { x => 1 } ] },
969 { replace_one => [ { x => 1 }, { x => 4 } ] },
970 { delete_one => [ { x => 4 } ] },
971 { update_many => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ] },
972 );
973 # array references
975 @requests = (
976 [ insert_one => [ { x => 1 } ] ],
977 [ replace_one => [ { x => 1 }, { x => 4 } ] ],
978 [ delete_one => [ { x => 4 } ] ],
979 [ update_many => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ] ],
980 );
981 Valid method names include "insert_one", "insert_many", "delete_one",
983 "delete_many" "replace_one", "update_one", "update_many".
984 An optional hash reference of options may be provided.
986 Valid options include:
988 · "bypassDocumentValidation" - skips document validation, if enabled;
990 this is ignored for MongoDB servers older than version 3.2.
991 · "ordered" – when true, the bulk operation is executed like
993 "initialize_ordered_bulk". When false, the bulk operation is
994 executed like "initialize_unordered_bulk". The default is true.
995 · "session" - the session to use for these operations. If not
997 supplied, will use an implicit session. For more information see
998 MongoDB::ClientSession
999 See MongoDB::BulkWrite for more details on bulk writes. Be advised
1001 that the legacy Bulk API method names differ slightly from
1002 MongoDB::Collection method names.
1003
1005 · David Golden <david@mongodb.com>
1006 · Rassi <rassi@mongodb.com>
1008 · Mike Friedman <friedo@friedo.com>
1010 · Kristina Chodorow <k.chodorow@gmail.com>
1012 · Florian Ragwitz <rafl@debian.org>
1014
1016 This software is Copyright (c) 2020 by MongoDB, Inc.
1017 This is free software, licensed under:
1019 The Apache License, Version 2.0, January 2004
1021perl v5.32.0 2020-08-18 MongoDB::Collection(3)