Mark Overmeer > Apache-Solr-0.92 > Apache::Solr



Annotate this POD


Open  2
View/Report Bugs
Module Version: 0.92   Source   Latest Release: Apache-Solr-0.98


Apache::Solr - Apache Solr (Lucene) extension


 Apache::Solr is extended by


  my $solr    = Apache::Solr->new(server => $url);

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

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

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


Solr is a stand-alone full-text search-engine, with loads of features. The main component is Lucene. This module tries to provide a high level interface to the Solr server.

BE WARNED: this code is very new! Please help me improve this code by sending bugs and suggesting improvements.




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

 -Option        --Default
  agent           <created internally>
  autocommit      true
  core            undef
  format          'XML'
  server          <required>
  server_version  <latest>
agent => LWP::UserAgent object

Agent which implements the communication between this client and the Solr server. When you have multiple Apache::Solr objects in your program, you may want to share this agent, to share the connection.

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

autocommit => BOOLEAN

Commit all changes immediately unless specified differently.

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.

format => 'XML'|'JSON'

Communication format between client and server. You may also instantiate Apache::Solr::XML or Apache::Solr::JSON directly.

server => URL

The locations of the Solr server depends on the way the java environment is set-up. The URL is either an URI object or a string which can be instantiated as such.

server_version => VERSION

By default the latest version of the server software, currently 4.0. Try to get this setting right, because it will help you a lot in correct parameter use and support for the right features.



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


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


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.


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




Search for often used terms. See

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.


  my $r = $self->queryTerms(fl => 'subject', limit => 100);
  {   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))

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.


See 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>
allowDups => BOOLEAN

[deprecated since Solr 1.1??] Use option overwrite.

commit => BOOLEAN
commitWithin => SECONDS

[Since Solr 3.4] Automatically translated into 'commit' for older servers. Currently, the resolution is milli-seconds.

overwrite => BOOLEAN
overwriteCommitted => BOOLEAN

[deprecated since Solr 1.1??]

overwritePending => BOOLEAN

[deprecated since Solr 1.1??]

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

[since Solr 1.4]

softCommit => BOOLEAN

[since Solr 4.0]

waitFlush => BOOLEAN

[before Solr 1.4]

waitSearcher => BOOLEAN

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

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

When specified, it indicates whether to commit (update the indexes) after the last delete. By default the value of new(autocommit).

fromCommitted => BOOLEAN

[deprecated since ?]

fromPending => BOOLEAN

[deprecated since ?]

id => ID|ARRAY-of-IDs

The expected content of the uniqueKey fields (usually named id) for the documents to be removed.

query => QUERY|ARRAY-of-QUERYs

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.


 -Option      --Default
  content_type  <from> filename
  file          undef
  string        undef
content_type => MIME

Either file or string must be used.


The string can either be


   my $r = $solr->extractDocument(file => 'design.pdf'
     , literal_id => 'host');
 -Option      --Default
  maxSegments   1
  softCommit    <false>
  waitFlush     <true>
  waitSearcher  <true>
maxSegments => INTEGER

[since Solr 1.3]

softCommit => BOOLEAN

[since Solr 4.0]

waitFlush => BOOLEAN

[before Solr 1.4]

waitSearcher => BOOLEAN

[solr 1.4]


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:


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


Used by extractDocument().


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.

You may use WebService::Solr::Query to construct the query ('q').


  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)

Used by queryTerms() only.


  my @t = $solr->expandTerms('terms.lower.incl' => 'true');
  my @t = $solr->expandTerms([lower_incl => 1]);   # same

  my $r = $self->queryTerms(fl => 'subject', limit => 100);

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

Other helpers

$obj->endpoint(ACTION, OPTIONS)

Compute the address to be called (for HTTP)

  core    new(core)
  params  []
core => NAME

If no core is specified, the default of the server is addressed.

params => HASH|ARRAY-of-pairs

The order of the parameters will be preserved when an ARRAY or parameters is passed; you never know for a HASH.


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.


This module is part of Apache-Solr distribution version 0.92, built on December 06, 2012. Website:


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

syntax highlighting: