VuFind Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Search Customization ======

Starting with VuFind 1.0RC2, the search options available to your users are completely customizable through configuration files.

===== Defining Search Types =====

The available search types are defined in a file called searchspecs.yaml.  This file may be found in config/vufind and may be copied and customized in the config/vufind subdirectory of your [[configuration:local_settings_directory|local settings directory]].

[[http://www.yaml.org/|YAML]] is a text file format for storing data that is a little more flexible than the standard .ini files used by most of VuFind.  Don't be intimidated -- most simple changes can be made without needing a deep understanding of how YAML works, and most new searches you will need can be created by copying some of the samples provided with the default VuFind installation.

The comments embedded in the YAML file provide full details on how the searches need to be defined; that information is not duplicated here to avoid redundancy.  This Wiki page is intended as a general overview of customization issues rather than a full technical spec.


==== Dismax vs. Lucene ====

In order to understand the VuFind search configuration, it is helpful to understand the difference between Dismax and Lucene queries.  Both are types of queries that the Solr index can perform.  If you are interested in the technical details, see the [[http://wiki.apache.org/solr/DisMaxRequestHandler|Solr Wiki]].  From a practical perspective, the key difference is that Dismax is better at providing relevant results for simple queries, but Lucene offers more features (boolean operators, wildcards, mixed-index searching).

VuFind tries to use Dismax searches when possible, but it uses Lucene when it has to because of advanced features.  For best results when creating a new search type, you should try to provide enough settings to allow both Dismax searches (via "DismaxFields") AND Lucene searches (via "QueryFields").  Note that you must always provide Lucene settings, even if you choose never to use Dismax.

==== Search Tuning ====

There are a few simple adjustments you can make to tweak search results to your liking.

=== Weighting ===

One of the easiest and most common things you may wish to customize in searchspecs.yaml is search field weighting.  The numbers found throughout the YAML file are relative weights applied during searches to rank results, and these can be adjusted to change the order in which search results appear.  For example, you might decide that in an AllFields search, Authors are more important than Titles -- you could cause records with hits in the author field to rise above records with hits in the title field simply by changing the appropriate numbers.  When making changes, be sure to keep the Dismax-related settings consistent with the Lucene-related settings for more predictable results.

=== Fuzziness ===

Sometimes, you don't want to require matches on all of the terms provided by the user's search string.  Finding the right balance between too few and too many search results is another area where trial and error may be necessary.  Adjusting the fuzziness of results differs for Dismax vs. Lucene searches due to the varying capabilities of the two search types.

For Dismax, you can configure the "mm" parameter in the "DismaxParams" section of the YAML file.  This parameter lets you control the number of required terms based on the number of input terms.  It is very flexible, and details of exactly how it works can be found in the [[http://wiki.apache.org/solr/DisMaxRequestHandler#mm_.28Minimum_.27Should.27_Match.29|Solr Wiki]].

For Lucene, you have a bit less flexibility, but many searches in the YAML file combine search terms using both a Boolean AND operator and a Boolean OR operator, giving the ANDed terms a greater weight than the ORed terms.  You can read the comments in the YAML file and look at the examples for more details of how this works.

===== Search Interface Customization =====

A file called [[configuration:files:searches.ini]] is used to control which of the search types defined in searchspecs.yaml are used by VuFind.  The [Basic_Searches] section defines which search options are displayed in the basic search box found on most pages of the interface.  The [Advanced_Searches] section defines which search options are displayed on the Advanced Search screen.  You can adjust the order in both areas to meet your needs.  Note that if you are working in a multi-language environment, you will need to create translations for any text you enter into searches.ini in the language files found in the web/lang directory.

===== Other Customizable Options =====

The [General] section of [[configuration:files:searches.ini]] allows some additional customization of search-related features:

  * The case_sensitive_bools setting lets you choose whether boolean operators in the search string must be ALL UPPERCASE in order to be recognized (true) or if they will be used regardless of case (false).  The default setting is true.
  * The default_handler setting lets you specify which of the searches from searchspecs.yaml is used by default when no other handler is chosen.

===== Related Video =====

Some of the topics from this page are also covered in the [[videos:configuring_search_and_facet_settings|Configuring Search and Facet Settings]] video.