Apache Solr Documentation

6.5 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

Ref Guide Topics


*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

After the <query> section of solrconfig.xml, request handlers and search components are configured.

A request handler processes requests coming to Solr. These might be query requests or index update requests. You will likely need several of these defined, depending on how you want Solr to handle the various requests you will make.

A search component is a feature of search, such as highlighting or faceting. The search component is defined in solrconfig.xml separate from the request handlers, and then registered with a request handler as needed.

These are often referred to as "requestHandler" and "searchComponent", which is how they are defined in solrconfig.xml.

Topics covered in this section:

Request Handlers

Every request handler is defined with a name and a class. The name of the request handler is referenced with the request to Solr, typically as a path. For example, if Solr is installed at http://localhost:8983/solr/ and you have a collection named "gettingstarted", you can make a request using URLs like this:


This query will be processed by the request handler with the name "/select". We've only used the "q" parameter here, which includes our query term, a simple keyword of "solr". If the request handler has more parameters defined, those will be used with any query we send to this request handler unless they are over-ridden by the client (or user) in the query itself.

If you have another request handler defined, you would send your request with that name. For example, /update is a request handler that handles index updates (i.e., sending new documents to the index). By default, /select is a request handler that handles query requests.

Request handlers can also process requests for nested paths of their names, for example, a request using /myhandler/extrapath may be processed by a request handler registered with the name /myhandler. If a request handler is explicitly defined by the name /myhandler/extrapath, that would take precedence over the nested path. This assumes you are using the request handler classes included with Solr; if you create your own request handler, you should make sure it includes the ability to handle nested paths if you want to use them with your custom request handler.

It is also possible to configure defaults for request handlers with a section called initParams. These defaults can be used when you want to have common properties that will be used by each separate handler. For example, if you intend to create several request handlers that will all request the same list of fields in the response, you can configure an initParams section with your list of fields. For more information about initParams, see the section InitParams in SolrConfig.


The primary request handler defined with Solr by default is the "SearchHandler", which handles search queries. The request handler is defined, and then a list of defaults for the handler are defined with a defaults list.

For example, in the default solrconfig.xml, the first request handler defined looks like this:

xml#666666solid explicit 10 ]]>

This example defines the rows parameter, which defines how many search results to return, to "10". The echoParams parameter defines that the parameters defined in the query should be returned when debug information is returned. Note also that the way the defaults are defined in the list varies if the parameter is a string, an integer, or another type.

All of the parameters described in the section on searching can be defined as defaults for any of the SearchHandlers.

Besides defaults, there are other options for the SearchHandler, which are:

  • appends: This allows definition of parameters that are added to the user query. These might be filter queries, or other query rules that should be added to each query. There is no mechanism in Solr to allow a client to override these additions, so you should be absolutely sure you always want these parameters applied to queries.

    xml#666666solid inStock:true ]]>

    In this example, the filter query "inStock:true" will always be added to every query.

  • invariants: This allows definition of parameters that cannot be overridden by a client. The values defined in an invariants section will always be used regardless of the values specified by the user, by the client, in defaults or in appends.

    xml#666666solid cat manu_exact price:[* TO 500] price:[500 TO *] ]]>

    In this example, facet fields have been defined which limits the facets that will be returned by Solr. If the client requests facets, the facets defined with a configuration like this are the only facets they will see.

The final section of a request handler definition is components, which defines a list of search components that can be used with a request handler. They are only registered with the request handler. How to define a search component is discussed further on in the section on Search Components. The components element can only be used with a request handler that is a SearchHandler.

The solrconfig.xml file includes many other examples of SearchHandlers that can be used or modified as needed.


The UpdateRequestHandlers are request handlers which process updates to the index.

In this guide, we've covered these handlers in detail in the section Uploading Data with Index Handlers.


It is possible to configure a request handler to search across shards of a cluster, used with distributed search. More information about distributed search and how to configure the shardHandler is in the section Distributed Search with Index Sharding.

Implicit Request Handlers

Solr includes many out-of-the-box request handlers that are not configured in solrconfig.xml, and so are referred to as "implicit" - see Implicit RequestHandlers.

Search Components

Search components define the logic that is used by the SearchHandler to perform queries for users.

Default Components

There are several default search components that work with all SearchHandlers without any additional configuration. If no components are defined (with the exception of first-components and last-components - see below), these are executed by default, in the following order:

Component Name

Class Name

More Information



Described in the section Query Syntax and Parsing.



Described in the section Faceting.



Described in the section MoreLikeThis.



Described in the section Highlighting.



Described in the section The Stats Component.



Described in the section on Common Query Parameters.

expandsolr.ExpandComponentDescribed in the section Collapse and Expand Results.

If you register a new search component with one of these default names, the newly defined component will be used instead of the default.

First-Components and Last-Components

It's possible to define some components as being used before (with first-components) or after (with last-components) the default components listed above.

first-components and/or last-components may only be used in conjunction with the default components. If you define your own components, the default components will not be executed, and first-components and last-components are disallowed.

xml#666666solid mycomponent spellcheck ]]>


If you define components, the default components (see above) will not be executed, and first-components and last-components are disallowed:

xml#666666solid mycomponent query debug ]]>

Other Useful Components

Many of the other useful components are described in sections of this Guide for the features they support. These are:


  • No labels


  1. may be it's not a problem,but I still want ask:

    in a shard query,it will call method "org.apache.solr.handler.component.QueryComponent.java ' s mergeIds()", solr will create a 

    ShardFieldSortedHitQueue , and it's size is offset+rows+1, it's dangerous when user giveing a big value,gonna cost huge memory, solr designer doesn't concern it ?

    1. I'm not sure about the specifics with how the java classes are used internally, but I can tell you this:  Distributed search with a large start (offset) parameter requires a lot of everything – CPU, memory, and I/O.  The reason is this:

      If you ask for a start value of 5000000 and rows of 100, each shard must gather information on 5000100 rows and send it to the coordinating node – the requested documents across all shards could be anywhere in those huge lists.  If you have ten shards, that's fifty million documents.  The coordinating node then compiles that information to determine which 100 documents match those requirements.

      If you need to page deeply into a result set, use cursors.  See Pagination of Results#PerformanceProblemswith%22DeepPaging%22

  2. got it;if I don't paging one by one, suddenly go page 1000000,any suggestion?

  3. hi team ,

    i just deployed the solr5.4 on my test server ,but i can't find the solrconfig.xml file for each collection, however , i can find such configuration file in server/solr/basic_configure dir , but it doesn't work after i change the configuration parameter. so confuse.

    1. If you are running in cloud mode, then the active configuration is loaded into zookeeper, rather than ${instanceDir}/conf.

  4. Hi All,

    I couldn't find documentation stating that processing of facets specified using the json.facet syntax require the component called 'facet_module'. 

    I discovered this when creating a custom requestHandler for queries that allows json.facet queries. My custom requestHandler (that uses my custom component 'my_custom_component') must be specifies as follows in order for the json.facet queries to produce results.

    <requestHandler name="/entities" class="solr.SearchHandler">
        <arr name="components">

    It seems best to add this to the documentation above. Cheers & solr is great.