Request Parameters API

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'.

curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json'  -d '{
  "set":{
    "myFacets":{
      "facet":"true",
      "facet.limit":5}},
  "set":{
    "myQueries":{
      "defType":"edismax",
      "rows":"5",
      "df":"text_all"}}
}'

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:

curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json'  -d '{
  "set":{
    "my_handler_params":{
      "facet.limit":5,
      "_invariants_": {
        "facet":true,
       },
      "_appends_":{"facet.field":["field1","field2"]
     }
   }}
}'

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:

<requestHandler name="/my_handler" class="solr.SearchHandler" useParams="my_handler_params"/>

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

<requestHandler name="/my_handler" class="solr.SearchHandler">
  <lst name="defaults">
    <int name="facet.limit">5</int>
  </lst>
  <lst name="invariants">
    <bool name="facet">true</bool>
  </lst>
  <lst name="appends">
    <arr name="facet.field">
      <str>field1</str>
      <str>field2</str>
    </arr>
  </lst>
</requestHandler>

Implicit RequestHandlers with the Request Parameters API

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 parameter. As an example, for the /export request handler:

curl http://localhost:8983/solr/techproducts/config/requestHandler?componentName=/export&expandParams=true

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:

curl http://localhost:8983/solr/techproducts/config/params

#Or use the paramset name
curl http://localhost:8983/solr/techproducts/config/params/myQueries

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):

http://localhost/solr/techproducts/select?useParams=myQueries

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

http://localhost/solr/techproducts/select?useParams=myFacets,myQueries

In the above example the parameter 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.

<requestHandler name="/terms" class="solr.SearchHandler" useParams="myQueries">
  <lst name="defaults">
    <bool name="terms">true</bool>
    <bool name="distrib">false</bool>
  </lst>
  <arr name="components">
    <str>terms</str>
  </arr>
</requestHandler>

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).

Examples Using the Request Parameters API

The Solr "films" example demonstrates the use of the parameters API. You can use this example in your Solr installation (in the example/films directory) or view the files in the Apache GitHub mirror at https://github.com/apache/lucene-solr/tree/master/solr/example/films.