NAME

       WebService::Solr::Query - Abstract query syntax for Solr queries

SYNOPSIS

           my $query  = WebService::Solr::Query->new( { foo => 'bar' } );
           my $result = $solr->search( $query );

DESCRIPTION

       WebService::Solr::Query provides a programmatic way to generate queries to be sent to
       Solr. Syntax wise, it attempts to be as close to SQL::Abstract WHERE clauses as possible,
       with obvious exceptions for idioms that do not exist in SQL. Just as values in
       SQL::Abstract are SQL-escaped, this module does the appropriate Solr-escaping on all
       values passed to the object (see "escape()").

QUERY SYNTAX

   Key-Value Pairs
       The simplest way to search is with key value pairs.

           my $q = WebService::Solr::Query->new( { foo => 'bar' } );
           # RESULT: (foo:"bar")

   Implicit AND and OR
       By default, data received as a HASHREF is AND'ed together.

           my $q = WebService::Solr::Query->new( { foo => 'bar', baz => 'quux' } );
           # RESULT: (foo:"bar" AND baz:"quux")

       Furthermore, data received as an ARRAYREF is OR'ed together.

           my $q = WebService::Solr::Query->new( { foo => [ 'bar', 'baz' ] } );
           # RESULT: (foo:"bar" OR foo:"baz")

   Nested AND and OR
       The ability to nest AND and OR boolean operators is essential to express complex queries.
       The "-and" and "-or" prefixes have been provided for this need.

           my $q = WebService::Solr::Query->new( { foo => [
               -and => { -prohibit => 'bar' }, { -require => 'baz' }
           ] } );
           # RESULT: (((-foo:"bar") AND (+foo:"baz")))

           my $q = WebService::Solr::Query->new( { foo => [
               -or => { -require => 'bar' }, { -prohibit => 'baz' }
           ] } );
           # RESULT: (((+foo:"bar") OR (-foo:"baz")))

   Default Field
       To search the default field, use the "-default" prefix.

           my $q = WebService::Solr::Query->new( { -default => 'bar' } );
           # RESULT: ("bar")

   Require/Prohibit
           my $q = WebService::Solr::Query->new( { foo => { -require => 'bar' } } );
           # RESULT: (+foo:"bar")

           my $q = WebService::Solr::Query->new( { foo => { -prohibit => 'bar' } } );
           # RESULT: (-foo:"bar")

   Range
       There are two types of range queries, inclusive ("-range_inc") and exclusive
       ("-range_exc"). The "-range" prefix can be used in place of "-range_inc".

           my $q = WebService::Solr::Query->new( { foo => { -range => ['a', 'z'] } } );
           # RESULT: (+foo:[a TO z])

           my $q = WebService::Solr::Query->new( { foo => { -range_exc => ['a', 'z'] } } );
           # RESULT: (+foo:{a TO z})

   Boost
           my $q = WebService::Solr::Query->new( { foo => { -boost => [ 'bar', '2.0' ] } } );
           # RESULT: (foo:"bar"^2.0)

   Proximity
           my $q = WebService::Solr::Query->new( { foo => { -proximity => [ 'bar baz', 10 ] } } );
           # RESULT: (foo:"bar baz"~10)

   Fuzzy
           my $q = WebService::Solr::Query->new( { foo => { -fuzzy => [ 'bar', '0.8' ] } } );
           # RESULT: (foo:bar~0.8)

   Literal Queries
       Specifying a scalar ref as a value in a key-value pair will allow arbitrary queries to be
       sent across the line. NB: This will bypass any data massaging done on regular strings,
       thus the onus of properly escaping the data is left to the user.

           my $q = WebService::Solr::Query->new( { '*' => \'*' } )
           # RESULT (*:*)

ACCESSORS

       •   query - stores the original query structure

METHODS

   new( \%query )
       Creates a new query object with the given hashref.

   stringify( )
       Converts the supplied structure into a Solr/Lucene query.

   escape( $value )
       The following values must be escaped in a search value:

           + - & | ! ( ) { } [ ] ^ " ~ * ? : \

       NB: Values sent to "new()" are automatically escaped for you.

   unescape( $value )
       Unescapes values escaped in "escape()".

   D
       Debugging constant, default: off.

   BUILDARGS
       Moo method to handle input to "new()".

SEE ALSO

       •   WebService::Solr

       •   http://wiki.apache.org/solr/SolrQuerySyntax

AUTHORS

       Andy Lester "andy@petdance.com"

       Brian Cassidy <bricas@cpan.org>

       Jos Boumans <kane@cpan.org>

COPYRIGHT AND LICENSE

       Copyright 2008-2014 National Adult Literacy Database Copyright 2015-2020 Andy Lester

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