senselogic.sitevision.api.search.searcher

Interface Searcher

public interface Searcher

A searcher with highly configurable behaviour.

The Searcher is the mother of all querying and the powerful big brother of SearchUtil. When the basic convenience methods in SearchUtil doesn't fit your needs, you can always use the Searcher instead!

The behaviour of a Searcher is stipulated via it's assembly of components. The following components are available:

• Parser - what parser should be used to handle the queries and what field/fields should be queried?
• Filter - how should the result be limited?
• SpellCheck - should the search engine try to get suggestions (did you mean)?
• Highlight - which fields should be highlighted and how?
• Sort - how should the result be sorted?
• Monitor - how should querying be monitored? (e.g. should search query logging mode be on or off?)
• PermissionCheck - how should permission checks be performed? (Note! Only applicable when querying a sv:nodeIndex)

All components are optional and are assembled using a SearcherBuilder. When the Searcher is created, it can be re-used for subsequent searching.

Example of how to get and use a Searcher in Velocity:

   ## Get the search factory
   #set ($searchFactory = $sitevisionUtils.searchFactory)

   ## Get the search builder
   #set ($searcherBuilder = $searchFactory.searcherBuilder)

   ## Configure the search builder (use component builders to create whatever components that is needed and add them)
   ...

   ## Create the searcher
   #set ($searcher = $searcherBuilder.build())

   ## Search and handle the result
   #set ($searchResult = $searcher.search('example*', 10))
   #if ($searchResult.hasHits())
   <ol>
       #foreach ($hit in $searchResult.hits)
          <li>...</li>
       #end
   </ol>
   #end
 

What index to query can also be specified via the SearcherBuilder. Please note that fields might differ between index so if you query multiple indexes and re-use the SearcherBuilder, you must also re-set the components that are field-dependant (e.g. the Sort, the Highlight, the Parser if you have specified custom query fields etc.).

Example of how to query two indexes using server-side JavaScript
(i.e. search identities from the the user identity index and pages/files/images from the node index):

   // Get a search builder
   var searcherBuilder = require('SearcherBuilder');

   // Build a 'node index' Searcher and search
   var nodeSearcher = searcherBuilder // Will use the default node index
                         .build();
   var nodeResult = nodeSearcher.search('nisse', 3);

   // Build a 'user identity index' Searcher and search
   var indexUtil = require('IndexUtil');
   var userIdentityIndexType = require('IndexUtil.IndexType.USER_IDENTITY');
   var identityResult = searcherBuilder
                          .setIndex(indexUtil.getDefaultIndex(userIdentityIndexType))
                          .build()
                          .search('nisse', 10);

   // Iterate results
   var hits, hit;
   if (identityResult.hasHits()) {
      hits = identityResult.getHits();
      while (hits.hasNext()) {
         hit = hits.next();
         // Handle hit from user identity index
         ...
      }
   }
   if (nodeResult.hasHits()) {
      hits = nodeResult.getHits();
      while (hits.hasNext()) {
         hit = hits.next();
         // Handle hit from node index
         ...
      }
   }

Tip! The Builder interface documentation contains more information about Builders and how to work with them!

Query syntax note! Query strings should be expressed according to the Solr query syntax. The syntax is basically the Lucene query syntax with some minor differences (solr syntax allows open-ended range queries and pure negative queries). Also note that a general recommendation is to always use the prefix operators (+/-) instead of the boolean keywords (AND/OR/NOT) to avoid unexpected behaviour. For deeper understanding, see for example Why Not AND, OR, And NOT?.

An instance of the Sitevision class implementing this interface can be obtained via SearcherBuilder.build(). See SearcherBuilder for how to obtain an instance of the SearcherBuilder interface.

Since:

Sitevision 3.6

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
SearchResult	search(String aQuery, int aMaxHitsToReturn) Executes a search using the components/behaviour that was specified when the Searcher was created.
SearchResult	search(String aQuery, int aStartAtHit, int aMaxHitsToReturn) Executes a paginated search using the components/behaviour that was specified when the Searcher was created.
SearchResult	search(String aQuery, String aDisplayQuery, int aMaxHitsToReturn) Executes a search using the components/behaviour that was specified when the Searcher was created.
SearchResult	search(String aQuery, String aDisplayQuery, int aStartAtHit, int aMaxHitsToReturn) Executes a paginated search using the components/behaviour that was specified when the Searcher was created.

Method Detail

search

SearchResult search(String aQuery,
                    int aMaxHitsToReturn)
             throws IllegalArgumentException

Executes a search using the components/behaviour that was specified when the Searcher was created.

Note! aQuery will be stripped from Local params, see QueryStringUtil.stripLocalParams(String).

Parameters:

aQuery - the query string

aMaxHitsToReturn - maximum total number of hits to be returned

Returns:

the search result, never null

Throws:

IllegalArgumentException - if aQuery is null or whitespace-only, if aStartAtHit is negative, if aMaxHitsToReturn is negative or zero.

search

SearchResult search(String aQuery,
                    String aDisplayQuery,
                    int aMaxHitsToReturn)
             throws IllegalArgumentException

Executes a search using the components/behaviour that was specified when the Searcher was created.

This method is typically used if you want to execute a complex query (i.e. aQuery), but display a more simpler one (i.e. aDisplayQuery) when rendering the search result. Use SearchResult.getQuery() to get the aQuery and use SearchResult.getDisplayQuery() to get the aDisplayQuery.

Note! aQuery will be stripped from Local params, see QueryStringUtil.stripLocalParams(String).

Parameters:

aQuery - the query string

aDisplayQuery - the "human friendly" variant of the query string that can be used/retrieved when rendering the search result. Note! If aDisplayQuery is null, aQuery will be used as aDisplayQuery.

aMaxHitsToReturn - maximum total number of hits to be returned

Returns:

the search result, never null

Throws:

IllegalArgumentException - if aQuery is null or whitespace-only, if aStartAtHit is negative, if aMaxHitsToReturn is negative or zero.

Since:

Sitevision 3.6.4

search

SearchResult search(String aQuery,
                    int aStartAtHit,
                    int aMaxHitsToReturn)
             throws IllegalArgumentException

Executes a paginated search using the components/behaviour that was specified when the Searcher was created.

Note! aQuery will be stripped from Local params, see QueryStringUtil.stripLocalParams(String).

Parameters:

aQuery - the query string

aStartAtHit - number of leading hits to be skipped

aMaxHitsToReturn - maximum total number of hits to be returned

Returns:

the search result, never null

Throws:

IllegalArgumentException - if aQuery is null or whitespace-only, if aStartAtHit is negative, if aMaxHitsToReturn is negative or zero.

search

SearchResult search(String aQuery,
                    String aDisplayQuery,
                    int aStartAtHit,
                    int aMaxHitsToReturn)
             throws IllegalArgumentException

Executes a paginated search using the components/behaviour that was specified when the Searcher was created.

This method is typically used if you want to execute a paginated complex query (i.e. aQuery), but display a more simpler one (i.e. aDisplayQuery) when rendering the search result. Use SearchResult.getQuery() to get the aQuery and use SearchResult.getDisplayQuery() to get the aDisplayQuery.

Note! aQuery will be stripped from Local params, see QueryStringUtil.stripLocalParams(String).

Parameters:

aQuery - the query string

aDisplayQuery - the "human friendly" variant of the query string that can be used/retrieved when rendering the search result. Note! If aDisplayQuery is null, aQuery will be used as aDisplayQuery.

aStartAtHit - number of leading hits to be skipped

aMaxHitsToReturn - maximum total number of hits to be returned

Returns:

the search result, never null

Throws:

IllegalArgumentException - if aQuery is null or whitespace-only, if aStartAtHit is negative, if aMaxHitsToReturn is negative or zero.

Since:

Sitevision 3.6.4