view release on metacpan or  search on metacpan

lib/Apache/Solr.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

Apache::Solr - Apache Solr (Lucene) extension

=head1 INHERITANCE

 Apache::Solr is extended by
   Apache::Solr::JSON
   Apache::Solr::XML

=head1 SYNOPSIS

  # use Log::Report mode => "DEBUG";
  my $solr    = Apache::Solr->new(server => $url);
  my $lwp     = $solr->agent;   # internal LWP::UserAgent

  my $doc     = Apache::Solr::Document->new(...);
  my $results = $solr->addDocument($doc);
  $results or die $results->errors;

  my $results = $solr->select(q => 'author:mark');
  my $doc     = $results->selected(3);
  print $doc->_author;

  my $results = $solr->select(q => "really", hl => {fl=>'content'});
  while(my $doc = $results->nextSelected)
  {    my $hldoc = $results->highlighted($doc);
      print $hldoc->_content;
      ...
  }

  # based on Log::Report, hence (for communication errors and such)
  use Log::Report;
  dispatcher SYSLOG => 'default';  # now all warnings/error to syslog
  try { $solr->select(...) }; print $@->wasFatal;

  # [1.11] Information about communication errors 
  my $result = try { $solr->select(...) };
  if(my $ex = $@->wasFatal)
  {  $result = $ex->message->valueOf('result');
     if(defined $result)   #!! defined !!
     {    warn Dumper $result->decoded;

=head1 DESCRIPTION

Solr is a stand-alone full-text search-engine (based on Lucent), with
loads of features.  This module tries to provide a high level interface
to the Solr server.

See F<F<http://wiki.apache.org/solr/> and F<http://lucene.apache.org/solr/>

=head1 METHODS

=head2 Constructors

=over 4

=item Apache::Solr-E<gt>B<new>(%options)

Create a client to connect to one "core" (collection) of the Solr
server.

 -Option        --Default
  agent           <created internally>
  autocommit      true
  core            undef
  format          'XML'
  retry_max       60
  retry_wait      5
  server          <required>
  server_version  <latest>

=over 2

=item agent => LWP::UserAgent object

Agent which implements the communication between this client and the
Solr server.

When you have multiple C<Apache::Solr> objects in your program, you may
want to share this agent, to share the connection. Since [0.94], this
will happen automagically: the parameter defaults to the agent created
for the previous object.

Do not forget to install LWP::Protocol::https if you need to connect
via https.

=item autocommit => BOOLEAN

Commit all changes immediately unless specified differently.

=item core => NAME

Set the core name to be addressed by this client. When there is no core
name specified, the core is selected by the server or already part of
the URL.

You probably want to set-up a core dedicated for testing and one for
the live environment.

=item format => 'XML'|'JSON'

lib/Apache/Solr.pod  view on Meta::CPAN

=item waitSearcher => BOOLEAN

=back

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

[solr 1.4]

=back

=head3 Core management

See F<https://solr.apache.org/guide/6_6/coreadmin-api.html>
The CREATE, SWAP, ALIAS, and RENAME actions are not yet supported, because
they are not very useful, it seems.

=over 4

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

[0.94] Load a new core (on the server) from the configuration of this
core. While the new core is initializing, the existing one will continue
to handle requests. When the new Solr core is ready, it takes over and
the old core is unloaded.

 -Option--Default
  core    <this core>

=over 2

=item core => NAME

=back

example: 

  my $result = $solr->coreReload;
  $result or die $result->errors;

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

[0.94] Returns a HASH with information about this core.  There is no
description about the exact structure and interpretation of this data.

 -Option--Default
  core    <this core>

=over 2

=item core => NAME

=back

example: 

  my $result = $solr->coreStatus;
  $result or die $result->errors;

  use Data::Dumper;
  print Dumper $result->decoded->{status};

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

Removes a core from Solr. Active requests will continue to be processed, but no new requests will be sent to the named core. If a core is registered under more than one name, only the given name is removed.

 -Option--Default
  core    <this core>

=over 2

=item core => NAME

=back

=back

=head2 Helpers

=head3 Parameter pre-processing

Many parameters are passed to the server.  The syntax of the communication
protocol is not optimal for the end-user: it is too verbose and depends on
the Solr server version.

General rules:

=over 4

=item * you can group them on prefix

=item * use underscore as alternative to dots: less quoting needed

=item * boolean values in Perl will get translated into 'true' and 'false'

=item * when an ARRAY (or LIST), the order of the parameters get preserved

=back

=over 4

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

Produce a warning $message about deprecated parameters with the
indicated server version.

=item $obj-E<gt>B<expandExtract>(PAIRS|ARRAY)

Used by L<extractDocument()|Apache::Solr/"Updates">.

[0.93] If the key is C<literal> or C<literals>, then the keys in the
value HASH (or ARRAY of PAIRS) get 'literal.' prepended.  "Literals"
are fields you add yourself to the SolrCEL output.  Unless C<extractOnly>,
you need to specify the 'id' literal.

[0.94] You can also use C<fmap>, C<boost>, and C<resource> with an
HASH (or ARRAY-of-PAIRS).  [0.97] the value in each PAIR may be a SCALAR
(ref string) which circumvents some copying.

example: