Apache Solr Documentation

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

Older Versions of this Guide (PDF)

Ref Guide Topics

Meta-Documentation

*** As of June 2017, the latest Solr Ref Guide is located at https://lucene.apache.org/solr/guide ***

Please note comments on these pages have now been disabled for all users.

Skip to end of metadata
Go to start of metadata

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 it may be useful for users of single-node or master/slave Solr installations for core maintenance operations.

The CoreAdmin API is implemented by the CoreAdminHandler, which is a special purpose SolrRequestHandler that is used to manage Solr cores. Unlike normal SolrRequestHandlers, the CoreAdminHandler is not attached to a single core. Instead, it 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.

2

STATUS

The STATUS action returns the status of all running Solr cores, or status for only the named core.

http://localhost:8983/solr/admin/cores?action=STATUS&core=core0

Input

Query Parameters

Parameter

Type

Required

Default

Description

core

stringNo 

The name of a core, as listed in the "name" attribute of a <core> element in solr.xml.

indexInfo

booleanNotrue

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.

http://localhost:8983/solr/admin/cores?action=CREATE&name=coreX&instanceDir=path/to/dir&config=config_file_name.xml&dataDir=data

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.

CREATE must be able to find a configuration!

Your CREATE call 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 the ZooKeeper database. This satisfies the config requirement. There is something to note, though – if you're running SolrCloud, you should NOT be using the CoreAdmin API at all. Use the Collections API.

When you are not running SolrCloud, if you have Config Sets defined, you can use the configSet parameter as documented below. If there are no config sets, 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 and your schema, which is usually named either managed-schema or schema.xml, as well as any files referenced by those configs. The config and schema filenames could 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 file

The core.properties file is built as part of the CREATE command.  If you create a core.properties file yourself in a core directory and then try to use CREATE to add that core to Solr, you will get an error telling you that another core is already defined there.  The core.properties file must NOT exist before calling the CoreAdmin API with the CREATE command.

 

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

name

stringYesN/A

The name of the new core. Same as "name" on the <core> element.

instanceDir

stringNowhatever is specified for "name" parameter

The directory where files for this SolrCore should be stored. Same as instanceDir on the <core> element.

config

stringNo 

Name of the config file (i.e., solrconfig.xml) relative to instanceDir.

schema

stringNo 

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 Definition in SolrConfig for details.

dataDir

stringNo 

Name of the data directory relative to instanceDir.

configSetstringNo Name of the configset to use for this core. For more information, see the section Config Sets.

collection

stringNo 

The name of the collection to which this core belongs. The default is the name of the core. collection.<param>=<value> causes a property of <param>=<value> to be set if a new collection is being created. Use collection.configName=<configname> to point to the configuration for a new collection.

shard

stringNo 

The shard id this core represents. Normally you want to be auto-assigned a shard id.

property.name=valuestringNo Sets the core property name to value. See the section on defining core.properties file contents.
asyncstringNo Request ID to track this action which will be processed asynchronously

Use collection.configName=<configname> to point to the config for a new collection.

Example

http://localhost:8983/solr/admin/cores?action=CREATE&name=my_core&collection=my_collection&shard=shard2

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.

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.

http://localhost:8983/solr/admin/cores?action=RELOAD&core=core0

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 the Web container.

RELOAD performs "live" reloads of SolrCore, reusing some existing objects. Some configuration options, such as the dataDir location and IndexWriter-related settings in solrconfig.xml can not be changed and made active with a simple RELOAD action.

Input

Query Parameters

Parameter

Type

Required

Default

Description

core

stringYes N/A

The name of the core, as listed in the "name" attribute of a <core> element in solr.xml.

RENAME

The RENAME action changes the name of a Solr core.

http://localhost:8983/solr/admin/cores?action=RENAME&core=core0&other=core5

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

core

stringYes 

The name of the Solr core to be renamed.

other

stringYes 

The new name for the Solr core. If the persistent attribute of <solr> is true, the new name will be written to solr.xml as the name attribute of the <core> attribute.

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

http://localhost:8983/solr/admin/cores?action=SWAP&core=core1&other=core0

Do not use SWAP with a SolrCloud node. It is not supported and can result in the core being unusable.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

core

stringYes 

The name of one of the cores to be swapped.

other

stringYes 

The name of one of the cores to be swapped.

asyncstringNo Request ID to track this action which will be processed asynchronously

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.

http://localhost:8983/solr/admin/cores?action=UNLOAD&core=core0

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.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

corestringYes 

The name of one of the cores to be removed.

deleteIndex

booleanNofalse

If true, will remove the index when unloading the core.

deleteDataDirbooleanNofalseIf true, removes the data directory and all sub-directories.
deleteInstanceDirbooleanNofalseIf true, removes everything related to the core, including the index directory, configuration files and other related files.
asyncstringNo 

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.

http://localhost:8983/solr/admin/cores?action=MERGEINDEXES&core=new_core_name&indexDir=/solr_home/core1/data/index&indexDir=/solr_home/core2/data/index

In this example, we use the indexDir parameter 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, as in this example:

http://localhost:8983/solr/admin/cores?action=mergeindexes&core=new_core_name&srcCore=core1&srcCore=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.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

core

stringYes 

The name of the target core/index.

indexDirstring  Multi-valued, directories that would be merged.
srcCorestring  Multi-valued, source cores that would be merged.
asyncstring  

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.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

core

stringYes 

The name of the core to be split.

path

string  

Multi-valued, the directory path in which a piece of the index will be written.

targetCore

string  

Multi-valued, the target Solr core to which a piece of the index will be merged

ranges

stringNo 

A comma-separated list of hash ranges in hexadecimal format

split.key

stringNo 

The key to be used for splitting the index

asyncstringNo Request ID to track this action which will be processed asynchronously

Either path or targetCore parameter must be specified but not both. The ranges and split.key parameters are optional and only one of the two should be specified, if at all required.

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 of 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 the SPLITSHARD command but it can be used for non-cloud Solr cores as well. When used against a non-cloud core 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.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

requestid

stringYes 

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.

The REQUESTRECOVERY action supports one parameter, which is described in the table below.

Input

Query Parameters

Parameter

TypeRequiredDefault

Description

core

stringYes 

The name of the core to re-sync.

Examples

http://localhost:8981/solr/admin/cores?action=REQUESTRECOVERY&core=gettingstarted_shard1_replica1

The core to specify can be found by expanding the appropriate ZooKeeper node via the admin UI.

 

  • No labels

15 Comments

  1. Since this is pretty much a copy from the old page, I don't have anything to add except some formatting notes:

    • You don't need the h1 header at the top - the page name says it already.
    • At the bottom of the content, add the {scrollbar} macro for consistency with other pages - it adds page navigation (prev, next, etc.).
  2. There seems to be a formatting issue - Clicking on the action names "CREATE" etc. does not take you to the actual action.

    1. fixed - just killed the manually created list and replaced it with the TOC so it will always be correct.

  3. The CREATE command is missing configSet parameter. It's mentioned in the next section, but is worth showing it here for those not sure of exact terminology or usage.

    1. Added it, thanks Alexandre.

  4. I've taken a pass at bringing it in sync with how Collections API are doc'ed. Will take another one later tonight and clean it up.

    1. I'm done with my changes. It'd be nice to add some examples with sample output etc though.

  5. The query parameters table for the CREATE action lists the "datadir" parameter. It must be "dataDir" (camel-case)

  6. I'd like to request improvements to the docs for the CREATE command. We discussed it on solr-user and I was encouraged to post a comment here. (Unfortunately the archive browser doesn't allow direct links to an individual thread: https://mail-archives.apache.org/mod_mbox/lucene-solr-user/201503.mbox/browser, grr...)

    The CREATE command is not an API! The whole purpose of creating an API is to abstract away details that the caller doesn't need to know.

    But this API requires internal knowledge of (and access to) Solr's internals: the caller must know the internal file structure of Solr, set up that file structure with proper permissions, and then call the CREATE API. So why have an API at all?

    This API should be marked as "Private" so that people like me don't waste hours trying to write an HTTP client that creates a new core over HTTP.

    Also, `instanceDir` is marked as required, but if I call the CREATE API without it, I don't get an error. If it's not actually required, then it shouldn't be marked as required.

    The instanceDir argument is ambiguous:

    The directory where files for this SolrCore should be stored. Same as instanceDir on the <core> element.

    So should I pass "foo" or "/var/solr/data/foo"? Also, telling me it's similar to <core> does nothing for me. What is <core> anyway? If you linked to something that explains what <core> is, then maybe I could answer my own question about what this path means.

    The configSet argument is also ambiguous.

     

    Name of the configset to use for this core. For more information, see the section Config Sets.

     

    I tried using configSet in non-cloud mode and it doesn't work. It looks inside the instanceDir but all of the default config sets are stored in $SOLR_INSTALL/solr/server/...something...

    1. The CoreAdmin API was originally built as a way to avoid hand-editing solr.xml and restarting Solr, which is how you would have accomplished those changes in the dustbin of history.  Restarting Solr is a highly disruptive operation, avoiding that was the primary goal.  Either way, with the API or without, you would need to set up the core before you could actually add it to Solr.

      Between that initial purpose and now, Solr has evolved enormously ... solr.xml no longer contains the core definitions, SolrCloud became a reality, config sets were added as a non-cloud option, and so on.  FYI - the configsets functionality is VERY new, not all the implementation and documentation bugs are worked out.

      The CoreAdmin API has fulfilled its purpose admirably for all that time, so it has not seen much change other than a few extra parameters that got bolted on for things like SolrCloud.  You're not the first person to be thoroughly confused by the fact that the CREATE action only creates the SolrCore object within Solr, not the on-disk representation.  Perhaps a better name for that action would be ADD.

      On recommended and default values for parameters supplied to the CoreAdmin API:  The instanceDir parameter is relative to the solr home.  The dataDir parameter is relative to instanceDir and defaults to "data".  The default value for instanceDir is the core name.  You can specify absolute paths for these if you want, but relative paths are far more flexible.

      Before we built the bin/solr script, the solr home defaulted to "solr", relative to the current working directory of the process that started the servlet container that's running Solr.  The bin/solr script actually sets the solr home explicitly.  It is fairly common for users to set the solr home as an absolute path, with everything else relative to that location.

       

  7. Is this still true?

    To use the CoreAdminHandler, make sure that the adminPath attribute is defined on the <cores> element; otherwise you will not be able to make HTTP requests to perform Solr core administration.

    According to the Format of solr.xml page, there is no longer a <cores> element.

    1. nope - removed along with some other fixes – thanks for catching this.

  8. From the documentation of the CREATE action:

    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.

    This seems to be wrong? At least in the old version 4.10.4, an error is thrown instead (but the reference guide for 4.10 contained this sentence as well) and the Wiki at https://wiki.apache.org/solr/CoreAdmin#CREATE also says that Solr 4.3+ throws an error when trying to create an existing core. If I understand correctly, RELOAD should be used instead to create a new core with different configuration.

  9. There are more operations in the source code of CoreAdminOperation that are not listed here. Is that intentional?

    E.g. REQUESTRECOVERY isn't documented here, but is implemented, and is referenced in https://support.lucidworks.com/hc/en-us/articles/203959903-Bringing-up-downed-Solr-servers-that-don-t-want-to-come-up

     

    1. Hmm, good catch. I'll fix this up momentarily.