1MongoDB::Collection(3)User Contributed Perl DocumentationMongoDB::Collection(3)
2
3
4
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
15 # insert a document
16 $coll->insert_one( { name => "John Doe", age => 42 } );
17
18 # insert one or more documents
19 $coll->insert_many( \@documents );
20
21 # delete a document
22 $coll->delete_one( { name => "John Doe" } );
23
24 # update a document
25 $coll->update_one( { name => "John Doe" }, { '$inc' => { age => 1 } } );
26
27 # find a single document
28 $doc = $coll->find_one( { name => "John Doe" } )
29
30 # Get a MongoDB::Cursor for a query
31 $cursor = $coll->find( { age => 42 } );
32
33 # 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
42 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
50 To catch and handle errors, the Try::Tiny and Safe::Isa modules are
51 recommended:
52
53 use Try::Tiny;
54 use Safe::Isa; # provides $_isa
55
56 try {
57 $coll->insert_one( $doc )
58 }
59 catch {
60 if ( $_->$_isa("MongoDB::DuplicateKeyError" ) {
61 ...
62 }
63 else {
64 ...
65 }
66 };
67
68 To retry failures automatically, consider using Try::Tiny::Retry.
69
70 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
78 For detailed instructions on using transactions with MongoDB, see the
79 MongoDB manual page: Transactions
80 <https://docs.mongodb.com/master/core/transactions>.
81
82 Terminology
83 Document
84
85 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
89 Ordered document
90
91 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
98 Filter expression
99
100 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
109 name
110 The name of the collection.
111
112 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
119 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
124 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
129 By default it will be inherited from a MongoDB::Database object.
130
131 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
135 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
138 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
148 Returns the MongoDB::MongoClient object associated with this object.
149
150 full_name
151 $full_name = $coll->full_name;
152
153 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
157 indexes
158 $indexes = $collection->indexes;
159
160 $collection->indexes->create_one( [ x => 1 ], { unique => 1 } );
161 $collection->indexes->drop_all;
162
163 Returns a MongoDB::IndexView object for managing the indexes associated
164 with the collection.
165
166 clone
167 $coll2 = $coll1->clone( write_concern => { w => 2 } );
168
169 Constructs a copy of the original collection, but allows changing
170 attributes in the copy.
171
172 with_codec
173 $coll2 = $coll1->with_codec( $new_codec );
174 $coll2 = $coll1->with_codec( prefer_numeric => 1 );
175
176 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
180 $coll2 = $coll1->clone( bson_codec => $new_codec );
181
182 If given a hash reference or a list of key/value pairs, it is
183 equivalent to:
184
185 $coll2 = $coll1->clone(
186 bson_codec => $coll1->bson_codec->clone( @list )
187 );
188
189 insert_one
190 $res = $coll->insert_one( $document );
191 $res = $coll->insert_one( $document, $options );
192 $id = $res->inserted_id;
193
194 Inserts a single document into the database and returns a
195 MongoDB::InsertOneResult or MongoDB::UnacknowledgedResult object.
196
197 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
201 An optional hash reference of options may be given.
202
203 Valid options include:
204
205 • "bypassDocumentValidation" - skips document validation, if enabled;
206 this is ignored for MongoDB servers older than version 3.2.
207
208 • "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
212 insert_many
213 $res = $coll->insert_many( [ @documents ] );
214 $res = $coll->insert_many( [ @documents ], { ordered => 0 } );
215
216 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
221 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
225 An optional hash reference of options may be provided.
226
227 Valid options include:
228
229 • "bypassDocumentValidation" - skips document validation, if enabled;
230 this is ignored for MongoDB servers older than version 3.2.
231
232 • "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
236 • "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
241 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
246 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
251 Deletes a single document that matches a filter expression and returns
252 a MongoDB::DeleteResult or MongoDB::UnacknowledgedResult object.
253
254 A hash reference of options may be provided.
255
256 Valid options include:
257
258 • "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
262 • "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
266 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
271 Deletes all documents that match a filter expression and returns a
272 MongoDB::DeleteResult or MongoDB::UnacknowledgedResult object.
273
274 Valid options include:
275
276 • "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
280 • "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
284 replace_one
285 $res = $coll->replace_one( $filter, $replacement );
286 $res = $coll->replace_one( $filter, $replacement, { upsert => 1 } );
287
288 Replaces one document that matches a filter expression and returns a
289 MongoDB::UpdateResult or MongoDB::UnacknowledgedResult object.
290
291 The replacement document must not have any field-update operators in it
292 (e.g. $set).
293
294 A hash reference of options may be provided.
295
296 Valid options include:
297
298 • "bypassDocumentValidation" - skips document validation, if enabled;
299 this is ignored for MongoDB servers older than version 3.2.
300
301 • "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
305 • "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
309 • "upsert" – defaults to false; if true, a new document will be added
310 if one is not found
311
312 update_one
313 $res = $coll->update_one( $filter, $update );
314 $res = $coll->update_one( $filter, $update, { upsert => 1 } );
315
316 Updates one document that matches a filter expression and returns a
317 MongoDB::UpdateResult or MongoDB::UnacknowledgedResult object.
318
319 The update document must have only field-update operators in it (e.g.
320 $set).
321
322 A hash reference of options may be provided.
323
324 Valid options include:
325
326 • "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
330 • "bypassDocumentValidation" - skips document validation, if enabled;
331 this is ignored for MongoDB servers older than version 3.2.
332
333 • "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
337 • "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
341 • "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
345 update_many
346 $res = $coll->update_many( $filter, $update );
347 $res = $coll->update_many( $filter, $update, { upsert => 1 } );
348
349 Updates one or more documents that match a filter expression and
350 returns a MongoDB::UpdateResult or MongoDB::UnacknowledgedResult
351 object.
352
353 The update document must have only field-update operators in it (e.g.
354 $set).
355
356 A hash reference of options may be provided.
357
358 Valid options include:
359
360 • "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
364 • "bypassDocumentValidation" - skips document validation, if enabled;
365 this is ignored for MongoDB servers older than version 3.2.
366
367 • "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
371 • "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
375 • "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
379 find
380 $cursor = $coll->find( $filter );
381 $cursor = $coll->find( $filter, $options );
382
383 $cursor = $coll->find({ i => { '$gt' => 42 } }, {limit => 20});
384
385 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
389 The query can be customized using MongoDB::Cursor methods, or with an
390 optional hash reference of options.
391
392 Valid options include:
393
394 • "allowPartialResults" - get partial results from a mongos if some
395 shards are down (instead of throwing an error).
396
397 • "batchSize" – the number of documents to return per batch.
398
399 • "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
403 • "comment" – attaches a comment to the query.
404
405 • "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
409 • "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
414 • "limit" – the maximum number of documents to return.
415
416 • "max" – specify the exclusive upper bound for a specific index.
417
418 • "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
424 • "maxScan" – (DEPRECATED) maximum number of documents or index keys
425 to scan.
426
427 • "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
430 • "min" – specify the inclusive lower bound for a specific index.
431
432 • "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
441 • "noCursorTimeout" – if true, prevents the server from timing out a
442 cursor after a period of inactivity.
443
444 • "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
449 • "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
453 • "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
457 • "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
462 • "skip" – the number of documents to skip before returning.
463
464 • "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
469 For more information, see the Read Operations Overview
470 <http://docs.mongodb.org/manual/core/read-operations-introduction/> in
471 the MongoDB documentation.
472
473 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
478 my $query_result = $coll->find( $filter )->result;
479
480 while ( my $next = $query_result->next ) {
481 ...
482 }
483
484 find_one
485 $doc = $collection->find_one( $filter, $projection );
486 $doc = $collection->find_one( $filter, $projection, $options );
487
488 Executes a query with a filter expression and returns a single
489 document.
490
491 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
496 If only a filter is provided or if the projection document is an empty
497 hash reference, all fields will be returned.
498
499 my $doc = $collection->find_one( $filter );
500 my $doc = $collection->find_one( $filter, {}, $options );
501
502 A hash reference of options may be provided as a third argument. Valid
503 keys include:
504
505 • "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
509 • "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
513 • "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
517 • "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
523 See also core documentation on querying:
524 <http://docs.mongodb.org/manual/core/read/>.
525
526 find_id
527 $doc = $collection->find_id( $id );
528 $doc = $collection->find_id( $id, $projection );
529 $doc = $collection->find_id( $id, $projection, $options );
530
531 Executes a query with a filter expression of "{ _id => $id }" and
532 returns a single document.
533
534 See the find_one documentation for details on the $projection and
535 $options parameters.
536
537 See also core documentation on querying:
538 <http://docs.mongodb.org/manual/core/read/>.
539
540 find_one_and_delete
541 $doc = $coll->find_one_and_delete( $filter );
542 $doc = $coll->find_one_and_delete( $filter, $options );
543
544 Given a filter expression, this deletes a document from the database
545 and returns it as it appeared before it was deleted.
546
547 A hash reference of options may be provided. Valid keys include:
548
549 • "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
553 • "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
557 • "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
562 • "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
566 • "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
570 find_one_and_replace
571 $doc = $coll->find_one_and_replace( $filter, $replacement );
572 $doc = $coll->find_one_and_replace( $filter, $replacement, $options );
573
574 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
578 The replacement document must not have any field-update operators in it
579 (e.g. $set).
580
581 A hash reference of options may be provided. Valid keys include:
582
583 • "bypassDocumentValidation" - skips document validation, if enabled;
584 this is ignored for MongoDB servers older than version 3.2.
585
586 • "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
590 • "maxTimeMS" – the maximum amount of time in milliseconds to allow
591 the command to run.
592
593 • "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
598 • "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
602 • "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
606 • "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
610 • "upsert" – defaults to false; if true, a new document will be added
611 if one is not found
612
613 find_one_and_update
614 $doc = $coll->find_one_and_update( $filter, $update );
615 $doc = $coll->find_one_and_update( $filter, $update, $options );
616
617 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
621 The update document must contain only field-update operators (e.g.
622 $set).
623
624 A hash reference of options may be provided. Valid keys include:
625
626 • "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
630 • "bypassDocumentValidation" - skips document validation, if enabled;
631 this is ignored for MongoDB servers older than version 3.2.
632
633 • "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
637 • "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
641 • "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
646 • "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
650 • "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
654 • "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
658 • "upsert" – defaults to false; if true, a new document will be added
659 if one is not found
660
661 watch
662 Watches for changes on this collection-
663
664 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
669 my $stream = $collection->watch();
670 my $stream = $collection->watch( \@pipeline );
671 my $stream = $collection->watch( \@pipeline, \%options );
672
673 while (1) {
674
675 # 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
682 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
686 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
690 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
695 The optional second argument is a hash reference with options:
696
697 • "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
705 • "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
710 • "maxAwaitTimeMS" - The maximum number of milliseconds for the
711 server to wait before responding.
712
713 • "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
718 • "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
722 See "aggregate" for more available options.
723
724 See the manual section on Change Streams
725 <https://docs.mongodb.com/manual/changeStreams/> for general usage
726 information on change streams.
727
728 See the Change Streams specification
729 <https://github.com/mongodb/specifications/blob/master/source/change-
730 streams.rst> for details on change streams.
731
732 aggregate
733 @pipeline = (
734 { '$group' => { _id => '$state,' totalPop => { '$sum' => '$pop' } } },
735 { '$match' => { totalPop => { '$gte' => 10 * 1000 * 1000 } } }
736 );
737
738 $result = $collection->aggregate( \@pipeline );
739 $result = $collection->aggregate( \@pipeline, $options );
740
741 Runs a query using the MongoDB 2.2+ aggregation framework and returns a
742 MongoDB::QueryResult object.
743
744 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
748 Note: Some pipeline documents have ordered arguments, such as $sort.
749 Be sure to provide these argument using Tie::IxHash. E.g.:
750
751 { '$sort' => Tie::IxHash->new( age => -1, posts => 1 ) }
752
753 A hash reference of options may be provided. Valid keys include:
754
755 • "allowDiskUse" – if, true enables writing to temporary files.
756
757 • "batchSize" – the number of documents to return per batch.
758
759 • "bypassDocumentValidation" - skips document validation, if enabled.
760 (Note, this will be ignored for servers before version 3.2.)
761
762 • "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
766 • "explain" – if true, return a single document with execution
767 information.
768
769 • "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
773 • "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
778 • "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
782 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
788 See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the
789 MongoDB manual for more information on how to construct aggregation
790 queries.
791
792 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
798 count_documents
799 $count = $coll->count_documents( $filter );
800 $count = $coll->count_documents( $filter, $options );
801
802 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
805 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
809 A hash reference of options may be provided. Valid keys include:
810
811 • "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
815 • "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
819 • "limit" – the maximum number of documents to count.
820
821 • "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
825 • "skip" – the number of documents to skip before counting documents.
826
827 • "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
831 NOTE: When upgrading from the deprecated "count" method, some legacy
832 operators are not supported and must be replaced:
833
834 +-------------+--------------------------------+
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
844 estimated_document_count
845 $count = $coll->estimated_document_count();
846 $count = $coll->estimated_document_count($options);
847
848 Returns an estimated count of documents based on collection metadata.
849
850 NOTE: this method does not support sessions or transactions.
851
852 A hash reference of options may be provided. Valid keys include:
853
854 • "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
858 distinct
859 $result = $coll->distinct( $fieldname );
860 $result = $coll->distinct( $fieldname, $filter );
861 $result = $coll->distinct( $fieldname, $filter, $options );
862
863 Returns a MongoDB::QueryResult object that will provide distinct values
864 for a specified field name.
865
866 The query may be limited by an optional filter expression.
867
868 A hash reference of options may be provided. Valid keys include:
869
870 • "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
874 • "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
878 • "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
882 See documentation for the distinct command
883 <http://docs.mongodb.org/manual/reference/command/distinct/> for
884 details.
885
886 rename
887 $newcollection = $collection->rename("mynewcollection");
888
889 Renames the collection. If a collection already exists with the new
890 collection name, this method will throw an exception.
891
892 A hashref of options may be provided.
893
894 Valid options include:
895
896 • "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
900 It returns a new MongoDB::Collection object corresponding to the
901 renamed collection.
902
903 drop
904 $collection->drop;
905
906 Deletes a collection as well as all of its indexes.
907
908 ordered_bulk
909 $bulk = $coll->ordered_bulk;
910 $bulk->insert_one( $doc1 );
911 $bulk->insert_one( $doc2 );
912 ...
913 $result = $bulk->execute;
914
915 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
920 The method "initialize_ordered_bulk_op" may be used as an alias.
921
922 A hash reference of options may be provided.
923
924 Valid options include:
925
926 • "bypassDocumentValidation" - skips document validation, if enabled;
927 this is ignored for MongoDB servers older than version 3.2.
928
929 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
934 The method "initialize_unordered_bulk_op" may be used as an alias.
935
936 A hash reference of options may be provided.
937
938 Valid options include:
939
940 • "bypassDocumentValidation" - skips document validation, if enabled;
941 this is ignored for MongoDB servers older than version 3.2.
942
943 bulk_write
944 $res = $coll->bulk_write( [ @requests ], $options )
945
946 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
952 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
958 # 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
966 # 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
974 # 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
982 Valid method names include "insert_one", "insert_many", "delete_one",
983 "delete_many" "replace_one", "update_one", "update_many".
984
985 An optional hash reference of options may be provided.
986
987 Valid options include:
988
989 • "bypassDocumentValidation" - skips document validation, if enabled;
990 this is ignored for MongoDB servers older than version 3.2.
991
992 • "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
996 • "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
1000 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
1007 • Rassi <rassi@mongodb.com>
1008
1009 • Mike Friedman <friedo@friedo.com>
1010
1011 • Kristina Chodorow <k.chodorow@gmail.com>
1012
1013 • Florian Ragwitz <rafl@debian.org>
1014
1016 This software is Copyright (c) 2020 by MongoDB, Inc.
1017
1018 This is free software, licensed under:
1019
1020 The Apache License, Version 2.0, January 2004
1021
1022
1023
1024perl v5.36.0 2022-07-22 MongoDB::Collection(3)