=head1 NAME

Apache::Solr::Document - Apache Solr (Lucene) Document container

=head1 SYNOPSIS

  # create and upload a new document
  my $doc = Apache::Solr::Document->new(...);
  $solr->addDocument($doc, commit => 1, overwrite => 1)

  # take first result
  my $results = $solr->select
    ( q  => 'text:gold'             # search text-fields for 'gold'
    , hl => { field => 'content' }  # highlight 'gold' in content'
    );

  my $doc = $results->selected(3);  # fourth answer
  print $doc->rank;         # 3
  print $doc->field('subject')->{content};
  print $doc->content('subject');   # same
  print $doc->_subject;             # same, via autoload (mind the '_'!)

  my $hl  = $results->highlighted($doc);  # another ::Doc object
  print $hl->_content;              # highlighted content

=head1 DESCRIPTION

This object wraps-up an document: a set of fields.
Either, this is a document which has to be added to the Solr database
using L<Apache::Solr::addDocument()|Apache::Solr/"Updates">,
or the subset of information as returned by L<Apache::Solr::select()|Apache::Solr/"Search">.

=head1 METHODS

=head2 Constructors

=over 4

=item Apache::Solr::Document-E<gt>B<fromResult>(HASH, RANK)

Create a document object from data received as result of a select
search.

=item Apache::Solr::Document-E<gt>B<new>(OPTIONS)

 -Option--Default
  boost   1.0
  fields  {}

=over 2

=item boost => FLOAT

Boost the preference for hits in this document.

=item fields => HASH|ARRAY

Passed to L<addFields()|Apache::Solr::Document/"Accessors">.

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<addField>(NAME, CONTENT, OPTIONS)

CONTENT can be specified as SCALAR (reference) for performance. In
that case, a reference to the original will be kept.  When C<undef>,
the field gets ignored.

 -Option--Default
  boost   1.0

=over 2

=item boost => FLOAT

=back

=item $obj-E<gt>B<addFields>(HASH|ARRAY, OPTIONS)

The HASH or ARRAY containing NAME/CONTENT pairs.
The OPTIONS are passed L<addField()|Apache::Solr::Document/"Accessors"> as OPTIONS.

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

Boost value for all fields in the document.

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

Returns the content of the first field with NAME.

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

Returns the first field with NAME (or undef).  This is a HASH.

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

All used unique names.

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

Returns a list of HASHs, each containing at least a C<name> and a
C<content>.  Each HASH will also contain a C<boost> value.  When a NAME
is provided, only those fields are returned.

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

Only defined when the document contains results of a search: the ranking.
A value of '0' means "best".

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

Returns the value of the unique key associated with the document C<id>.  Only
the server knowns which field is the unique one.  If it differs from the
usual C<id>, you have to set it via global value C<$Apache::Solr::uniqueKey>

=back

=head2 Helpers

=head1 SEE ALSO

This module is part of Apache-Solr distribution version 0.92,
built on December 06, 2012. Website: F<http://perl.overmeer.net>

=head1 LICENSE

Copyrights 2012 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>