Quick Review: What are Multiple Cores?

Multiple cores let you have a single Solr instance with separate configurations and indexes, with their own config and schema for very different applications, but still have the convenience of unified administration. Individual indexes are still fairly isolated, but you can manage them as a single application, create new indexes on the fly by spinning up new SolrCores, and even make one SolrCore replace another SolrCore without ever restarting your Servlet Container. See MultipleIndexes

Core Administration

<!> Solr1.3

Since Solr1.3, SolrCore can optionally be managed at runtime. Additionally, Solr allows multiple SolrCore instances to run within a single web-app. The cores can be dynamically managed via the CoreAdminHandler. For alternative ways to manage multiple indicies, see MultipleIndexes.

Contents

  1. Quick Review: What are Multiple Cores?
  2. Core Administration
  3. Configuration
    1. solr
    2. cores
    3. property
    4. solr.xml Permissions
  4. Example
  5. CoreAdminHandler
    1. STATUS
    2. CREATE
    3. RELOAD
    4. RENAME
    5. ALIAS
    6. SWAP
    7. UNLOAD
    8. LOAD
  6. Known Issues

Configuration

To enable support for dynamic SolrCore administration, place a file named solr.xml in the solr.home directory. Here is an example solr.xml file: 

<solr persistent="true" sharedLib="lib">
 <cores adminPath="/admin/cores">
  <core name="core0" instanceDir="core0" />
  <core name="core1" instanceDir="core1" />
 </cores>
</solr>

You can also specify properties in solr.xml which can be used in the solrconfig.xml and schema.xml files. 

<solr persistent="true" sharedLib="lib">
 <property name="snapshooter" value="/home/solr-user/solr/bin/snapshooter.sh" />
 <cores adminPath="/admin/cores">
  <core name="core0" instanceDir="core0">
    <property name="dataDir" value="/data/core0" />
  </core>
  <core name="core1" instanceDir="core1" />
 </cores>
</solr>

The properties can be container scope (i.e. specified after <solr> but outside of a <core> element) in which case it is automatically inherited by each core. Therefore, they can be used in any of the cores' configuration files.

The properties can also be defined in a core's scope (inside the <core> element) in which case they can be used only in that core's scope. If a property by that name already exists in the container scope then it will be overridden.

Besides them, a few properties are automatically added in the core scope. They are:

Such properties can be used inside solrconfig.xml and schema.xml files by specifying an expression with optionally, a default value. 

// Without a default value
${snapshooter}
// With a default value
${snapshooter:./solr/bin/snapshooter.sh}

The above expression will evaluate to the value specified in solr.xml for the property name "solr.snapshooter". If no value is defined in solr.xml, it will check if a system property by that name exists otherwise it will use the specified default value. If no default value is specified, a runtime exception will be thrown and the core may fail to startup.

solr

The <solr> tag accepts two attributes:

cores

The <cores> tag accepts the following attributes: 

import org.apache.solr.handler.admin.CoreAdminHandler ;

class MyAdminHandler extends CoreAdminHandler { 
    
  /**
   * @return true, if the changes need to be persisted by the CoreContainer. (use only if solr.xml would be changed because of this action. )
   *         false, otherwise.   (Use this if unsure or having a read-only access to the CoreContainer like collecting statistics)
   * 
   */ 
  protected boolean handleCustomAction(SolrQueryRequest req, SolrQueryResponse rsp) {
     CoreContainer container = super.getCoreContainer(); 
     SolrCore mycore1 = container.getCore("core1");
     SolrCore mycore2 = container.getCore("core2");
     SolrParams params = req.getParams();
     String a = params.get( CoreAdminParams.ACTION );
     if (a.toLowerCase().equals("mystat"))  {
         // TODO: populate 'rsp' as necessary. 
      } 
  } 
}

class MyAdminHandler extends CoreAdminHandler { 
    //Available for override , but unnecessary except for the rare case. 
     protected boolean handleAliasAction(SolrQueryRequest req, SolrQueryResponse rsp) ; 
     protected boolean handleCreateAction(SolrQueryRequest req, SolrQueryResponse rsp) ; 
     // etc. 
}

The <core> tag accepts the following attributes:

property

The <property> tag accepts two attributes:

solr.xml Permissions

It is important to note that persistent=true functionality 'replaces' solr.xml it does not edit it. This means that the directory the file is in needs to allow the web server to replace the file. If the permissions are set incorrectly it will give 500 errors and throw IOExceptions. Additionally, all comments are wiped from the file on save.

Example

Solr ships with an example running two cores together setup. To run this configuration, start jetty in the example/ directory using: 

java -Dsolr.solr.home=multicore -jar start.jar

This will start solr running two cores: core0, and core1. To access each core, try:

To access the admin pages for each core visit:

CoreAdminHandler

The CoreAdminHandler is a special SolrRequestHandler that is used to manage existing cores. Unlike normal SolrRequestHandlers, the CoreAdminHandler is not attached to a core, it is configured in solr.xml. A single CoreAdminHandler exists for each web-app

To enable dynamic core configuration, make sure the adminPath attribute is set in solr.xml. If this attribute is absent, the CoreAdminHandler will not be available.

STATUS

Get the status for a given core or all cores if no core is specified:

CREATE

Creates a new core and register it. If persistence is enabled (persist=true), the configuration for this new core will be saved in 'solr.xml'. If a core with the same name exists, while the "new" created core is initalizing, the "old" one will continue to accept requests. Once it has finished, all new request will go to the "new" core, and the "old" core will be unloaded.

Note that config ,schema & dataDir parameters are optional.

RELOAD

Load a new core from the same configuration as an existing registered core. While the "new" core is initalizing, the "old" one will continue to accept requests. Once it has finished, all new request will go to the "new" core, and the "old" core will be unloaded.

This can be useful when (backwards compatible) changes have been made to your solrconfig.xml or schema.xml files (ie: new <field> declarations, changed default params for a <requestHandler>, etc...) and you want to start using them without stopping and restarting your whole Servlet Container.

RENAME

Change the names used to access a core. The example below changes the name of the core from "core0" to "core5".

ALIAS

(Experimental) Adds an additional name for a core. The example below allows access to the same core via the names "core0" and "corefoo".

SWAP

Atomically swaps the names used to access two existing cores. This can be useful for replacing a "live" core with an "ondeck" core, and keeping the old "live" core running in case you decide to roll-back.

UNLOAD

Removes a core from solr. Existing requests will continue to be processed, but no new requests can be sent to this core by the name. If a core is registered under more than one name, only that specific mapping is removed.

LOAD

/!\ not implemented yet!

This will load a new core from an existing configuration (will be implemented when cores can be described with a lazy-load flag).

?persist=true will save the changes to solr.xml

Known Issues

Lucene's BooleanQuery maxClauseCount is a static variable, making it a single value across the entire JVM. Whichever Solr core initializes last will win the setting of the solrconfig.xml's maxBooleanClauses value. Workaround, set maxBooleanClauses to the greatest value desired in *all* cores.

CoreAdmin (last edited 2009-11-14 12:00:09 by ErikHatcher)