CoreAdmin API
The Core Admin API is primarily used under the covers by the Collections API when running a SolrCloud cluster.
SolrCloud users should not typically use the CoreAdmin API directly, but the API may be useful for users of user-managed clusters or single-node installations for core maintenance operations.
The CoreAdmin API is implemented by the CoreAdminHandler, which is a special purpose request handler that is used to manage Solr cores.
Unlike other request handlers, the CoreAdminHandler is not attached to a single core.
Instead, there is a single instance of the CoreAdminHandler in each Solr node that manages all the cores running in that node and is accessible at the /solr/admin/cores
path.
CoreAdmin actions can be executed by via HTTP requests that specify an action
request parameter, with additional action specific arguments provided as additional parameters.
All action names are uppercase, and are defined in depth in the sections below.
All of the examples in this section assume you are running the "techproducts" Solr example:
bin/solr start -DconfigSetBaseDir=./server/solr/configsets -e techproducts
We are passing in the explicit relative path for the configSetBaseDir
to enable creating new cores using the sample_techproducts_configs
configset in the examples below.
STATUS
The STATUS
action returns the status of all running Solr cores, or status for only the named core.
V1 API
http://localhost:8983/solr/admin/cores?action=STATUS&core=techproducts
V2 API
curl -X GET http://localhost:8983/api/cores/
To get the status for a single core:
curl -X GET http://localhost:8983/api/cores/techproducts
To skip returning information about the index:
curl -X GET http://localhost:8983/api/cores?indexInfo=false
STATUS Parameters
core
-
Optional
Default: none
The name of a core, as listed in the "name" attribute of a
<core>
element insolr.xml
. This parameter is required in v1, and part of the url in the v2 API. indexInfo
-
Optional
Default:
true
If
false
, information about the index will not be returned with a core STATUS request. In Solr implementations with a large number of cores (i.e., more than hundreds), retrieving the index information for each core can take a lot of time and isn’t always required.
CREATE
The CREATE
action creates a new core and registers it.
If a Solr core with the given name already exists, it will continue to handle requests while the new core is initializing. When the new core is ready, it will take new requests and the old core will be unloaded.
admin/cores?action=CREATE&name=core-name&instanceDir=path/to/dir&config=solrconfig.xml&dataDir=data
V1 API
Assuming you are using an existing configSet to create your new core:
http://localhost:8983/solr/admin/cores?action=CREATE&&name=techproducts_v2&configSet=sample_techproducts_configs
If you have already existing core files deployed on disk, and need to just create the Solr core from them then the url will look something like
http://localhost:8983/solr/admin/cores?action=CREATE&name=_core-name_&instanceDir=_path/to/dir_&config=solrconfig.xml&dataDir=data
V2 API
curl -X POST http://localhost:8983/api/cores -H 'Content-Type: application/json' -d '
{
"create": {
"name": "techproducts_v2",
"configSet": "sample_techproducts_configs"
}
}
'
Note that this command is the only one of the Core Admin API commands that does not support the core
parameter.
Instead, the name
parameter is required, as shown below.
Note that CREATE must be able to find a configuration or it will not succeed.
When you are running SolrCloud and create a new core for a collection, the configuration will be inherited from the collection.
Each collection is linked to a configName
, which is stored in ZooKeeper.
This satisfies the configuration requirement.
That said, if you’re running SolrCloud, you should NOT use the CoreAdmin API at all.
Instead, use the Collections API.
With a user-managed cluster, if you have Configsets defined, you can use the configSet
parameter as documented below.
If there are no configsets, then the instanceDir
specified in the CREATE call must already exist, and it must contain a conf
directory which in turn must contain solrconfig.xml
, your schema (usually named either managed-schema.xml
or schema.xml
), and any files referenced by those configs.
The config and schema filenames can be specified with the config
and schema
parameters, but these are expert options.
One thing you could do to avoid creating the conf
directory is use config
and schema
parameters that point at absolute paths, but this can lead to confusing configurations unless you fully understand what you are doing.
CREATE and the
core.properties fileThe |
CREATE Core Parameters
name
-
Required
Default: none
The name of the new core. Same as
name
on the<core>
element. instanceDir
-
Optional
Default: see description
The directory where files for this core should be stored. Same as
instanceDir
on the<core>
element. The default is the value specified for thename
parameter if not supplied. This directory must be insideSOLR_HOME
,SOLR_DATA_HOME
or one of the paths specified by system propertysolr.allowPaths
. config
-
Optional
Default:
solrconfig.xml
Name of the config file (i.e.,
solrconfig.xml
) relative toinstanceDir
. schema
-
Optional
Default: see description
Name of the schema file to use for the core. Please note that if you are using a "managed schema" (the default behavior) then any value for this property which does not match the effective
managedSchemaResourceName
will be read once, backed up, and converted for managed schema use. See Schema Factory Configuration for details. dataDir
-
Optional
Default:
data
Name of the data directory relative to
instanceDir
. If absolute value is used, it must be insideSOLR_HOME
,SOLR_DATA_HOME
or one of the paths specified by system propertysolr.allowPaths
. configSet
-
Optional
Default: none
Name of the configset to use for this core. For more information, see the section Configsets.
collection
-
Optional
Default: see description
The name of the collection to which this core belongs. The default is the name of the core.
collection.param=value
causes a property ofparam=value
to be set if a new collection is being created. Usecollection.configName=config-name
to point to the configuration for a new collection.While it’s possible to create a core for a non-existent collection, this approach is not supported and not recommended. Always create a collection using the Collections API before creating a core directly for it. shard
-
Optional
Default: none
The shard ID this core represents. This should only be required in special circumstances; normally you want to be auto-assigned a shard ID.
property.name=value
-
Optional
Default: none
Sets the core property name to value. See the section on defining core.properties file contents.
async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
Use collection.configName=configname
to point to the config for a new collection.
RELOAD
The RELOAD action loads a new core from the configuration of an existing, registered Solr core. While the new core is initializing, the existing one will continue to handle requests. When the new Solr core is ready, it takes over and the old core is unloaded.
V1 API
http://localhost:8983/solr/admin/cores?action=RELOAD&core=techproducts
V2 API
curl -X POST http://localhost:8983/api/cores/techproducts/reload
This is useful when you’ve made changes to a Solr core’s configuration on disk, such as adding new field definitions. Calling the RELOAD action lets you apply the new configuration without having to restart Solr.
RELOAD performs "live" reloads of SolrCore, reusing some existing objects.
Some configuration options, such as the |
RENAME
The RENAME
action changes the name of a Solr core.
V1 API
curl -X GET "http://localhost:8983/solr/admin/cores?action=RENAME&core=currentCoreName&other=newCoreName"
V2 API
curl -X POST http://localhost:8983/api/cores/currentCoreName/rename -H 'Content-Type: application/json' -d '
{
"to": "newCoreName"
}
'
RENAME Parameters
core
-
Required
Default: none
The name of an existing Solr core to rename. Specified as a query parameter if making a v1 request, or as a path parameter if using the v2 API.
other
(v1),to
(v2)-
Required
Default: none
The new name for the Solr core. Specified as a query parameter if making a v1 request, or as a property in the request body if using the v2 API. If the persistent attribute of
<solr>
istrue
, the new name will be written tosolr.xml
as thename
attribute of the<core>
attribute. async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
SWAP
SWAP
atomically swaps the names used to access two existing Solr cores.
This can be used to swap new content into production.
The prior core remains available and can be swapped back, if necessary.
Each core will be known by the name of the other, after the swap.
V1 API
`admin/cores?action=SWAP&core=_core-name_&other=_other-core-name_`
V2 API
curl -X POST http://localhost:8983/api/cores/_core-name_/swap -H 'Content-Type: application/json' -d '
{
"with": "_other-core-name_"
}
'
Do not use |
UNLOAD
The UNLOAD
action removes a core from Solr.
Active requests will continue to be processed, but no new requests will be sent to the named core.
If a core is registered under more than one name, only the given name is removed.
V1 API
http://localhost:8983/solr/admin/cores?actionUNLOAD&core=techproducts
V2 API
curl -X POST http://localhost:8983/api/cores/techproducts/unload -H 'Content-Type: application/json' -d '
{}
'
The UNLOAD
action requires a parameter (core
) identifying the core to be removed.
If the persistent attribute of <solr>
is set to true
, the <core>
element with this name
attribute will be removed from solr.xml
.
Unloading all cores in a SolrCloud collection causes the removal of that collection’s metadata from ZooKeeper. |
UNLOAD Parameters
core
-
Required
Default: none
The name of a core to be removed. This parameter is required.
deleteIndex
-
Optional
Default:
false
If
true
, will remove the index when unloading the core. deleteDataDir
-
Optional
Default:
false
If
true
, removes thedata
directory and all sub-directories. deleteInstanceDir
-
Optional
Default:
false
If
true
, removes everything related to the core, including the index directory, configuration files and other related files. async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
MERGEINDEXES
The MERGEINDEXES
action merges one or more indexes to another index.
The indexes must have completed commits, and should be locked against writes until the merge is complete or the resulting merged index may become corrupted.
The target core index must already exist and have a compatible schema with the one or more indexes that will be merged to it.
Another commit on the target core should also be performed after the merge is complete.
V1 API
curl -X GET "http://localhost:8983/solr/admin/cores?action=MERGEINDEXES&core=targetCoreName&indexDir=path/to/core1/data/index&indexDir=path/to/core2/data/index"
V2 API
curl -X POST http://localhost:8983/api/cores/targetCoreName/merge-indices -H 'Content-Type: application/json' -d '
{
"indexDirs": ["path/to/core1/data/index","path/to/core2/data/index"]
}
'
In this example, we use the indexDir
parameter (indexDirs
in the v2 API) to define the index locations of the source cores.
The core
parameter defines the target index.
A benefit of this approach is that we can merge any Lucene-based index that may not be associated with a Solr core.
Alternatively, we can instead use a srcCore
parameter (srcCores
in the v2 API), as in the example below:
V1 API
curl -X GET "http://localhost:8983/solr/admin/cores?action=mergeindexes&core=targetCoreName&srcCore=core1&srcCore=core2"
V2 API
curl -X POST http://localhost:8983/api/cores/targetCoreName/merge-indices -H 'Content-Type: application/json' -d '
{
"srcCores": ["core1","core2"]
}
'
This approach allows us to define cores that may not have an index path that is on the same physical server as the target core. However, we can only use Solr cores as the source indexes. Another benefit of this approach is that we don’t have as high a risk for corruption if writes occur in parallel with the source index.
We can make this call run asynchronously by specifying the async
parameter and passing a request ID.
This ID can then be used to check the status of the already submitted task using the REQUESTSTATUS API.
MERGEINDEXES Parameters
core
-
Required
Default: none
The name of the target core/index.
indexDir
-
Optional
Default: none
Multi-valued, directories that would be merged.
srcCore
-
Optional
Default: none
Multi-valued, source cores that would be merged.
async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
SPLIT
The SPLIT
action splits an index into two or more indexes.
The index being split can continue to handle requests.
The split pieces can be placed into a specified directory on the server’s filesystem or it can be merged into running Solr cores.
The SPLIT
action supports five parameters, which are described in the table below.
SPLIT Parameters
core
-
Required
Default: none
The name of the core to be split.
path
-
Optional
Default: none
Multi-valued, the directory path in which a piece of the index will be written. Either this parameter or
targetCore
must be specified. If this is specified, thetargetCore
parameter may not be used. targetCore
-
Optional
Default: none
Multi-valued, the target Solr core to which a piece of the index will be merged. Either this parameter or
path
must be specified. If this is specified, thepath
parameter may not be used. ranges
-
Optional
Default: none
A comma-separated list of hash ranges in hexadecimal format. If this parameter is used,
split.key
should not be. See the SPLIT Examples below for an example of how this parameter can be used. split.key
-
Optional
Default: none
The key to be used for splitting the index. If this parameter is used,
ranges
should not be. See the SPLIT Examples below for an example of how this parameter can be used. async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
SPLIT Examples
The core
index will be split into as many pieces as the number of path
or targetCore
parameters.
Usage with two targetCore parameters:
http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2
Here the core
index will be split into two pieces and merged into the two targetCore
indexes.
Usage with two path parameters:
http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&path=/path/to/index/1&path=/path/to/index/2
The core
index will be split into two pieces and written into the two directory paths specified.
Usage with the split.key parameter:
http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&split.key=A!
Here all documents having the same route key as the split.key
i.e., A!
will be split from the core
index and written to the targetCore
.
Usage with ranges parameter:
http://localhost:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2&targetCore=core3&ranges=0-1f4,1f5-3e8,3e9-5dc
This example uses the ranges
parameter with hash ranges 0-500, 501-1000 and 1001-1500 specified in hexadecimal.
Here the index will be split into three pieces with each targetCore receiving documents matching the hash ranges specified i.e., core1 will get documents with hash range 0-500, core2 will receive documents with hash range 501-1000 and finally, core3 will receive documents with hash range 1001-1500.
At least one hash range must be specified.
Please note that using a single hash range equal to a route key’s hash range is NOT equivalent to using the split.key
parameter because multiple route keys can hash to the same range.
The targetCore
must already exist and must have a compatible schema with the core
index.
A commit is automatically called on the core
index before it is split.
This command is used as part of SolrCloud’s SPLITSHARD command but it can be used for cores in user-managed clusters as well.
When used against a core in a user-managed cluster without split.key
parameter, this action will split the source index and distribute its documents alternately so that each split piece contains an equal number of documents.
If the split.key
parameter is specified then only documents having the same route key will be split from the source index.
REQUESTSTATUS
Request the status of an already submitted asynchronous CoreAdmin API call.
V1 API
http://localhost:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=id
V2 API
curl -X GET http://localhost:8983/api/node/commands/id
Core REQUESTSTATUS Parameters
The REQUESTSTATUS command has only one parameter.
requestid
-
Required
Default: none
The user defined request-id for the asynchronous request.
The call below will return the status of an already submitted asynchronous CoreAdmin call.
http://localhost:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=1
REQUESTRECOVERY
The REQUESTRECOVERY
action manually asks a core to recover by synching with the leader.
This should be considered an "expert" level command and should be used in situations where the node (SorlCloud replica) is unable to become active automatically.
admin/cores?action=REQUESTRECOVERY&core=core-name