Constructors

Apache::Solr->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>
    

Accessors

$obj->agent()

Returns the LWP::UserAgent object which maintains the connection to the server.

$obj->autocommit( [BOOLEAN] )

$obj->core( [$core] )

Returns the $core, when not defined the default core as set by new(core). May return "undef".

$obj->server( [$uri|STRING] )

Returns the URI object which refers to the server base address. You need to clone() it before modifying. You may set a new value as STRING or $uri object.

$obj->serverVersion()

Returns the specified version of the Solr server software (by default the latest). Treat this version as string, to avoid rounding errors.

Commands

Search

$obj->queryTerms($terms)

Search for often used terms. See http://wiki.apache.org/solr/TermsComponent

$terms are passed to expandTerms() before being used.

Be warned: The result is not sorted when XML communication is used, even when you explicitly request it.

example:

  my $r = $self->queryTerms(fl => 'subject', limit => 100);
  if($r->success)
  {    foreach my $hit ($r->terms('subject'))
      {    my ($term, $count) = @$hit;
          print "term=$term, count=$count\n";
      }
  }
  if(my $r = $self->queryTerms(fl => 'subject', limit => 100))
     ...
    

$obj->select( [\%options], @parameters )

Find information in the document collection.

This method has a HUGE number of parameters. These values are passed in the uri of the http query to the solr server. See expandSelect() for all the simplifications offered here. Sets of there parameters may need configuration help in the server as well.

[1.06] You may pass some options to process the selected results (the Apache::Solr::Result object initiation). For instance, "sequential". For backwards compatability reasons, they have to be passed in a HASH as optional first parameter.

Updates

See http://wiki.apache.org/solr/UpdateXmlMessages. Missing are the atomic updates.

$obj->addDocument( <$doc|ARRAY>, %options )

Add one or more documents (Apache::Solr::Document objects) to the Solr database on the server.

 -Option            --Default
  allowDups           <false>
  commit              <autocommit>
  commitWithin        undef
  overwrite           <true>
  overwriteCommitted  <not allowDups>
  overwritePending    <not allowDups>
    

$obj->commit(%options)

 -Option        --Default
  expungeDeletes  <false>
  softCommit      <false>
  waitFlush       <true>
  waitSearcher    <true>
    

$obj->delete(%options)

Remove one or more documents, based on id or query.

 -Option       --Default
  commit         <autocommit>
  fromCommitted  true
  fromPending    true
  id             undef
  query          undef
    

$obj->extractDocument(%options)

Call the Solr Tika built-in to have the server translate various kinds of structured documents into Solr searchable documents. This component is also called "Solr Cell".

The %options are mostly passed on as attributes to the server call, but there are a few more. You need to pass either a "file" or "string" with data.

See http://wiki.apache.org/solr/ExtractingRequestHandler

 -Option      --Default
  commit        new(autocommit)
  content_type  <from> filename
  file          undef
  string        undef
    

   my $r = $solr->extractDocument(file => 'design.pdf',
       literal_id => 'host');

$obj->optimize(%options)

 -Option      --Default
  maxSegments   1
  softCommit    <false>
  waitFlush     <true>
  waitSearcher  <true>
    

$obj->rollback()

[solr 1.4]

Core management

See 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.

$obj->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>
    

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

$obj->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>
    

  my $result = $solr->coreStatus;
  $result or die $result->errors;
  use Data::Dumper;
  print Dumper $result->decoded->{status};

$obj->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>
    

Helpers

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:

• you can group them on prefix
• use underscore as alternative to dots: less quoting needed
• boolean values in Perl will get translated into 'true' and 'false'
• when an ARRAY (or LIST), the order of the parameters get preserved

$obj->deprecated($message)

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

$obj->expandExtract(PAIRS|ARRAY)

Used by extractDocument().

[0.93] If the key is "literal" or "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 "extractOnly", you need to specify the 'id' literal.

[0.94] You can also use "fmap", "boost", and "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:

  my $result = $solr->extractDocument(string => $document,
      resource_name => $fn, extractOnly => 1,
      literals => { id => 5, b => 'tic' }, literal_xyz => 42,
      fmap => { id => 'doc_id' }, fmap_subject => 'mysubject',
      boost => { abc => 3.5 }, boost_xyz => 2.0
  );
    

$obj->expandSelect(PAIRS)

The select() method accepts many, many parameters. These are passed to modules in the server, which need configuration before being usable.

Besides the common parameters, like 'q' (query) and 'rows', there are parameters for various (pluggable) backends, usually prefixed by the backend abbreviation.

  my @r = $solr->expandSelect(
      q => 'inStock:true', rows => 10,
      facet => {limit => -1, field => [qw/cat inStock/], mincount => 1},
      f_cat_facet => {missing => 1},
      hl    => {},
      mlt   => { fl => 'manu,cat', mindf => 1, mintf => 1 },
      stats => { field => [ 'price', 'popularity' ] },
      group => { query => 'price:[0 TO 99.99]', limit => 3 },
  );
  # becomes (one line)
  ...?rows=10&q=inStock:true
    &facet=true&facet.limit=-1&facet.field=cat
       &f.cat.facet.missing=true&facet.mincount=1&facet.field=inStock
    &mlt=true&mlt.fl=manu,cat&mlt.mindf=1&mlt.mintf=1
    &stats=true&stats.field=price&stats.field=popularity
    &group=true&group.query=price:[0+TO+99.99]&group.limit=3

$obj->expandTerms(PAIRS|ARRAY)

Used by queryTerms() only.

example:

  my @t = $solr->expandTerms('terms.lower.incl' => 'true');
  my @t = $solr->expandTerms([lower_incl => 1]);   # same
  my $r = $self->queryTerms(fl => 'subject', limit => 100);
    

$obj->ignored($message)

Produce a warning $message about parameters which will get ignored because they were not yet supported by the indicated server version.

$obj->removed($message)

Produce a warning $message about parameters which will not be passed on, because they were removed from the indicated server version.

Other helpers

$obj->endpoint($action, %options)

Compute the address to be called (for HTTP)

 -Option--Default
  core    new(core)
  params  []
    

$obj->request($url, $result, $body, $ct)

Send a request to the server $url and return the response (an HTTP::Response object). A trace of the activity is added to the $result object. The $body of the request can be provided as bytes or reference to bytes (SCALAR). The content-type $ct must match the body bytes.

Comparison with other implementations

Compared to WebService::Solr

WebService::Solr is a good module, with a lot of miles. The main differences is that "Apache::Solr" has much more abstraction.

• simplified parameter syntax, improving readibility
• real Perl-level boolean parameters, not 'true' and 'false'
• warnings for deprecated and ignored parameters
• smart result object with built-in trace and timing
• hidden paging of results
• flexible logging framework (Log::Report)
• both-way XML or both-way JSON, not requests in XML and answers in JSON
• access to plugings like terms and tika
• no Moose