.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::QueryResult 3pm"
.TH MongoDB::QueryResult 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::QueryResult \- An iterator for Mongo query results
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    $cursor = $coll\->find( $filter );
\&    $result = $cursor\->result;
\&
\&    while ( $doc = $result\->next ) {
\&        process_doc($doc)
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class defines an iterator against a query result.  It automatically
fetches additional results from the originating mongod/mongos server
on demand.
.PP
For backwards compatibility reasons, MongoDB::Cursor encapsulates query
parameters and generates a \f(CW\*(C`MongoDB::QueryResult\*(C'\fR object on demand.  All
iterators on \f(CW\*(C`MongoDB::Cursor\*(C'\fR delegate to \f(CW\*(C`MongoDB::QueryResult\*(C'\fR object.
.PP
Retrieving this object and iterating on it directly will be slightly
more efficient.
.SH "USAGE"
.IX Header "USAGE"
.SS "Error handling"
.IX Subsection "Error handling"
Unless otherwise explicitly documented, all methods throw exceptions if
an error occurs.  The error types are documented in MongoDB::Error.
.PP
To catch and handle errors, the Try::Tiny and Safe::Isa modules
are recommended:
.SS "Cursor destruction"
.IX Subsection "Cursor destruction"
When a \f(CW\*(C`MongoDB::QueryResult\*(C'\fR object is destroyed, a cursor termination
request will be sent to the originating server to free server resources.
.SS "Multithreading"
.IX Subsection "Multithreading"
\&\fB\s-1NOTE\s0\fR: Per threads documentation, use of Perl threads is discouraged by the
maintainers of Perl and the MongoDB Perl driver does not test or provide support
for use with threads.
.PP
Iterators are cloned in threads, but not reset.  Iterating from multiple
threads will give unpredictable results.  Only iterate from a single
thread.
.SH "METHODS"
.IX Header "METHODS"
.SS "has_next"
.IX Subsection "has_next"
.Vb 3
\&    if ( $response\->has_next ) {
\&        ...
\&    }
.Ve
.PP
Returns true if additional documents are available.  This will
attempt to get another batch of documents from the server if
necessary.
.SS "next"
.IX Subsection "next"
.Vb 3
\&    while ( $doc = $result\->next ) {
\&        process_doc($doc)
\&    }
.Ve
.PP
Returns the next document or \f(CW\*(C`undef\*(C'\fR if the server cursor is exhausted.
.SS "batch"
.IX Subsection "batch"
.Vb 5
\&  while ( @batch = $result\->batch ) {
\&    for $doc ( @batch ) {
\&      process_doc($doc);
\&    }
\&  }
.Ve
.PP
Returns the next batch of documents or an empty list if the server cursor is exhausted.
.SS "all"
.IX Subsection "all"
.Vb 1
\&    @docs = $result\->all;
.Ve
.PP
Returns all documents as a list.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve