=encoding utf8

=head1 NAME

Apache::Solr::Result - Apache Solr (Lucene) result container

=head1 SYNOPSIS

  # All operations return a ::Result object
  my $result = $solr->select(...);

  $result->success or die $result->solrError; # error reported by Solr
  $result->success or die $result->errors;    # any error caught by this object
  if($result)  # same as if($result->success)

  # Lots of trace information included
  $result->showTimings;

  # ::Document containing the requested fields from a select() search
  my $doc1   = $result->selected(0);

  # ::Document containing the highlight info from a selected document
  my $hl1    = $result->highlighted($doc1);

  # Some operations have helper methods
  my $result = $solr->queryTerm(...);
  print Dumper $result->terms;

=head1 DESCRIPTION

=head1 OVERLOADED

=over 4

=item overload: B<stringification> 

Z<>

=back

=head1 METHODS

=head2 Constructors

=over 4

=item $class-E<gt>B<new>(%options)

Z<>

 -Option    --Default
  core        undef
  endpoint    <required>
  params      []
  request     undef
  response    undef
  sequential  false

=over 2

=item core => Apache::Solr object

=item endpoint => URI

=item params => \%params|\@pairs

The parameters used for the query.  [1.11] not a required option anymore.

=item request => HTTP::Request object

=item response => HTTP::Response object

=item sequential => BOOLEAN

[1.06] By setting this, you indicate that you will process the documents
in (numeric) sequential order; that you have no intention to go back to
a lower number.  This implies that those cached results can be cleaned-up
in the client early, reducing memory consumption.

However: you are allowed to go back to lower numbers, with the penalty
of a repeat of a message exchange between this client and the database.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<core>()

[0.95] May return the L<Apache::Solr|Apache::Solr> object which created this result.

=item $obj-E<gt>B<decoded>( [HASH] )

Set/get the decoded content of the Solr server response.  In some cases,
even error responses contain a valid Solr server data.

=item $obj-E<gt>B<elapse>()

Number of seconds used to receive a decoded answer.

=item $obj-E<gt>B<endpoint>()

The URI where the request is sent to.

=item $obj-E<gt>B<errors>()

All errors collected by this object into one string.

=item $obj-E<gt>B<httpError>()

Z<>

=item $obj-E<gt>B<params>()

List of (expanded) parameters used to call the solr server.

=item $obj-E<gt>B<request>( [$request] )

Set/get the HTTP::Request object used in this query.

=item $obj-E<gt>B<response>( [$response] )

Set/get the HTTP::Response object received from this query action.

=item $obj-E<gt>B<sequential>()

[1.06] Shows whether the results are only read in numeric order.

=item $obj-E<gt>B<serverError>()

Z<>

=item $obj-E<gt>B<solrError>()

Z<>

=item $obj-E<gt>B<solrQTime>()

Elapse (as reported by the server) to handle the request.  In seconds!

=item $obj-E<gt>B<solrStatus>()

Z<>

=item $obj-E<gt>B<start>()

The timestamp of the moment the call has started, including the creation of
the message to be sent.

=item $obj-E<gt>B<success>()

Returns C<true> if the command has successfully completed.

» example: 

  my $result = $sorl->commit;
  $result->success or die;
  $result or die;          # same, via overloading
  $solr->commit or die;    # same, also overloading

=back

=head2 Response information

=head3 in response to a select()

=over 4

=item $obj-E<gt>B<highlighted>($document)

Return information which relates to the selected C<$document>.

=item $obj-E<gt>B<nextSelected>(%options)

[0.95] Produces the next document, or C<undef> when there are none left.
[1.06] Use L<selected()|Apache::Solr::Result/"in response to a select()"> or search parameter C<start> to give a starting
point.  [1.06] The C<%options> are passed to L<selected()|Apache::Solr::Result/"in response to a select()">.

» example: 

  my $result = $solr->select(q => ...);
  while(my $doc = $result->nextSelected)
  {   my $hl = $result->highlighted($doc);
  }

=item $obj-E<gt>B<nrSelected>()

Returns the number of selected documents, as result of a
L<Apache::Solr::select()|Apache::Solr/"Search"> call.  Probably many of those documents are
not loaded (yet).

» example: 

  print $result->nrSelected, " results\n";

  for(my $docnr = 0; $docnr < $result->nrSelected; $docnr++)
  {   my $doc = $result->selected($docnr);
      ...
  }
  # easier:
  while(my $doc = $result->nextSelected) ...

=item $obj-E<gt>B<selected>($rank, %options)

Returns information about the query by L<Apache::Solr::select()|Apache::Solr/"Search"> on
position C<$rank> (count starts at 0!)  Returned is an L<Apache::Solr::Document|Apache::Solr::Document>
object.

The first request will take a certain number of "rows".  This routine
will automatically collect more of the selected answers, when you address
results outside the first "page" of "rows".  The results of these other
requests are cached as well.

This method has no C<%options> at the moment.

» example: 

  my $r = $solr->select(rows => 10, ...);
  $r or die $r->errors;

  if(my $last = $r->selected(9)) {...}
  my $doc = $r->selected(11);     # auto-request more

=back

=head3 in response to a queryTerms()

=over 4

=item $obj-E<gt>B<terms>( $field, [$terms] )

Returns the results of a 'terms' query (see L<Apache::Solr::queryTerms()|Apache::Solr/"Search">),
which is a HASH.  When C<$terms> are specified, a new table is set.

In Solr XML (at least upto v4.0) the results are presented as lst, not arr
So: their sort order is lost.

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<fullPageSize>()

[1.07] Returns the page size of all of the full returned pages.  The last page
is probably smaller.

=item $obj-E<gt>B<replaceParams>(\%params, \%oldparams)

Z<>

=item $obj-E<gt>B<selectedPage>($pagenr)

The L<selected()|Apache::Solr::Result/"in response to a select()"> documents are retreived in pages, each of size
L<fullPageSize()|Apache::Solr::Result/"Helpers"> (although the last page may be shorter).  Each
page is separately downloaded when used.  Each page is also a
full C<Apache::Solr::Result> object with request, response, and timing
information.

=item $obj-E<gt>B<selectedPageLoad>($rank, $client)

Query the database for the next page of results.

=item $obj-E<gt>B<selectedPageNr>($rank)

Z<>

=item $obj-E<gt>B<selectedPageSize>()

[1.07] DEPRECATED.  Use L<fullPageSize()|Apache::Solr::Result/"Helpers">.

=item $obj-E<gt>B<selectedPages>()

Z<>

=item $obj-E<gt>B<showTimings>( [$fh] )

Print timing informat to the C<$fh>, by default the selected file-handle (probably STDOUT).

=back

=head1 DIAGNOSTICS

=over 4

=item Error: cannot autoload page $nr, no client provided.

Cast by C<selectedPageLoad()>

=item Error: no search for terms on field $field requested.

Cast by C<terms()>

=item Error: there is no highlighting information in the result.

Cast by C<highlighted()>

=back

=head1 SEE ALSO

This module is part of Apache-Solr version 1.12,
built on July 15, 2026. Website: F<https://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2012-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

