view release on metacpan or  search on metacpan

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

=item 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.

=item 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 C</admin/info/system>, but
do not spend more development time on this module until it gets more
users.

=back

=back

=head2 Accessors

=over 4

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

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

=item $obj-E<gt>B<autocommit>( [BOOLEAN] )

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

Returns the $core, when not defined the default core as set by L<new(core)|Apache::Solr/"Constructors">.
May return C<undef>.

=item $obj-E<gt>B<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 C<$uri>
object.

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

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

=back

=head2 Commands

=head3 Search

=over 4

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

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

$terms are passed to L<expandTerms()|Apache::Solr/"Parameter pre-processing"> before being used.

B<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))
     ...

=item $obj-E<gt>B<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 L<expandSelect()|Apache::Solr/"Parameter pre-processing"> 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
L<Apache::Solr::Result|Apache::Solr::Result> object initiation).  For instance, C<sequential>.
For backwards compatability reasons, they have to be passed in a HASH
as optional first parameter.

=back

=head3 Updates

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

=over 4

=item $obj-E<gt>B<addDocument>( <$doc|ARRAY>, %options )

Add one or more documents (L<Apache::Solr::Document|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>

=over 2

=item allowDups => BOOLEAN

[removed since Solr 4.0]  Use option C<overwrite>.

=item commit => BOOLEAN

=item commitWithin => SECONDS

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

=item overwrite => BOOLEAN

=item overwriteCommitted => BOOLEAN

[removed since Solr 4.0]  Use option C<overwrite>.

=item overwritePending => BOOLEAN

[removed since Solr 4.0]  Use option C<overwrite>.

=back

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

 -Option        --Default
  expungeDeletes  <false>
  softCommit      <false>

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

  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: 

  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
  );

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

The L<select()|Apache::Solr/"Search"> 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.

=over 4

=item * expand

=item * facet -> F<http://wiki.apache.org/solr/SimpleFacetParameters>

=item * hl (highlight) -> F<http://wiki.apache.org/solr/HighlightingParameters>

=item * mlt -> F<https://solr.apache.org/guide/8_11/morelikethis.html>

=item * stats -> F<http://wiki.apache.org/solr/StatsComponent>

=item * suggest -> F<https://solr.apache.org/guide/8_11/suggester.html>

=item * group -> F<http://wiki.apache.org/solr/FieldCollapsing>

=back

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

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

Used by L<queryTerms()|Apache::Solr/"Search"> 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);

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

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

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

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

=back

=head3 Other helpers

=over 4

=item $obj-E<gt>B<endpoint>($action, %options)

Compute the address to be called (for HTTP)

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

=over 2

=item core => NAME

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

=item 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.

=back

=item $obj-E<gt>B<request>($url, $result, $body, $ct)

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

=back

=head1 DETAILS

=head2 Comparison with other implementations

=head3 Compared to WebService::Solr

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

=over 4