NAME

Apache::Solr - Apache Solr (Lucene) extension

INHERITANCE

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

SYNOPSIS

# use Log::Report mode => "DEBUG";
my $solr    = Apache::Solr->new(server => $url, field_key_simplify => 0);
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;

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 https://wiki.apache.org/solr/ and https://lucene.apache.org/solr/

METHODS

Constructors

$class->new(%options)

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

-Option            --Default
 agent               <created internally>
 autocommit          true
 core                undef
 field_key_simplify  true
 format              'XML'
 retry_max           60
 retry_wait          5
 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. 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.

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.

field_key_simplify => BOOLEAN

[1.12] support the use of underscores ('_') as alternative for dot ('.') in field paths. For backwards compatibility reasons, this field has the wrong default, see example.

format => 'XML'|'JSON'

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

retry_max => COUNT

[1.09] When the server(-connection) persists in producing errors, it may not recover at all. Let's not block the main code. Of course, it may take considerable time for each error to show, so the communication failure can take much, much longer than retry_wait times retry_max seconds.

You can disable retries with with '0'.

retry_wait => $seconds

[1.09] When the connection to the Solr server fails, or when the server does not respond correctly, a retry is attempted after waiting a few $seconds. You may use '0' to skip waiting.

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.5. Try to get this setting right, because it will help you a lot in correct parameter use and support for the right features.

We know now that this can be requested via /admin/info/system, but do not spend more development time on this module until it gets more users.

» example: field_key_simplify

[1.12] On the Perl side, the query parameter structure is processed as a HASH. The Solr fields are nested with dots, which means they are not barewords which can be used unquoted as has keys. That's inconvenient. So, you can use an underscore instead of a dot. However: the underscore is also a value character in a field name token. So, it is very unwise to enable this rewrite even though it makes your Perl pretty.

 f_cat_facet  => { missing => 1 },  # by default means:
'f.cat.facet' => { missing => 1 },

 f.myinteger_i.facet.range.start    # is by default rules:
 f.myinteger.i.facet.range.start    # which is broken.

Wrong default kept to be backwards compatible.

Attributes

$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->fieldKeySimplify(): [1.12] Returns true when underscores in field paths are to be interpreted as dots. This is true by default, but deprecated. Please expliticly disable this rewrite rule by setting new(field_key_simplify) to false.
$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 https://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 https://wiki.apache.org/solr/UpdateXmlMessages. Missing are the atomic updates.

$obj->addDocument($doc|\@docs, %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: [removed since Solr 4.0] 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: [removed since Solr 4.0] Use option overwrite.
overwritePending => BOOLEAN: [removed since Solr 4.0] Use option overwrite.

$obj->commit(%options)

-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, removed in 4.0]
waitSearcher => BOOLEAN

$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

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|\@ids: The expected content of the uniqueKey fields (usually named id) for the documents to be removed.
query => $query|\@queries

$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 https://wiki.apache.org/solr/ExtractingRequestHandler

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

commit => BOOLEAN: [0.94] commit the document to the database.
content_type => MIME
file => FILENAME|FILEHANDLE: Either file or string must be used.
string => STRING|SCALAR: The document provided as normal text or a reference to raw text. You may also specify the file option with a filename.

» example:

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

$obj->optimize(%options)

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

maxSegments => INTEGER: [since Solr 1.3]
softCommit => BOOLEAN: [since Solr 4.0]
waitFlush => BOOLEAN: [before Solr 1.4, removed from 4.0]
waitSearcher => BOOLEAN

$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(%options)

[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>

core => $name

» example:

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

$obj->coreStatus(%options)

[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>

core => $name

» example:

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>

core => $name

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 (see new(field_key_simplify))
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|\@pairs)

Used by extractDocument().

[0.93] If the key is literal or literals, then the keys in the value HASH (or @pairs ARRAY) 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 @pairs ARRAY). [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.

expand
facet -> https://wiki.apache.org/solr/SimpleFacetParameters
hl (highlight) -> https://wiki.apache.org/solr/HighlightingParameters
mlt -> https://solr.apache.org/guide/8_11/morelikethis.html
stats -> https://wiki.apache.org/solr/StatsComponent
suggest -> https://solr.apache.org/guide/8_11/suggester.html
group -> https://wiki.apache.org/solr/FieldCollapsing

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

» example:

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|\@pairs)

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  []

core => $name: If no core is specified, the default of the server is addressed.
params => %params|\@params: The order of the parameters will be preserved when an ARRAY or parameters is passed; you never know for a HASH.

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

DETAILS

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

DIAGNOSTICS

Fault: Cannot read document from $fn: $!: Cast by extractDocument()
Fault: Read error for document $fn: $!: Cast by extractDocument()
Fault: Solr request failed after $elapse seconds after $retries retries: $!: Cast by request()
Alert: Solr request failed with $code, $retries retries left: $!: Cast by request()
Error: Solr request failed with: $err: Cast by request()
Warning: deprecated solr $message: Cast by deprecated()
Error: extract requires document as file or string.: Cast by extractDocument()
Error: extractDocument() requires Solr v1.4 or higher.: Cast by extractDocument()
Error: field $field is not simple for a set.: Cast by expandSelect()
Warning: ignored solr $message: Cast by ignored()
Warning: removed solr $message: Cast by removed()
Error: rollback not supported by your solr server version.: Cast by rollback()
Error: set $set cannot be used per field, in $field.: Cast by expandSelect()
Error: unknown field set $set.: Cast by expandSelect()

LICENSE

For contributors see file ChangeLog.

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

To install Apache::Solr, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Apache::Solr

CPAN shell

perl -MCPAN -e shell
install Apache::Solr

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

INHERITANCE

SYNOPSIS

DESCRIPTION

METHODS

Constructors

Attributes

Commands

Search

Updates

Core management

Helpers

Parameter pre-processing

Other helpers

DETAILS

Comparison with other implementations

Compared to WebService::Solr

DIAGNOSTICS

SEE ALSO

LICENSE

Module Install Instructions

Keyboard Shortcuts