Replica Management Commands | Apache Solr Reference Guide 8.11

A replica is a physical copy of a shard.

ADDREPLICA: Add Replica

Add one or more replicas to a shard in a collection. The node name can be specified if the replica is to be created in a specific node. Otherwise, a set of nodes can be specified and the most suitable ones among them will be chosen to create the replica(s).

/admin/collections?action=ADDREPLICA&collection=collection&shard=shard&node=nodeName

ADDREPLICA Parameters

collection

The name of the collection where the replica should be created. This parameter is required.

shard

The name of the shard to which replica is to be added.

If shard is not specified, then _route_ must be.

_route_

If the exact shard name is not known, users may pass the _route_ value and the system would identify the name of the shard.

Ignored if the shard parameter is also specified.

node

The name of the node where the replica should be created (optional).

createNodeSet

A comma-separated list of nodes among which the best ones will be chosen to place the replicas (optional)

The format is a comma-separated list of node_names, such as localhost:8983_solr,localhost:8984_solr,localhost:8985_solr.

If neither node nor createNodeSet are specified then the best node(s) from among all the live nodes in the cluster are chosen.

instanceDir

The instanceDir for the core that will be created.

dataDir

The directory in which the core should be created.

type

The type of replica to create. These possible values are allowed:

nrt: The NRT type maintains a transaction log and updates its index locally. This is the default and the most commonly used.
tlog: The TLOG type maintains a transaction log but only updates its index via replication.
pull: The PULL type does not maintain a transaction log and only updates its index via replication. This type is not eligible to become a leader.
See the section Types of Replicas for more information about replica type options.

nrtReplicas

The number of nrt replicas that should be created (optional, defaults to 1 if type is nrt otherwise 0).

tlogReplicas

The number of tlog replicas that should be created (optional, defaults to 1 if type is tlog otherwise 0).

pullReplicas

The number of pull replicas that should be created (optional, defaults to 1 if type is pull otherwise 0).

property.name=value

Set core property name to value. See Defining core.properties for details about supported properties and values.

The entries in each core.properties file are vital for Solr to function correctly. Overriding entries can result in unusable collections. Altering these entries by specifying property.name=value is an expert-level option and should only be used if you have a thorough understanding of the consequences.

waitForFinalState: If true, the request will complete only when all affected replicas become active. The default is false, which means that the API will return the status of the single action, which may be before the new replica is online and active.
async: Request ID to track this action which will be processed asynchronously

Examples using ADDREPLICA

Input

Create a replica for the "test" collection on the node "192.167.1.2:8983_solr".

http://localhost:8983/solr/admin/collections?action=ADDREPLICA&collection=test2&shard=shard2&node=192.167.1.2:8983_solr&wt=xml

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">3764</int>
  </lst>
  <lst name="success">
    <lst>
      <lst name="responseHeader">
        <int name="status">0</int>
        <int name="QTime">3450</int>
      </lst>
      <str name="core">test2_shard2_replica4</str>
    </lst>
  </lst>
</response>

Input

Create a replica for the "gettingstarted" collection with one PULL replica and one TLOG replica.

http://localhost:8983/solr/admin/collections?action=addreplica&collection=gettingstarted&shard=shard1&tlogReplicas=1&pullReplicas=1

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 784
    },
    "success": {
        "127.0.1.1:7574_solr": {
            "responseHeader": {
                "status": 0,
                "QTime": 257
            },
            "core": "gettingstarted_shard1_replica_p11"
        },
        "127.0.1.1:8983_solr": {
            "responseHeader": {
                "status": 0,
                "QTime": 295
            },
            "core": "gettingstarted_shard1_replica_t10"
        }
    }
}

MOVEREPLICA: Move a Replica to a New Node

This command moves a replica from one node to another node by executing ADDREPLICA on the destination and then DELETEREPLICA on the source. If this command is interrupted or times out before the ADDREPLICA operation produces a replica in an active state, the DELETEREPLICA will not occur. Timeouts do not cancel the ADDREPLICA, and will result in extra shards. In case of shared filesystems the dataDir will be reused.

If this command is used on a collection where more than one replica from the same shard exists on the same node, and the shard and sourceNode parameters match more than one replica, the replica selected is not deterministic (currently it’s random).

MOVERREPLICA does not check the maxShardsPerNode setting, and may produce a collection that is in violation of the maxShardsPerNode.

MOVEREPLICA Parameters

collection: The name of the collection. This parameter is required.
targetNode: The name of the destination node. This parameter is required.
sourceNode: The name of the node that contains the replica to move. This parameter is required unless replica is specified. If replica is specified this parameter is ignored.
shard: The name of the shard for which a replica should be moved. This parameter is required unless replica is specified. If replica is specified, this parameter is ignored.
replica: The name of the replica to move. This parameter is required unless shard and sourceNode are specified, however this parameter has precedence over those two parameters.
timeout: The number of seconds to wait for the replica to be live in the new location before deleting the replica in the old location. Defaults to 600 seconds. Deletion will not occur and creation will not be rolled back in the event of a timeout, potentially leaving an extra replica. Presently, this parameter is ignored if the replica is an hdfs replica.
inPlaceMove: For replicas that use shared filesystems allow 'in-place' move that reuses shared data. Defaults to true, but is ignored if the replica does not have the property shared_storage with a value of true
async: Request ID to track this action which will be processed asynchronously.

Examples using MOVEREPLICA

V2 API Input

POST /api/c/test

{
  "move-replica":{
    "replica":"core_node6",
    "targetNode": "localhost:8983_solr"
  }
}

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 3668
    },
    "success": "MOVEREPLICA action completed successfully, moved replica=test_shard1_replica_n5 at node=localhost:8982_solr to replica=test_shard1_replica_n7 at node=localhost:8983_solr"
}

V1 API

Input

http://localhost:8983/solr/admin/collections?action=MOVEREPLICA&collection=test&targetNode=localhost:8983_solr&replica=core_node6

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 3668
    },
    "success": "MOVEREPLICA action completed successfully, moved replica=test_shard1_replica_n5 at node=localhost:8982_solr to replica=test_shard1_replica_n7 at node=localhost:8983_solr"
}

DELETEREPLICA: Delete a Replica

Deletes a named replica from the specified collection and shard.

If the corresponding core is up and running the core is unloaded, the entry is removed from the clusterstate, and (by default) delete the instanceDir and dataDir. If the node/core is down, the entry is taken off the clusterstate and if the core comes up later it is automatically unregistered.

/admin/collections?action=DELETEREPLICA&collection=collection&shard=shard&replica=replica

DELETEREPLICA Parameters

collection

The name of the collection. This parameter is required.

shard

The name of the shard that includes the replica to be removed. This parameter is required.

replica

The name of the replica to remove.

If count is used instead, this parameter is not required. Otherwise, this parameter must be supplied.

count

The number of replicas to remove. If the requested number exceeds the number of replicas, no replicas will be deleted. If there is only one replica, it will not be removed.

If replica is used instead, this parameter is not required. Otherwise, this parameter must be supplied.

deleteInstanceDir

By default Solr will delete the entire instanceDir of the replica that is deleted. Set this to false to prevent the instance directory from being deleted.

deleteDataDir

By default Solr will delete the dataDir of the replica that is deleted. Set this to false to prevent the data directory from being deleted.

deleteIndex

By default Solr will delete the index of the replica that is deleted. Set this to false to prevent the index directory from being deleted.

onlyIfDown

When set to true, no action will be taken if the replica is active. Default false.

async

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

Examples using DELETEREPLICA

Input

http://localhost:8983/solr/admin/collections?action=DELETEREPLICA&collection=test2&shard=shard2&replica=core_node3&wt=xml

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">110</int>
  </lst>
</response>

ADDREPLICAPROP: Add Replica Property

Assign an arbitrary property to a particular replica and give it the value specified. If the property already exists, it will be overwritten with the new value.

/admin/collections?action=ADDREPLICAPROP&collection=collectionName&shard=shardName&replica=replicaName&property=propertyName&property.value=value

ADDREPLICAPROP Parameters

collection

The name of the collection the replica belongs to. This parameter is required.

shard

The name of the shard the replica belongs to. This parameter is required.

replica

The replica, e.g., core_node1. This parameter is required.

property

The name of the property to add. This property is required.

This will have the literal property. prepended to distinguish it from system-maintained properties. So these two forms are equivalent:

property=special

and

property=property.special

property.value

The value to assign to the property. This parameter is required.

shardUnique

If true, then setting this property in one replica will remove the property from all other replicas in that shard. The default is false.

There is one pre-defined property preferredLeader for which shardUnique is forced to true and an error returned if shardUnique is explicitly set to false.

PreferredLeader is a boolean property. Any value assigned that is not equal (case insensitive) to true will be interpreted as false for preferredLeader.

ADDREPLICAPROP Response

The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.

Examples using ADDREPLICAPROP

Input

This command would set the "preferredLeader" property (property.preferredLeader) to "true" on "core_node1", and remove that property from any other replica in the shard.

http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&collection=collection1&replica=core_node1&property=preferredLeader&property.value=true&wt=xml

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">46</int>
  </lst>
</response>

Input

This pair of commands will set the "testprop" property (property.testprop) to 'value1' and 'value2' respectively for two nodes in the same shard.

http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&collection=collection1&replica=core_node1&property=testprop&property.value=value1

http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&collection=collection1&replica=core_node3&property=property.testprop&property.value=value2

Input

This pair of commands would result in "core_node_3" having the "testprop" property (property.testprop) value set because the second command specifies shardUnique=true, which would cause the property to be removed from "core_node_1".

http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&collection=collection1&replica=core_node1&property=testprop&property.value=value1

http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&shard=shard1&collection=collection1&replica=core_node3&property=testprop&property.value=value2&shardUnique=true

DELETEREPLICAPROP: Delete Replica Property

Deletes an arbitrary property from a particular replica.

/admin/collections?action=DELETEREPLICAPROP&collection=collectionName&shard=shardName&replica=replicaName&property=propertyName

DELETEREPLICAPROP Parameters

collection

The name of the collection the replica belongs to. This parameter is required.

shard

The name of the shard the replica belongs to. This parameter is required.

replica

The replica, e.g., core_node1. This parameter is required.

property

The property to add. This will have the literal property. prepended to distinguish it from system-maintained properties. So these two forms are equivalent:

property=special

and

property=property.special

DELETEREPLICAPROP Response

The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.

Examples using DELETEREPLICAPROP

Input

This command would delete the preferredLeader (property.preferredLeader) from core_node1.

http://localhost:8983/solr/admin/collections?action=DELETEREPLICAPROP&shard=shard1&collection=collection1&replica=core_node1&property=preferredLeader&wt=xml

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">9</int>
  </lst>
</response>