1MongoDB::Collection(3)User Contributed Perl DocumentationMongoDB::Collection(3)
2
3
4

NAME

6       MongoDB::Collection - A MongoDB Collection
7

VERSION

9       version v2.2.2
10

SYNOPSIS

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

DESCRIPTION

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

USAGE

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

ATTRIBUTES

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

METHODS

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

AUTHORS

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                      2023-01-20            MongoDB::Collection(3)
Impressum