Apache Solr Documentation

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

Older Versions of this Guide (PDF)

6.5 Draft Ref Guide Topics


This Unreleased Guide Will Cover Apache Solr 6.5

Skip to end of metadata
Go to start of metadata

The Request Parameters API allows creating parameter sets, a.k.a. paramsets, that can override or take the place of parameters defined in solrconfig.xml. The parameter sets defined with this API can be used in requests to Solr, or referenced directly in solrconfig.xml request handler definitions.

It is really another endpoint of the Config API instead of a separate API, and has distinct commands. It does not replace or modify any sections of solrconfig.xml, but instead provides another approach to handling parameters used in requests. It behaves in the same way as the Config API, by storing parameters in another file that will be used at runtime. In this case, the parameters are stored in a file named params.json. This file is kept in ZooKeeper or in the conf directory of a standalone Solr instance.

The settings stored in params.json are used at query time to override settings defined in solrconfig.xml in some cases as described below.

When might you want to use this feature?

  • To avoid frequently editing your solrconfig.xml to update request parameters that change often.
  • To reuse parameters across various request handlers.
  • To mix and match parameter sets at request time.
  • To avoid a reload of your collection for small parameter changes.

The Request Parameters Endpoint

All requests are sent to the /config/params endpoint of the Config API. 

Setting Request Parameters

The request to set, unset, or update request parameters is sent as a set of Maps with names.  These objects can be directly used in a request or a request handler definition.

The available commands are:

  • set: Create or overwrite a parameter set map.
  • unset: delete a parameter set map.
  • update: update a parameter set map. This is equivalent to a map.putAll(newMap) . Both the maps are merged and if the new map has same keys as old they are overwritten

You can mix these commands into a single request if necessary.

Each map must include a name so it can be referenced later, either in a direct request to Solr or in a request handler definition.

In the following example, we are setting 2 sets of parameters named 'myFacets' and 'myQueries'.

In the above example all the parameters are equivalent to the "defaults" in solrconfig.xml. It is possible to add invariants and appends as follows:

Using Request Parameters with RequestHandlers

After creating the my_handler_params paramset in the above section, it is possible to define a request handler as follows:

It will be equivalent to a standard request handler definition such as this one:

Implicit RequestHandlers

Solr ships with many out-of-the-box request handlers that may only be configured via the Request Parameters API, because their configuration is not present in solrconfig.xml.  See Implicit RequestHandlers for the paramset to use when configuring an implicit request handler.

Viewing Expanded Paramsets and Effective Parameters with RequestHandlers

To see the expanded paramset and the resulting effective parameters for a RequestHandler defined with useParams, use the expandParams request param.  E.g. for the /export request handler:

Viewing Request Parameters

To see the paramsets that have been created, you can use the /config/params endpoint to read the contents of params.json, or use the name in the request:

The useParams Parameter

When making a request, the useParams parameter applies the request parameters sent to the request. This is translated at request time to the actual parameters. 

For example (using the names we set up in the earlier examples, please replace with your own name):

It is possible to pass more than one parameter set in the same request. For example:

In the above example the param set 'myQueries' is applied on top of 'myFacets'. So, values in 'myQueries' take precedence over values in 'myFacets'. Additionally, any values passed in the request take precedence over 'useParams'parameters. This acts like the "defaults" specified in the '<requestHandler>' definition in solrconfig.xml.

The parameter sets can be used directly in a request handler definition as follows. Please note that the 'useParams' specified is always applied even if the request contains useParams.

To summarize, parameters are applied in this order:

  • parameters defined in <invariants> in solrconfig.xml.
  • parameters applied in _invariants_ in params.json and that is specified in the requesthandler definition or even in request
  • parameters defined in the request directly. 
  • parameter sets defined in the request, in the order they have been listed with useParams.
  • parameter sets defined in params.json that have been defined in the request handler.
  • parameters defined in <defaults> in solrconfig.xml.

Public APIs

The RequestParams Object can be accessed using the method SolrConfig#getRequestParams(). Each paramset can be accessed by their name using the method RequestParams#getRequestParams(String name).


The Solr "films" example demonstrates the use of the parameters API.   See https://github.com/apache/lucene-solr/tree/master/solr/example/films for details.


  • No labels


  1. The set and set map terms are rather confusing here. Especially when update command says  that it will override them. Could we add more clarifying text. Also, maybe provide example specifically for the update command (e.g. from films example) to clarify it.

  2. "parameters are applied in this order:"  To clarify, do you mean that a value for a parameter is effectively the first occurrence in this list?  As-written, one might interpret this wording as the list getting "applied" in order such that the last overwrites any previous value; though I don't think that is intended.

  3. The first one takes precedence over the next.

  4. Where do we actually define what paramSet declarations inside solrconfig.xml looks like? Is that in some other place in documentation? If so, can we link to that? Or mention the name at least (initParams, right?)

    Actually, I might be just confused on how initParams and paramsets and useParams interplay. Some sort of clarification is definitely needed.

    1. Param Sets have no equivalent in solrconfig.xml. It can only be specified in the params.json.  InitParams are introduced just because we have implicit requesthandlers. it is just a substitute of placing config inside the <requesthandler> tag.


      I'm thinking of getting rid of initParams altogether by specifying a default paramset for all implicitly defined handlers . That way we will have configuration only in params.json.

      for instance the /get can have an implicit param set defined as useParams="_get"  , so users can manage configuration for all requesthandlers from params.json

    2. A Request Handler can have arbitrary parameters. ParamSets only support the "defaults", "invariants", "appends" functionality