Config API
The Config API enables manipulating various aspects of your solrconfig.xml
using REST-like API calls.
This feature is enabled by default and works similarly in both SolrCloud and standalone mode. Many commonly edited properties (such as cache sizes and commit settings) and request handler definitions can be changed with this API.
When using this API, solrconfig.xml
is not changed. Instead, all edited configuration is stored in a file called configoverlay.json
. The values in configoverlay.json
override the values in solrconfig.xml
.
Config API Endpoints
All Config API endpoints are collection-specific, meaning this API can inspect or modify the configuration for a single collection at a time.
collection/config
: retrieve the full effective config, or modify the config. Use GET to retrieve and POST for executing commands.collection/config/overlay
: retrieve the details in theconfigoverlay.json
only, removing any options defined insolrconfig.xml
directly or implicitly through defaults.collection/config/params
: create parameter sets that can override or take the place of parameters defined insolrconfig.xml
. See Request Parameters API for more information about this endpoint.
Retrieving the Config
All configuration items can be retrieved by sending a GET request to the /config
endpoint:
V1 API
http://localhost:8983/solr/techproducts/config
V2 API
http://localhost:8983/api/collections/techproducts/config
The response will be the Solr configuration resulting from merging settings in configoverlay.json
with those in solrconfig.xml
.
It’s possible to restrict the returned configuration to a top-level section, such as, query
, requestHandler
or updateHandler
. To do this, append the name of the section to the config
endpoint. For example, to retrieve configuration for all request handlers:
V1 API
http://localhost:8983/solr/techproducts/config/requestHandler
V2 API
http://localhost:8983/api/collections/techproducts/config/requestHandler
The output will be details of each request handler defined in solrconfig.xml
, all defined implicitly by Solr, and all defined with this Config API stored in configoverlay.json
. To see the configuration for implicit request handlers, add expandParams=true
to the request. See the documentation for the implicit request handlers for examples using this command.
The available top-level sections that can be added as path parameters are: query
, requestHandler
, searchComponent
, updateHandler
, queryResponseWriter
, initParams
, znodeVersion
, listener
, directoryFactory
, indexConfig
, and codecFactory
.
To further restrict the request to a single component within a top-level section, use the componentName
request parameter.
For example, to return configuration for the /select
request handler:
V1 API
http://localhost:8983/solr/techproducts/config/requestHandler?componentName=/select
V2 API
http://localhost:8983/api/collections/techproducts/config/requestHandler?componentName=/select
The output of this command will look similar to:
{
"config":{"requestHandler":{"/select":{
"name": "/select",
"class": "solr.SearchHandler",
"defaults":{
"echoParams": "explicit",
"rows":10,
"preferLocalShards":false
}}}}
}
The ability to restrict to objects within a top-level section is limited to request handlers (requestHandler
), search components (searchComponent
), and response writers (queryResponseWriter
).
Commands to Modify the Config
This API uses specific commands with POST requests to tell Solr what property or type of property to add to or modify in configoverlay.json
. The commands are passed with the data to add or modify the property or component.
The Config API commands for modifications are categorized into 3 types, each of which manipulate specific data structures in solrconfig.xml
. These types are:
set-property
andunset-property
for Common PropertiesComponent-specific
add-
,update-
, anddelete-
commands for Custom Handlers and Local Componentsset-user-property
andunset-user-property
for User-defined properties
Commands for Common Properties
The common properties are those that are frequently customized in a Solr instance. They are manipulated with two commands:
set-property
: Set a well known property. The names of the properties are predefined and fixed. If the property has already been set, this command will overwrite the previous setting.unset-property
: Remove a property set using theset-property
command.
The properties that can be configured with set-property
and unset-property
are predefined and listed below. The names of these properties are derived from their XML paths as found in solrconfig.xml
.
Update Handler Settings
See UpdateHandlers in SolrConfig for defaults and acceptable values for these settings.
updateHandler.autoCommit.maxDocs
updateHandler.autoCommit.maxTime
updateHandler.autoCommit.openSearcher
updateHandler.autoSoftCommit.maxDocs
updateHandler.autoSoftCommit.maxTime
updateHandler.commitWithin.softCommit
updateHandler.indexWriter.closeWaitsForMerges
Query Settings
See Query Settings in SolrConfig for defaults and acceptable values for these settings.
Caches and Cache Sizes
query.filterCache.class
query.filterCache.size
query.filterCache.initialSize
query.filterCache.autowarmCount
query.filterCache.maxRamMB
query.filterCache.regenerator
query.queryResultCache.class
query.queryResultCache.size
query.queryResultCache.initialSize
query.queryResultCache.autowarmCount
query.queryResultCache.maxRamMB
query.queryResultCache.regenerator
query.documentCache.class
query.documentCache.size
query.documentCache.initialSize
query.documentCache.autowarmCount
query.documentCache.regenerator
query.fieldValueCache.class
query.fieldValueCache.size
query.fieldValueCache.initialSize
query.fieldValueCache.autowarmCount
query.fieldValueCache.regenerator
Query Sizing and Warming
query.maxBooleanClauses
query.enableLazyFieldLoading
query.useFilterForSortedQuery
query.queryResultWindowSize
query.queryResultMaxDocCached
Query Circuit Breakers
See Circuit Breakers in Solr for more details
query.useCircuitBreakers
query.memoryCircuitBreakerThresholdPct
RequestDispatcher Settings
See RequestDispatcher in SolrConfig for defaults and acceptable values for these settings.
requestDispatcher.handleSelect
requestDispatcher.requestParsers.enableRemoteStreaming
requestDispatcher.requestParsers.enableStreamBody
requestDispatcher.requestParsers.multipartUploadLimitInKB
requestDispatcher.requestParsers.formdataUploadLimitInKB
requestDispatcher.requestParsers.addHttpRequestToContext
Examples of Common Properties
Constructing a command to modify or add one of these properties follows this pattern:
{"set-property":{"<property>": "<value>"}}
A request to increase the updateHandler.autoCommit.maxTime
would look like:
V1 API
curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' http://localhost:8983/api/collections/techproducts/config
You can use the config/overlay
endpoint to verify the property has been added to configoverlay.json
:
V1 API
curl http://localhost:8983/solr/techproducts/config/overlay?omitHeader=true
V2 API
curl http://localhost:8983/api/collections/techproducts/config/overlay?omitHeader=true
Output:
{
"overlay": {
"znodeVersion": 1,
"props": {
"updateHandler": {
"autoCommit": {"maxTime": 15000}
}
}}}
To unset the property:
V1 API
curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' http://localhost:8983/api/collections/techproducts/config
Commands for Handlers and Components
Request handlers, search components, and other types of localized Solr components (such as query parsers, update processors, etc.) can be added, updated and deleted with specific commands for the type of component being modified.
The syntax is similar in each case: add-<component-name>
, update-<component-name>
, and delete-<component-name>
. The command name is not case sensitive, so Add-RequestHandler
, ADD-REQUESTHANDLER
and add-requesthandler
are equivalent.
In each case, add-
commands add a new configuration to configoverlay.json
, which will override any other settings for the component in solrconfig.xml
.
update-
commands overwrite an existing setting in configoverlay.json
.
delete-
commands remove the setting from configoverlay.json
.
Settings removed from configoverlay.json
are not removed from solrconfig.xml
if they happen to be duplicated there.
The full list of available commands follows below:
Basic Commands for Components
These commands are the most commonly used:
add-requesthandler
update-requesthandler
delete-requesthandler
add-searchcomponent
update-searchcomponent
delete-searchcomponent
add-initparams
update-initparams
delete-initparams
add-queryresponsewriter
update-queryresponsewriter
delete-queryresponsewriter
Advanced Commands for Components
These commands allow registering more advanced customizations to Solr:
add-queryparser
update-queryparser
delete-queryparser
add-valuesourceparser
update-valuesourceparser
delete-valuesourceparser
add-transformer
update-transformer
delete-transformer
add-updateprocessor
update-updateprocessor
delete-updateprocessor
add-queryconverter
update-queryconverter
delete-queryconverter
add-listener
update-listener
delete-listener
add-runtimelib
update-runtimelib
delete-runtimelib
add-expressible
update-expressible
delete-expressible
Examples of Handler and Component Commands
To create a request handler, we can use the add-requesthandler
command:
curl -X POST -H 'Content-type:application/json' -d '{
"add-requesthandler": {
"name": "/mypath",
"class": "solr.DumpRequestHandler",
"defaults":{ "x": "y" ,"a": "b", "rows":10 },
"useParams": "x"
}
}' http://localhost:8983/solr/techproducts/config
V1 API
curl -X POST -H 'Content-type:application/json' -d '{
"add-requesthandler": {
"name": "/mypath",
"class": "solr.DumpRequestHandler",
"defaults": { "x": "y" ,"a": "b", "rows":10 },
"useParams": "x"
}
}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{
"add-requesthandler": {
"name": "/mypath",
"class": "solr.DumpRequestHandler",
"defaults": { "x": "y" ,"a": "b", "rows":10 },
"useParams": "x"
}
}' http://localhost:8983/api/collections/techproducts/config
Make a call to the new request handler to check if it is registered:
curl http://localhost:8983/solr/techproducts/mypath?omitHeader=true
And you should see the following as output:
{
"params":{
"indent": "true",
"a": "b",
"x": "y",
"rows": "10"},
"context":{
"webapp": "/solr",
"path": "/mypath",
"httpMethod": "GET"}}
To update a request handler, you should use the update-requesthandler
command:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{
"update-requesthandler": {
"name": "/mypath",
"class": "solr.DumpRequestHandler",
"defaults": {"x": "new value for X", "rows": "20"},
"useParams": "x"
}
}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{
"update-requesthandler": {
"name": "/mypath",
"class": "solr.DumpRequestHandler",
"defaults": {"x": "new value for X", "rows": "20"},
"useParams": "x"
}
}' http://localhost:8983/api/collections/techproducts/config
As a second example, we’ll create another request handler, this time adding the 'terms' component as part of the definition:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{
"add-requesthandler": {
"name": "/myterms",
"class": "solr.SearchHandler",
"defaults": {"terms": true, "distrib":false},
"components": ["terms"]
}
}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{
"add-requesthandler": {
"name": "/myterms",
"class": "solr.SearchHandler",
"defaults": {"terms": true, "distrib":false},
"components": ["terms"]
}
}' http://localhost:8983/api/collections/techproducts/config
Finally we will go ahead and remove the request handler via the delete-requesthandler
command:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{
"delete-requesthandler": "/myterms"
}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{
"delete-requesthandler": "/myterms"
}' http://localhost:8983/api/collections/techproducts/config
Commands for User-Defined Properties
Solr lets users templatize the solrconfig.xml
using the place holder format ${variable_name:default_val}
. You could set the values using system properties, for example, -Dvariable_name= my_customvalue
. The same can be achieved during runtime using these commands:
set-user-property
: Set a user-defined property. If the property has already been set, this command will overwrite the previous setting.unset-user-property
: Remove a user-defined property.
The structure of the request is similar to the structure of requests using other commands, in the format of "command":{"variable_name": "property_value"}
. You can add more than one variable at a time if necessary.
For more information about user-defined properties, see the section User defined properties in core.properties.
See also the section Creating and Updating User-Defined Properties below for examples of how to use this type of command.
Creating and Updating User-Defined Properties
This command sets a user property.
V1 API
curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' http://localhost:8983/api/collections/techproducts/config
Again, we can use the /config/overlay
endpoint to verify the changes have been made:
V1 API
curl http://localhost:8983/solr/techproducts/config/overlay?omitHeader=true
V2 API
curl http://localhost:8983/api/collections/techproducts/config/overlay?omitHeader=true
And we would expect to see output like this:
{"overlay":{
"znodeVersion":5,
"userProps":{
"variable_name": "some_value"}}
}
To unset the variable, issue a command like this:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' http://localhost:8983/api/collections/techproducts/config
What about updateRequestProcessorChain?
The Config API does not let you create or edit updateRequestProcessorChain
elements. However, it is possible to create updateProcessor
entries and use them by name to create a chain.
For example:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
{"name": "firstFld",
"class": "solr.FirstFieldValueUpdateProcessorFactory",
"fieldName": "test_s"}
}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
{"name": "firstFld",
"class": "solr.FirstFieldValueUpdateProcessorFactory",
"fieldName": "test_s"}
}' http://localhost:8983/api/collections/techproducts/config
You can use this directly in your request by adding a parameter in the updateRequestProcessorChain
for the specific update processor called processor=firstFld
.
How to Map solrconfig.xml Properties to JSON
By using this API, you will be generating JSON representations of properties defined in solrconfig.xml
. To understand how properties should be represented with the API, let’s take a look at a few examples.
Here is what a request handler looks like in solrconfig.xml
:
<requestHandler name="/query" class="solr.SearchHandler">
<lst name="defaults">
<str name="echoParams">explicit</str>
<int name="rows">10</str>
</lst>
</requestHandler>
The same request handler defined with the Config API would look like this:
{
"add-requesthandler":{
"name": "/query",
"class": "solr.SearchHandler",
"defaults":{
"echoParams": "explicit",
"rows": 10
}
}
}
The QueryElevationComponent searchComponent in solrconfig.xml
looks like this:
<searchComponent name="elevator" class="solr.QueryElevationComponent" >
<str name="queryFieldType">string</str>
<str name="config-file">elevate.xml</str>
</searchComponent>
And the same searchComponent with the Config API:
{
"add-searchcomponent":{
"name": "elevator",
"class": "solr.QueryElevationComponent",
"queryFieldType": "string",
"config-file": "elevate.xml"
}
}
Removing the searchComponent with the Config API:
{
"delete-searchcomponent": "elevator"
}
A simple highlighter looks like this in solrconfig.xml
(example has been truncated for space):
<searchComponent class="solr.HighlightComponent" name="highlight">
<highlighting>
<fragmenter name="gap"
default="true"
class="solr.highlight.GapFragmenter">
<lst name="defaults">
<int name="hl.fragsize">100</int>
</lst>
</fragmenter>
<formatter name="html"
default="true"
class="solr.highlight.HtmlFormatter">
<lst name="defaults">
<str name="hl.simple.pre"><![CDATA[<em>]]></str>
<str name="hl.simple.post"><![CDATA[</em>]]></str>
</lst>
</formatter>
<encoder name="html" class="solr.highlight.HtmlEncoder" />
...
</highlighting>
The same highlighter with the Config API:
{
"add-searchcomponent": {
"name": "highlight",
"class": "solr.HighlightComponent",
"": {
"gap": {
"default": "true",
"name": "gap",
"class": "solr.highlight.GapFragmenter",
"defaults": {
"hl.fragsize": 100
}
}
},
"html": [{
"default": "true",
"name": "html",
"class": "solr.highlight.HtmlFormatter",
"defaults": {
"hl.simple.pre": "before-",
"hl.simple.post": "-after"
}
}, {
"name": "html",
"class": "solr.highlight.HtmlEncoder"
}]
}
}
Set autoCommit properties in solrconfig.xml
:
<autoCommit>
<maxTime>15000</maxTime>
<openSearcher>false</openSearcher>
</autoCommit>
Define the same properties with the Config API:
{
"set-property": {
"updateHandler.autoCommit.maxTime":15000,
"updateHandler.autoCommit.openSearcher":false
}
}
Name Components for the Config API
The Config API always allows changing the configuration of any component by name. However, some configurations such as listener
or initParams
do not require a name in solrconfig.xml
. In order to be able to update
and delete
of the same item in configoverlay.json
, the name attribute becomes mandatory.
How the Config API Works
Every core watches the ZooKeeper directory for the configset being used with that core. In standalone mode, however, there is no watch (because ZooKeeper is not running). If there are multiple cores in the same node using the same configset, only one ZooKeeper watch is used.
For instance, if the configset 'myconf' is used by a core, the node would watch /configs/myconf
. Every write operation performed through the API would 'touch' the directory and all watchers are notified. Every core would check if the schema file, solrconfig.xml
, or configoverlay.json
has been modified by comparing the znode
versions. If any have been modified, the core is reloaded.
If params.json
is modified, the params object is just updated without a core reload (see Request Parameters API for more information about params.json
).
Empty Command
If an empty command is sent to the /config
endpoint, the watch is triggered on all cores using this configset. For example:
V1 API
curl -X POST -H 'Content-type:application/json' -d '{}' http://localhost:8983/solr/techproducts/config
V2 API
curl -X POST -H 'Content-type:application/json' -d '{}' http://localhost:8983/api/collections/techproducts/config
Directly editing any files without 'touching' the directory will not make it visible to all nodes.
It is possible for components to watch for the configset 'touch' events by registering a listener using SolrCore#registerConfListener()
.
Listening to Config Changes
Any component can register a listener using:
SolrCore#addConfListener(Runnable listener)
to get notified for configuration changes. This is not very useful if the files modified result in core reloads (i.e., configoverlay.xml
or the schema). Components can use this to reload the files they are interested in.