{
    "mode": "perldoc",
    "parameter": "MongoDB::Collection",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/MongoDB%3A%3ACollection/json",
    "generated": "2026-06-09T21:03:05Z",
    "synopsis": "# get a Collection via the Database object\n$coll = $db->getcollection(\"people\");\n# insert a document\n$coll->insertone( { name => \"John Doe\", age => 42 } );\n# insert one or more documents\n$coll->insertmany( \\@documents );\n# delete a document\n$coll->deleteone( { name => \"John Doe\" } );\n# update a document\n$coll->updateone( { name => \"John Doe\" }, { '$inc' => { age => 1 } } );\n# find a single document\n$doc = $coll->findone( { name => \"John Doe\" } )\n# Get a MongoDB::Cursor for a query\n$cursor = $coll->find( { age => 42 } );\n# Cursor iteration\nwhile ( my $doc = $cursor->next ) {\n...\n}",
    "sections": {
        "NAME": {
            "content": "MongoDB::Collection - A MongoDB Collection\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version v2.2.2\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "# get a Collection via the Database object\n$coll = $db->getcollection(\"people\");\n\n# insert a document\n$coll->insertone( { name => \"John Doe\", age => 42 } );\n\n# insert one or more documents\n$coll->insertmany( \\@documents );\n\n# delete a document\n$coll->deleteone( { name => \"John Doe\" } );\n\n# update a document\n$coll->updateone( { name => \"John Doe\" }, { '$inc' => { age => 1 } } );\n\n# find a single document\n$doc = $coll->findone( { name => \"John Doe\" } )\n\n# Get a MongoDB::Cursor for a query\n$cursor = $coll->find( { age => 42 } );\n\n# Cursor iteration\nwhile ( my $doc = $cursor->next ) {\n...\n}\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This class models a MongoDB collection and provides an API for interacting with it.\n\nGenerally, you never construct one of these directly with \"new\". Instead, you call\n\"getcollection\" on a MongoDB::Database object.\n",
            "subsections": []
        },
        "USAGE": {
            "content": "",
            "subsections": [
                {
                    "name": "Error handling",
                    "content": "Unless otherwise explicitly documented, all methods throw exceptions if an error occurs. The\nerror types are documented in MongoDB::Error.\n\nTo catch and handle errors, the Try::Tiny and Safe::Isa modules are recommended:\n\nuse Try::Tiny;\nuse Safe::Isa; # provides $isa\n\ntry {\n$coll->insertone( $doc )\n}\ncatch {\nif ( $->$isa(\"MongoDB::DuplicateKeyError\" ) {\n...\n}\nelse {\n...\n}\n};\n\nTo retry failures automatically, consider using Try::Tiny::Retry.\n"
                },
                {
                    "name": "Transactions",
                    "content": "To conduct operations in a transactions, get a MongoDB::ClientSession from \"startsession\" in\nMongoDB::MongoClient. Start the transaction on the session using \"starttransaction\" and pass\nthe session as an option to all operations. Then call \"committransaction\" or\n\"aborttransaction\" on the session. See the MongoDB::ClientSession for options and usage\ndetails.\n\nFor detailed instructions on using transactions with MongoDB, see the MongoDB manual page:\nTransactions <https://docs.mongodb.com/master/core/transactions>.\n"
                },
                {
                    "name": "Terminology",
                    "content": "Document\nA collection of key-value pairs. A Perl hash is a document. Array references with an even number\nof elements and Tie::IxHash objects may also be used as documents.\n\nOrdered document\nMany MongoDB::Collection method parameters or options require an ordered document: an ordered\nlist of key/value pairs. Perl's hashes are not ordered and since Perl v5.18 are guaranteed to\nhave random order. Therefore, when an ordered document is called for, you may use an array\nreference of pairs or a Tie::IxHash object. You may use a hash reference if there is only one\nkey/value pair.\n\nFilter expression\nA filter expression provides the query criteria\n<http://docs.mongodb.org/manual/tutorial/query-documents/> to select a document for deletion. It\nmust be an \"Ordered document\".\n"
                }
            ]
        },
        "ATTRIBUTES": {
            "content": "database\nThe MongoDB::Database representing the database that contains the collection.\n\nname\nThe name of the collection.\n\nreadpreference\nA MongoDB::ReadPreference object. It may be initialized with a string corresponding to one of\nthe valid read preference modes or a hash reference that will be coerced into a new\nMongoDB::ReadPreference object. By default it will be inherited from a MongoDB::Database object.\n\nwriteconcern\nA MongoDB::WriteConcern object. It may be initialized with a hash reference that will be coerced\ninto a new MongoDB::WriteConcern object. By default it will be inherited from a\nMongoDB::Database object.\n\nreadconcern\nA MongoDB::ReadConcern object. May be initialized with a hash reference or a string that will be\ncoerced into the level of read concern.\n\nBy default it will be inherited from a MongoDB::Database object.\n\nmaxtimems\nSpecifies the default maximum amount of time in milliseconds that the server should use for\nworking on a query.\n\nNote: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS\nmeta-operator was introduced.\n\nbsoncodec\nAn object that provides the \"encodeone\" and \"decodeone\" methods, such as from BSON. It may be\ninitialized with a hash reference that will be coerced into a new BSON object. By default it\nwill be inherited from a MongoDB::Database object.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "client\n$client = $coll->client;\n\nReturns the MongoDB::MongoClient object associated with this object.\n\nfullname\n$fullname = $coll->fullname;\n\nReturns the full name of the collection, including the namespace of the database it's in\nprefixed with a dot character. E.g. collection \"foo\" in database \"test\" would result in a\n\"fullname\" of \"test.foo\".\n\nindexes\n$indexes = $collection->indexes;\n\n$collection->indexes->createone( [ x => 1 ], { unique => 1 } );\n$collection->indexes->dropall;\n\nReturns a MongoDB::IndexView object for managing the indexes associated with the collection.\n\nclone\n$coll2 = $coll1->clone( writeconcern => { w => 2 } );\n\nConstructs a copy of the original collection, but allows changing attributes in the copy.\n\nwithcodec\n$coll2 = $coll1->withcodec( $newcodec );\n$coll2 = $coll1->withcodec( prefernumeric => 1 );\n\nConstructs a copy of the original collection, but clones the \"bsoncodec\". If given an object\nthat does \"encodeone\" and \"decodeone\", it is equivalent to:\n\n$coll2 = $coll1->clone( bsoncodec => $newcodec );\n\nIf given a hash reference or a list of key/value pairs, it is equivalent to:\n\n$coll2 = $coll1->clone(\nbsoncodec => $coll1->bsoncodec->clone( @list )\n);\n\ninsertone\n$res = $coll->insertone( $document );\n$res = $coll->insertone( $document, $options );\n$id = $res->insertedid;\n\nInserts a single document into the database and returns a MongoDB::InsertOneResult or\nMongoDB::UnacknowledgedResult object.\n\nIf no \"id\" field is present, one will be added when a document is serialized for the database\nwithout modifying the original document. The generated \"id\" may be retrieved from the result\nobject.\n\nAn optional hash reference of options may be given.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\ninsertmany\n$res = $coll->insertmany( [ @documents ] );\n$res = $coll->insertmany( [ @documents ], { ordered => 0 } );\n\nInserts each of the documents in an array reference into the database and returns a\nMongoDB::InsertManyResult or MongoDB::UnacknowledgedResult. This is syntactic sugar for doing a\nMongoDB::BulkWrite operation.\n\nIf no \"id\" field is present, one will be added when a document is serialized for the database\nwithout modifying the original document. The generated \"id\" may be retrieved from the result\nobject.\n\nAn optional hash reference of options may be provided.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"ordered\" – when true, the server will halt insertions after the first error (if any). When\nfalse, all documents will be processed and any error will only be thrown after all\ninsertions are attempted. The default is true.\n\nOn MongoDB servers before version 2.6, \"insertmany\" bulk operations are emulated with\nindividual inserts to capture error information. On 2.6 or later, this method will be\nsignificantly faster than individual \"insertone\" calls.\n\ndeleteone\n$res = $coll->deleteone( $filter );\n$res = $coll->deleteone( { id => $id } );\n$res = $coll->deleteone( $filter, { collation => { locale => \"enUS\" } } );\n\nDeletes a single document that matches a filter expression and returns a MongoDB::DeleteResult\nor MongoDB::UnacknowledgedResult object.\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\ndeletemany\n$res = $coll->deletemany( $filter );\n$res = $coll->deletemany( { name => \"Larry\" } );\n$res = $coll->deletemany( $filter, { collation => { locale => \"enUS\" } } );\n\nDeletes all documents that match a filter expression and returns a MongoDB::DeleteResult or\nMongoDB::UnacknowledgedResult object.\n\nValid options include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nreplaceone\n$res = $coll->replaceone( $filter, $replacement );\n$res = $coll->replaceone( $filter, $replacement, { upsert => 1 } );\n\nReplaces one document that matches a filter expression and returns a MongoDB::UpdateResult or\nMongoDB::UnacknowledgedResult object.\n\nThe replacement document must not have any field-update operators in it (e.g. $set).\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"upsert\" – defaults to false; if true, a new document will be added if one is not found\n\nupdateone\n$res = $coll->updateone( $filter, $update );\n$res = $coll->updateone( $filter, $update, { upsert => 1 } );\n\nUpdates one document that matches a filter expression and returns a MongoDB::UpdateResult or\nMongoDB::UnacknowledgedResult object.\n\nThe update document must have only field-update operators in it (e.g. $set).\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"arrayFilters\" - An array of filter documents that determines which array elements to modify\nfor an update operation on an array field. Only available for MongoDB servers of version\n3.6+.\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"upsert\" – defaults to false; if true, a new document will be added if one is not found by\ntaking the filter expression and applying the update document operations to it prior to\ninsertion.\n\nupdatemany\n$res = $coll->updatemany( $filter, $update );\n$res = $coll->updatemany( $filter, $update, { upsert => 1 } );\n\nUpdates one or more documents that match a filter expression and returns a MongoDB::UpdateResult\nor MongoDB::UnacknowledgedResult object.\n\nThe update document must have only field-update operators in it (e.g. $set).\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"arrayFilters\" - An array of filter documents that determines which array elements to modify\nfor an update operation on an array field. Only available for MongoDB servers of version\n3.6+.\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"upsert\" – defaults to false; if true, a new document will be added if one is not found by\ntaking the filter expression and applying the update document operations to it prior to\ninsertion.\n\nfind\n$cursor = $coll->find( $filter );\n$cursor = $coll->find( $filter, $options );\n\n$cursor = $coll->find({ i => { '$gt' => 42 } }, {limit => 20});\n\nExecutes a query with a filter expression and returns a lazy \"MongoDB::Cursor\" object. (The\nquery is not immediately issued to the server; see below for details.)\n\nThe query can be customized using MongoDB::Cursor methods, or with an optional hash reference of\noptions.\n\nValid options include:\n\n*   \"allowPartialResults\" - get partial results from a mongos if some shards are down (instead\nof throwing an error).\n\n*   \"batchSize\" – the number of documents to return per batch.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"comment\" – attaches a comment to the query.\n\n*   \"cursorType\" – indicates the type of cursor to use. It must be one of three string values:\n'nontailable' (the default), 'tailable', and 'tailableawait'.\n\n*   \"hint\" – specify an index to use\n<http://docs.mongodb.org/manual/reference/command/count/#specify-the-index-to-use>; must be\na string, array reference, hash reference or Tie::IxHash object.\n\n*   \"limit\" – the maximum number of documents to return.\n\n*   \"max\" – specify the exclusive upper bound for a specific index.\n\n*   \"maxAwaitTimeMS\" – the maximum amount of time for the server to wait on new documents to\nsatisfy a tailable cursor query. This only applies to a \"cursorType\" of 'tailableawait';\nthe option is otherwise ignored. (Note, this will be ignored for servers before version\n3.2.)\n\n*   \"maxScan\" – (DEPRECATED) maximum number of documents or index keys to scan.\n\n*   \"maxTimeMS\" – the maximum amount of time to allow the query to run. (Note, this will be\nignored for servers before version 2.6.)\n\n*   \"min\" – specify the inclusive lower bound for a specific index.\n\n*   \"modifiers\" – (DEPRECATED) a hash reference of dollar-prefixed query modifiers\n<http://docs.mongodb.org/manual/reference/operator/query-modifier/> modifying the output or\nbehavior of a query. Top-level options will always take precedence over corresponding\nmodifiers. Supported modifiers include $comment, $hint, $maxScan, $maxTimeMS, $max, $min,\n$orderby, $returnKey, $showDiskLoc, and $snapshot. Some options may not be supported by\nnewer server versions.\n\n*   \"noCursorTimeout\" – if true, prevents the server from timing out a cursor after a period of\ninactivity.\n\n*   \"projection\" - a hash reference defining fields to return. See \"limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>\" in the MongoDB\ndocumentation for details.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"returnKey\" – Only return the index field or fields for the results of the query\n<https://docs.mongodb.com/manual/reference/operator/meta/returnKey/>.\n\n*   \"showRecordId\" – modifies the output of a query by adding a field $recordId\n<https://docs.mongodb.com/manual/reference/method/cursor.showRecordId/> that uniquely\nidentifies a document in a collection.\n\n*   \"skip\" – the number of documents to skip before returning.\n\n*   \"sort\" – an ordered document defining the order in which to return matching documents. See\nthe $orderby documentation\n<https://docs.mongodb.com/manual/reference/operator/meta/orderby/> for examples.\n\nFor more information, see the Read Operations Overview\n<http://docs.mongodb.org/manual/core/read-operations-introduction/> in the MongoDB\ndocumentation.\n\nNote, a MongoDB::Cursor object holds the query and does not issue the query to the server until\nthe result method is called on it or until an iterator method like next is called. Performance\nwill be better directly on a MongoDB::QueryResult object:\n\nmy $queryresult = $coll->find( $filter )->result;\n\nwhile ( my $next = $queryresult->next ) {\n...\n}\n\nfindone\n$doc = $collection->findone( $filter, $projection );\n$doc = $collection->findone( $filter, $projection, $options );\n\nExecutes a query with a filter expression and returns a single document.\n\nIf a projection argument is provided, it must be a hash reference specifying fields to return.\nSee Limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/> in the MongoDB\ndocumentation for details.\n\nIf only a filter is provided or if the projection document is an empty hash reference, all\nfields will be returned.\n\nmy $doc = $collection->findone( $filter );\nmy $doc = $collection->findone( $filter, {}, $options );\n\nA hash reference of options may be provided as a third argument. Valid keys include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"sort\" – an ordered document defining the order in which to return matching documents. If\n$orderby also exists in the modifiers document, the sort field overwrites $orderby. See docs\nfor $orderby <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.\n\nSee also core documentation on querying: <http://docs.mongodb.org/manual/core/read/>.\n\nfindid\n$doc = $collection->findid( $id );\n$doc = $collection->findid( $id, $projection );\n$doc = $collection->findid( $id, $projection, $options );\n\nExecutes a query with a filter expression of \"{ id => $id }\" and returns a single document.\n\nSee the findone documentation for details on the $projection and $options parameters.\n\nSee also core documentation on querying: <http://docs.mongodb.org/manual/core/read/>.\n\nfindoneanddelete\n$doc = $coll->findoneanddelete( $filter );\n$doc = $coll->findoneanddelete( $filter, $options );\n\nGiven a filter expression, this deletes a document from the database and returns it as it\nappeared before it was deleted.\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"projection\" - a hash reference defining fields to return. See \"limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>\" in the MongoDB\ndocumentation for details.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"sort\" – an ordered document defining the order in which to return matching documents. See\ndocs for $orderby <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.\n\nfindoneandreplace\n$doc = $coll->findoneandreplace( $filter, $replacement );\n$doc = $coll->findoneandreplace( $filter, $replacement, $options );\n\nGiven a filter expression and a replacement document, this replaces a document from the database\nand returns it as it was either right before or right after the replacement. The default is\n'before'.\n\nThe replacement document must not have any field-update operators in it (e.g. $set).\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run.\n\n*   \"projection\" - a hash reference defining fields to return. See \"limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>\" in the MongoDB\ndocumentation for details.\n\n*   \"returnDocument\" – either the string 'before' or 'after', to indicate whether the returned\ndocument should be the one before or after replacement. The default is 'before'.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"sort\" – an ordered document defining the order in which to return matching documents. See\ndocs for $orderby <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.\n\n*   \"upsert\" – defaults to false; if true, a new document will be added if one is not found\n\nfindoneandupdate\n$doc = $coll->findoneandupdate( $filter, $update );\n$doc = $coll->findoneandupdate( $filter, $update, $options );\n\nGiven a filter expression and a document of update operators, this updates a single document and\nreturns it as it was either right before or right after the update. The default is 'before'.\n\nThe update document must contain only field-update operators (e.g. $set).\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"arrayFilters\" - An array of filter documents that determines which array elements to modify\nfor an update operation on an array field. Only available for MongoDB servers of version\n3.6+.\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"projection\" - a hash reference defining fields to return. See \"limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>\" in the MongoDB\ndocumentation for details.\n\n*   \"returnDocument\" – either the string 'before' or 'after', to indicate whether the returned\ndocument should be the one before or after replacement. The default is 'before'.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\n*   \"sort\" – an ordered document defining the order in which to return matching documents. See\ndocs for $orderby <http://docs.mongodb.org/manual/reference/operator/meta/orderby/>.\n\n*   \"upsert\" – defaults to false; if true, a new document will be added if one is not found\n\nwatch\nWatches for changes on this collection-\n\nPerform an aggregation with an implicit initial $changeStream stage and returns a\nMongoDB::ChangeStream result which can be used to iterate over the changes in the collection.\nThis functionality is available since MongoDB 3.6.\n\nmy $stream = $collection->watch();\nmy $stream = $collection->watch( \\@pipeline );\nmy $stream = $collection->watch( \\@pipeline, \\%options );\n\nwhile (1) {\n\n# This inner loop will only run until no more changes are\n# available.\nwhile (my $change = $stream->next) {\n# process $change\n}\n}\n\nThe returned stream will not block forever waiting for changes. If you want to respond to\nchanges over a longer time use \"maxAwaitTimeMS\" and regularly call \"next\" in a loop.\n\nNote: Using this helper method is preferred to manually aggregating with a $changeStream stage,\nsince it will automatically resume when the connection was terminated.\n\nThe optional first argument must be an array-ref of aggregation pipeline\n<http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents. Each pipeline document\nmust be a hash reference. Not all pipeline stages are supported after $changeStream.\n\nThe optional second argument is a hash reference with options:\n\n*   \"fullDocument\" - The fullDocument to pass as an option to the $changeStream stage. Allowed\nvalues: \"default\", \"updateLookup\". Defaults to \"default\". When set to \"updateLookup\", the\nchange notification for partial updates will include both a delta describing the changes to\nthe document, as well as a copy of the entire document that was changed from some time after\nthe change occurred.\n\n*   \"resumeAfter\" - The logical starting point for this change stream. This value can be\nobtained from the \"id\" field of a document returned by \"next\" in MongoDB::ChangeStream.\nCannot be specified together with \"startAtOperationTime\"\n\n*   \"maxAwaitTimeMS\" - The maximum number of milliseconds for the server to wait before\nresponding.\n\n*   \"startAtOperationTime\" - A BSON::Timestamp specifying at what point in time changes will\nstart being watched. Cannot be specified together with \"resumeAfter\". Plain values will be\ncoerced to BSON::Timestamp objects.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nSee \"aggregate\" for more available options.\n\nSee the manual section on Change Streams <https://docs.mongodb.com/manual/changeStreams/> for\ngeneral usage information on change streams.\n\nSee the Change Streams specification\n<https://github.com/mongodb/specifications/blob/master/source/change-streams.rst> for details on\nchange streams.\n\naggregate\n@pipeline = (\n{ '$group' => { id => '$state,' totalPop => { '$sum' => '$pop' } } },\n{ '$match' => { totalPop => { '$gte' => 10 * 1000 * 1000 } } }\n);\n\n$result = $collection->aggregate( \\@pipeline );\n$result = $collection->aggregate( \\@pipeline, $options );\n\nRuns a query using the MongoDB 2.2+ aggregation framework and returns a MongoDB::QueryResult\nobject.\n\nThe first argument must be an array-ref of aggregation pipeline\n<http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents. Each pipeline document\nmust be a hash reference.\n\nNote: Some pipeline documents have ordered arguments, such as $sort. Be sure to provide these\nargument using Tie::IxHash. E.g.:\n\n{ '$sort' => Tie::IxHash->new( age => -1, posts => 1 ) }\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"allowDiskUse\" – if, true enables writing to temporary files.\n\n*   \"batchSize\" – the number of documents to return per batch.\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled. (Note, this will be\nignored for servers before version 3.2.)\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"explain\" – if true, return a single document with execution information.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"hint\" - An index to use for this aggregation. (Only compatible with servers above version\n3.6.) For more information, see the other aggregate options here:\n<https://docs.mongodb.com/manual/reference/command/aggregate/index.html>\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nNote MongoDB 2.6+ added the '$out' pipeline operator. If this operator is used to write\naggregation results directly to a collection, an empty result will be returned. Create a new\ncollection> object to query the generated result collection. When $out is used, the command is\ntreated as a write operation and read preference is ignored.\n\nSee Aggregation <http://docs.mongodb.org/manual/aggregation/> in the MongoDB manual for more\ninformation on how to construct aggregation queries.\n\nNote The use of aggregation cursors is automatic based on your server version. However, if\nmigrating a sharded cluster from MongoDB 2.4 to 2.6 or later, you must upgrade your mongod\nservers first before your mongos routers or aggregation queries will fail. As a workaround, you\nmay pass \"cursor => undef\" as an option.\n\ncountdocuments\n$count = $coll->countdocuments( $filter );\n$count = $coll->countdocuments( $filter, $options );\n\nReturns a count of documents matching a filter expression. To return a count of all documents,\nuse an empty hash reference as the filter.\n\nNOTE: this may result in a scan of all documents in the collection. For a fast count of the\ntotal documents in a collection see \"estimateddocumentcount\" instead.\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"hint\" – specify an index to use; must be a string, array reference, hash reference or\nTie::IxHash object. (Requires server version 3.6 or later.)\n\n*   \"limit\" – the maximum number of documents to count.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"skip\" – the number of documents to skip before counting documents.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nNOTE: When upgrading from the deprecated \"count\" method, some legacy operators are not supported\nand must be replaced:\n\n+-------------+--------------------------------+\n| Legacy      | Modern Replacement             |\n+=============+================================+\n| $where      | $expr (Requires MongoDB 3.6+)  |\n+-------------+--------------------------------+\n| $near       | $geoWithin with $center        |\n+-------------+--------------------------------+\n| $nearSphere | $geoWithin with $centerSphere  |\n+-------------+--------------------------------+\n\nestimateddocumentcount\n$count = $coll->estimateddocumentcount();\n$count = $coll->estimateddocumentcount($options);\n\nReturns an estimated count of documents based on collection metadata.\n\nNOTE: this method does not support sessions or transactions.\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\ndistinct\n$result = $coll->distinct( $fieldname );\n$result = $coll->distinct( $fieldname, $filter );\n$result = $coll->distinct( $fieldname, $filter, $options );\n\nReturns a MongoDB::QueryResult object that will provide distinct values for a specified field\nname.\n\nThe query may be limited by an optional filter expression.\n\nA hash reference of options may be provided. Valid keys include:\n\n*   \"collation\" - a document defining the collation for this operation. See docs for the format\nof the collation document here: <https://docs.mongodb.com/master/reference/collation/>.\n\n*   \"maxTimeMS\" – the maximum amount of time in milliseconds to allow the command to run. (Note,\nthis will be ignored for servers before version 2.6.)\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nSee documentation for the distinct command\n<http://docs.mongodb.org/manual/reference/command/distinct/> for details.\n\nrename\n$newcollection = $collection->rename(\"mynewcollection\");\n\nRenames the collection. If a collection already exists with the new collection name, this method\nwill throw an exception.\n\nA hashref of options may be provided.\n\nValid options include:\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nIt returns a new MongoDB::Collection object corresponding to the renamed collection.\n\ndrop\n$collection->drop;\n\nDeletes a collection as well as all of its indexes.\n\norderedbulk\n$bulk = $coll->orderedbulk;\n$bulk->insertone( $doc1 );\n$bulk->insertone( $doc2 );\n...\n$result = $bulk->execute;\n\nReturns a MongoDB::BulkWrite object to group write operations into fewer network round-trips.\nThis method creates an ordered operation, where operations halt after the first error. See\nMongoDB::BulkWrite for more details.\n\nThe method \"initializeorderedbulkop\" may be used as an alias.\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\nunorderedbulk\nThis method works just like \"orderedbulk\" except that the order that operations are sent to the\ndatabase is not guaranteed and errors do not halt processing. See MongoDB::BulkWrite for more\ndetails.\n\nThe method \"initializeunorderedbulkop\" may be used as an alias.\n\nA hash reference of options may be provided.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\nbulkwrite\n$res = $coll->bulkwrite( [ @requests ], $options )\n\nThis method provides syntactic sugar to construct and execute a bulk operation directly, without\nusing \"initializeorderedbulk\" or \"initializeunorderedbulk\" to generate a MongoDB::BulkWrite\nobject and then calling methods on it. It returns a MongoDB::BulkWriteResponse object just like\nthe MongoDB::BulkWrite execute method.\n\nThe first argument must be an array reference of requests. Requests consist of pairs of a\nMongoDB::Collection write method name (e.g. \"insertone\", \"deletemany\") and an array reference\nof arguments to the corresponding method name. They may be given as pairs, or as hash or array\nreferences:\n\n# pairs -- most efficient\n@requests = (\ninsertone  => [ { x => 1 } ],\nreplaceone => [ { x => 1 }, { x => 4 } ],\ndeleteone  => [ { x => 4 } ],\nupdatemany => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ],\n);\n\n# hash references\n@requests = (\n{ insertone  => [ { x => 1 } ] },\n{ replaceone => [ { x => 1 }, { x => 4 } ] },\n{ deleteone  => [ { x => 4 } ] },\n{ updatemany => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ] },\n);\n\n# array references\n@requests = (\n[ insertone  => [ { x => 1 } ] ],\n[ replaceone => [ { x => 1 }, { x => 4 } ] ],\n[ deleteone  => [ { x => 4 } ] ],\n[ updatemany => [ { x => { '$gt' => 5 } }, { '$inc' => { x => 1 } } ] ],\n);\n\nValid method names include \"insertone\", \"insertmany\", \"deleteone\", \"deletemany\"\n\"replaceone\", \"updateone\", \"updatemany\".\n\nAn optional hash reference of options may be provided.\n\nValid options include:\n\n*   \"bypassDocumentValidation\" - skips document validation, if enabled; this is ignored for\nMongoDB servers older than version 3.2.\n\n*   \"ordered\" – when true, the bulk operation is executed like \"initializeorderedbulk\". When\nfalse, the bulk operation is executed like \"initializeunorderedbulk\". The default is true.\n\n*   \"session\" - the session to use for these operations. If not supplied, will use an implicit\nsession. For more information see MongoDB::ClientSession\n\nSee MongoDB::BulkWrite for more details on bulk writes. Be advised that the legacy Bulk API\nmethod names differ slightly from MongoDB::Collection method names.\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "*   David Golden <david@mongodb.com>\n\n*   Rassi <rassi@mongodb.com>\n\n*   Mike Friedman <friedo@friedo.com>\n\n*   Kristina Chodorow <k.chodorow@gmail.com>\n\n*   Florian Ragwitz <rafl@debian.org>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "This software is Copyright (c) 2020 by MongoDB, Inc.\n\nThis is free software, licensed under:\n\nThe Apache License, Version 2.0, January 2004\n",
            "subsections": []
        }
    },
    "summary": "MongoDB::Collection - A MongoDB Collection",
    "flags": [],
    "examples": [],
    "see_also": []
}