{
    "content": [
        {
            "type": "text",
            "text": "# MongoDB::Cursor (perldoc)\n\n## NAME\n\nMongoDB::Cursor - A lazy cursor for Mongo query results\n\n## SYNOPSIS\n\nwhile (my $object = $cursor->next) {\n...\n}\nmy @objects = $cursor->all;\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **USAGE** (1 subsections)\n- **ATTRIBUTES**\n- **QUERY MODIFIERS**\n- **QUERY INTROSPECTION AND RESET**\n- **QUERY ITERATION**\n- **SEE ALSO**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "MongoDB::Cursor",
        "section": "",
        "mode": "perldoc",
        "summary": "MongoDB::Cursor - A lazy cursor for Mongo query results",
        "synopsis": "while (my $object = $cursor->next) {\n...\n}\nmy @objects = $cursor->all;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "USAGE",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Multithreading",
                        "lines": 6
                    }
                ]
            },
            {
                "name": "ATTRIBUTES",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "QUERY MODIFIERS",
                "lines": 141,
                "subsections": []
            },
            {
                "name": "QUERY INTROSPECTION AND RESET",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "QUERY ITERATION",
                "lines": 77,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 10,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "MongoDB::Cursor - A lazy cursor for Mongo query results\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version v2.2.2\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "while (my $object = $cursor->next) {\n...\n}\n\nmy @objects = $cursor->all;\n",
                "subsections": []
            },
            "USAGE": {
                "content": "",
                "subsections": [
                    {
                        "name": "Multithreading",
                        "content": "NOTE: Per threads documentation, use of Perl threads is discouraged by the maintainers of Perl\nand the MongoDB Perl driver does not test or provide support for use with threads.\n\nCursors are cloned in threads, but not reset. Iterating the same cursor from multiple threads\nwill give unpredictable results. Only iterate from a single thread.\n"
                    }
                ]
            },
            "ATTRIBUTES": {
                "content": "startediterating\nA boolean indicating if this cursor has queried the database yet. Methods modifying the query\nwill complain if they are called after the database is queried.\n",
                "subsections": []
            },
            "QUERY MODIFIERS": {
                "content": "These methods modify the query to be run. An exception will be thrown if they are called after\nresults are iterated.\n\nimmortal\n$cursor->immortal(1);\n\nOrdinarily, a cursor \"dies\" on the database server after a certain length of time (approximately\n10 minutes), to prevent inactive cursors from hogging resources. This option indicates that a\ncursor should not die until all of its results have been fetched or it goes out of scope in\nPerl.\n\nBoolean value, defaults to 0.\n\nNote: \"immortal\" only affects the server-side timeout. If you are getting client-side timeouts\nyou will need to change your client configuration. See \"maxtimems\" in MongoDB::MongoClient and\n\"sockettimeoutms\" in MongoDB::MongoClient.\n\nReturns this cursor for chaining operations.\n\nfields\n$coll->insert({name => \"Fred\", age => 20});\nmy $cursor = $coll->find->fields({ name => 1 });\nmy $obj = $cursor->next;\n$obj->{name}; \"Fred\"\n$obj->{age}; # undef\n\nSelects which fields are returned. The default is all fields. When fields are specified, id is\nreturned by default, but this can be disabled by explicitly setting it to \"0\". E.g. \"id => 0\".\nArgument must be either a hash reference or a Tie::IxHash object.\n\nSee Limit fields to return\n<http://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/> in the MongoDB\ndocumentation for details.\n\nReturns this cursor for chaining operations.\n\nsort\n# sort by name, descending\n$cursor->sort([name => -1]);\n\nAdds a sort to the query. Argument is either a hash reference or a Tie::IxHash or an array\nreference of key/value pairs. Because hash references are not ordered, do not use them for more\nthan one key.\n\nReturns this cursor for chaining operations.\n\nlimit\n$cursor->limit(20);\n\nSets cursor to return a maximum of N results.\n\nReturns this cursor for chaining operations.\n\nmaxawaittimems\n$cursor->maxawaittimems( 500 );\n\nThe maximum amount of time in milliseconds for the server to wait on new documents to satisfy a\ntailable cursor query. This only applies to a cursor of type 'tailbleawait'. This is ignored if\nthe cursor is not a 'tailableawait' cursor or the server version is less than version 3.2.\n\nReturns this cursor for chaining operations.\n\nmaxtimems\n$cursor->maxtimems( 500 );\n\nCauses the server to abort the operation if the specified time in milliseconds is exceeded.\n\nReturns this cursor for chaining operations.\n\ntailable\n$cursor->tailable(1);\n\nIf a cursor should be tailable. Tailable cursors can only be used on capped collections and are\nsimilar to the \"tail -f\" command: they never die and keep returning new results as more is added\nto a collection.\n\nThey are often used for getting log messages.\n\nBoolean value, defaults to 0.\n\nIf you want the tailable cursor to block for a few seconds, use \"tailableawait\" instead. Note\ncalling this with a false value disables tailing, even if \"tailableawait\" was previously\ncalled.\n\nReturns this cursor for chaining operations.\n\ntailableawait\n$cursor->tailableawait(1);\n\nSets a cursor to be tailable and block for a few seconds if no data is immediately available.\n\nBoolean value, defaults to 0.\n\nIf you want the tailable cursor without blocking, use \"tailable\" instead. Note calling this with\na false value disables tailing, even if \"tailable\" was previously called.\n\nskip\n$cursor->skip( 50 );\n\nSkips the first N results.\n\nReturns this cursor for chaining operations.\n\nhint\nHint the query to use a specific index by name:\n\n$cursor->hint(\"indexname\");\n\nHint the query to use index based on individual keys and direction:\n\n$cursor->hint([field1 => 1, field2 => -1, field3 => 1]);\n\nUse of a hash reference should be avoided except for single key indexes.\n\nThe hint must be a string or ordered document.\n\nReturns this cursor for chaining operations.\n\npartial\n$cursor->partial(1);\n\nIf a shard is down, mongos will return an error when it tries to query that shard. If this is\nset, mongos will just skip that shard, instead.\n\nBoolean value, defaults to 0.\n\nReturns this cursor for chaining operations.\n\nreadpreference\n$cursor->readpreference($readpreferenceobject);\n$cursor->readpreference('secondary', [{foo => 'bar'}]);\n\nSets read preference for the cursor's connection.\n\nIf given a single argument that is a MongoDB::ReadPreference object, the read preference is set\nto that object. Otherwise, it takes positional arguments: the read preference mode and a tag set\nlist, which must be a valid mode and tag set list as described in the MongoDB::ReadPreference\ndocumentation.\n\nReturns this cursor for chaining operations.\n",
                "subsections": []
            },
            "QUERY INTROSPECTION AND RESET": {
                "content": "These methods run introspection methods on the query conditions and modifiers stored within the\ncursor object.\n\nexplain\nmy $explanation = $cursor->explain;\n\nThis will tell you the type of cursor used, the number of records the DB had to examine as part\nof this query, the number of records returned by the query, and the time in milliseconds the\nquery took to execute.\n\nSee also core documentation on explain: <http://dochub.mongodb.org/core/explain>.\n",
                "subsections": []
            },
            "QUERY ITERATION": {
                "content": "These methods allow you to iterate over results.\n\nresult\nmy $result = $cursor->result;\n\nThis method will execute the query and return a MongoDB::QueryResult object with the results.\n\nThe \"hasnext\", \"next\", and \"all\" methods call \"result\" internally, which executes the query \"on\ndemand\".\n\nIterating with a MongoDB::QueryResult object directly instead of a MongoDB::Cursor will be\nslightly faster, since the MongoDB::Cursor methods below just internally call the corresponding\nmethod on the result object.\n\nhasnext\nwhile ($cursor->hasnext) {\n...\n}\n\nChecks if there is another result to fetch. Will automatically fetch more data from the server\nif necessary.\n\nnext\nwhile (my $object = $cursor->next) {\n...\n}\n\nReturns the next object in the cursor. Will automatically fetch more data from the server if\nnecessary. Returns undef if no more data is available.\n\nbatch\nwhile (my @batch = $cursor->batch) {\n...\n}\n\nReturns the next batch of data from the cursor. Will automatically fetch more data from the\nserver if necessary. Returns an empty list if no more data is available.\n\nall\nmy @objects = $cursor->all;\n\nReturns a list of all objects in the result.\n\nreset\nResets the cursor. After being reset, pre-query methods can be called on the cursor (sort,\nlimit, etc.) and subsequent calls to result, next, hasnext, or all will re-query the database.\n\ninfo\nReturns a hash of information about this cursor. This is intended for debugging purposes and\nusers should not rely on the contents of this method for production use. Currently the fields\nare:\n\n*   \"cursorid\" -- the server-side id for this cursor. See below for details.\n\n*   \"num\" -- the number of results received from the server so far\n\n*   \"at\" -- the (zero-based) index of the document that will be returned next from \"next\"\n\n*   \"flag\" -- if the database could not find the cursor or another error occurred, \"flag\" may\ncontain a hash reference of flags set in the response (depending on the error). See\n<http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPREPLY> for a\nfull list of flag values.\n\n*   \"start\" -- the index of the result that the current batch of results starts at.\n\nIf the cursor has not yet executed, only the \"num\" field will be returned with a value of 0.\n\nThe \"cursorid\" could appear in one of three forms:\n\n*   MongoDB::CursorID object (a blessed reference to an 8-byte string)\n\n*   A perl scalar (an integer)\n\n*   A Math::BigInt object (64 bit integer on 32-bit perl)\n\nWhen the \"cursorid\" is zero, there are no more results to fetch.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Core documentation on cursors: <http://dochub.mongodb.org/core/cursors>.\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": []
            }
        }
    }
}