solr/solr-ref-guide/src/request-parameters-api.adoc

= Request Parameters API
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

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.adoc#,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.

== Configuring Request Parameters

The request to set, 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 request to delete parameter set is sent as list of names or a name.

The available commands are:

* `set`: Create or overwrite a parameter set map.
* `delete`: Remove a request 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.

For `set` or `update` commands, 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'.

[source,bash]
----
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:

[source,bash]
----
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"]
     }
   }}
}'
----

In the following example, two set of parameters named 'myFacets' and 'myQueries' are deleted.

[source,bash]
----
curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json'  -d '{
  "delete":[
    "myFacets",
    "myQueries"
  ]
}'
----

When deleting a single parameter set, the value could be specified as string instead of list.

[source,bash]
----
curl http://localhost:8983/solr/techproducts/config/params -H 'Content-type:application/json'  -d '{
  "delete":"myFacets"
}'
----

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

[source,xml]
----
<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:

[source,xml]
----
<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.adoc#,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:

[source,bash]
----
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:

[source,bash]
----
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):

[source,text]
----
http://localhost/solr/techproducts/select?useParams=myQueries
----

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

[source,text]
----
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`.

[source,xml]
----
<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 are specified in the request handler definition or even in a single 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/leader/solr/example/films.