Replica Management Commands
A replica is a physical copy of a shard. Replicas enhance fail over by providing additional copies of the data and enhance scalability by providing additional capacity for searching.
All of the examples in this section assume you are running the "techproducts" Solr example:
bin/solr start -c -e techproducts
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).
V1 API
Input
http://localhost:8983/solr/admin/collections?action=ADDREPLICA&collection=techproducts&shard=shard1&node=localhost:8983_solr
Output
{
"responseHeader":{
"status":0,
"QTime":482},
"success":{
"localhost:8983_solr":{
"responseHeader":{
"status":0,
"QTime":396},
"core":"techproducts_shard1_replica_n3"}}}
V2 API Input
curl -X POST http://localhost:8983/api/collections/techproducts/shards/shard1/replicas -H 'Content-Type: application/json' -d '
{
"node":"localhost:8983_solr"
}
'
Output
{
"responseHeader":{
"status":0,
"QTime":820},
"success":{
"localhost:8983_solr":{
"responseHeader":{
"status":0,
"QTime":473},
"core":"techproducts_shard1_replica_n11"}}}
ADDREPLICA Parameters
collection
-
Required
Default: none
The name of the collection where the replica should be created.
shard
-
Optional
Default: none
The name of the shard to which replica is to be added.
If
shard
is not specified, then_route_
must be. _route_
(v1),route
(v2)-
Optional
Default: none
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
-
Optional
Default: none
The name of the node where the replica should be created.
createNodeSet
(v1),nodeSet
(v2)-
Optional
Default: none
Placement candidates for the newly created replica(s).
Provided as a comma-separated list of node names in v1 requests, such as
localhost:8983_solr,localhost:8984_solr,localhost:8985_solr
. In v2 requests,nodeSet
expects the values as a true list, such as["localhost:8983_solr", "localhost:8984_solr", "localhost:8985_solr"]
.
If neither node nor createNodeSet /nodeSet are specified then the best node(s) from among all the live nodes in the cluster are chosen.
|
instanceDir
-
Optional
Default: none
The instanceDir for the core that will be created.
dataDir
-
Optional
Default: none
The directory in which the core should be created.
type
-
Optional
Default:
nrt
The type of replica to create. These possible values are allowed:
-
nrt
: The NRT type maintains a transaction log and updates its index locally. -
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
-
Optional
Default: see description
The number of
nrt
replicas that should be created. Defaults to1
iftype
isnrt
otherwise0
. tlogReplicas
-
Optional
Default: see description
The number of
tlog
replicas that should be created. Defaults to1
iftype
istlog
otherwise0
. pullReplicas
-
Optional
Default: see description
The number of
pull
replicas that should be created. Defaults to1
iftype
ispull
otherwise0
. property.name=value
-
Optional
Default: none
Name/value pairs to use as additional properties in the created core. See Core Discovery 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 |
waitForFinalState
-
Optional
Default:
false
If
true
, the request will complete only when all affected replicas become active. Iffalse
, the API will return the status of the single action, which may be before the new replica is online and active. async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
Additional Examples using ADDREPLICA
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).
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"
}
V2 API Input
curl -X POST http://localhost:8983/api/collections/techproducts -H 'Content-Type: application/json' -d '
{
"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"
}
MOVEREPLICA Parameters
collection
-
Required
Default: none
The name of the collection.
targetNode
-
Required
Default: none
The name of the destination node.
sourceNode
-
Optional
Default: none
The name of the node that contains the replica to move. This parameter is required unless
replica
is specified. Ifreplica
is specified this parameter is ignored. shard
-
Optional
Default: none
The name of the shard for which a replica should be moved. This parameter is required unless
replica
is specified. Ifreplica
is specified, this parameter is ignored. replica
-
Optional
Default: none
The name of the replica to move. This parameter is required unless
shard
andsourceNode
are specified, however this parameter has precedence over those two parameters. timeout
-
Optional
Default:
600
secondsThe number of seconds to wait for the replica to be live in the new location before deleting the replica in the old location. 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
-
Optional
Default:
true
For replicas that use shared filesystems, allow an "in-place" move that reuses shared data. Defaults to
true
, but is ignored if the replica does not have the propertyshared_storage
with a value oftrue
. async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
DELETEREPLICA: Delete a Replica
Allows deletion of one or more replicas. The replicas to be deleted can be specified in multiple ways:
-
A single, specific replica can be deleted by if the associated collection, shard and replica name are all provided.
-
Multiple replicas can be deleted from a specific shard if the associated collection and shard names are provided, along with a
count
of the replicas to delete. -
Multiple replicas can be deleted from all shards in a collection if the associated collection name is provided, along with a
count
of the replicas to delete.
When deleting multiple replicas, Solr chooses replicas which are active, up to date, and not currently the leader.
For each replica being deleted, if the corresponding core is up and running the core is unloaded, the entry is removed from the clusterstate, and (by default) the instanceDir and dataDir are deleted. If the core underlying the replica is down, the entry is taken off the clusterstate and if the core comes up later it is automatically unregistered.
V1 API
http://localhost:8983/solr/admin/collections?action=DELETEREPLICA&collection=techproducts&shard=shard1&replica=core_node2
V2 API
The v2 API has three distinct endpoints for replica-deletion, depending on how the replicas are specified.
To delete a replica by name:
curl -X DELETE http://localhost:8983/api/collections/techproducts/shards/shard1/replicas/core_node2
To delete a specified number of (unnamed) replicas from a single shard:
curl -X DELETE "http://localhost:8983/api/collections/techproducts/shards/shard1/replicas?count=3"
To delete a specified number of (unnamed) replicas from all shards:
curl -X PUT -H "Content-type: application/json" "http://localhost:8983/api/collections/techproducts/scale" -d '
{
"count": 3
}
'
DELETEREPLICA Parameters
collection
-
Required
Default: none
The name of the collection. Provided as a query parameter or a path parameter in v1 and v2 requests, respectively.
shard
-
Required
Default: none
The name of the shard that includes the replica to be removed. Provided as a query parameter or a path parameter in v1 and v2 requests, respectively.
replica
-
Optional
Default: none
The name of the replica to remove. Provided as a query parameter or a path parameter in v1 and v2 requests, respectively.
If
count
is used instead, this parameter is not required. Otherwise, this parameter must be supplied. count
-
Optional
Default: none
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
-
Optional
Default:
true
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
-
Optional
Default:
true
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
-
Optional
Default:
true
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
-
Optional
Default:
false
When set to
true
, no action will be taken if the replica is active. followAliases
-
Optional
Default: false
A flag that allows treating the collection parameter as an alias for the actual collection name to be resolved.
async
-
Optional
Default: none
Request ID to track this action which will be processed asynchronously.
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.
V1 API
Input
http://localhost:8983/solr/admin/collections?action=ADDREPLICAPROP&collection=techproducts&shard=shard1&replica=core_node2&property=preferredLeader&property.value=true
V2 API Input
curl -X PUT http://localhost:8983/api/collections/techproducts/shards/shard1/replicas/core_node2/properties/preferredLeader -H 'Content-Type: application/json' -d '
{
"value": "true"
}
'
ADDREPLICAPROP Parameters
collection
-
Required
Default: none
The name of the collection the replica belongs to.
shard
-
Required
Default: none
The name of the shard the replica belongs to.
replica
-
Required
Default: none
The replica, e.g.,
core_node1
. property
-
Required
Default: none
The name of 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
property.value
-
Required
Default: none
The value to assign to the property.
shardUnique
-
Optional
Default:
false
If
true
, then setting this property in one replica will remove the property from all other replicas in that shard. The default isfalse
.There is one pre-defined property
preferredLeader
for whichshardUnique
is forced totrue
and an error returned ifshardUnique
is explicitly set tofalse
.preferredLeader
is a boolean property. Any value assigned that is not equal (case insensitive) totrue
will be interpreted asfalse
forpreferredLeader
.
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.
Additional Examples using ADDREPLICAPROP
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.
V1 API
Input
http://localhost:8983/solr/admin/collections?action=DELETEREPLICAPROP&collection=techproducts&shard=shard1&replica=core_node2&property=preferredLeader
V2 API Input
curl -X DELETE http://localhost:8983/api/collections/techproducts/shards/shard1/replicas/core_node2/properties/preferredLeader
DELETEREPLICAPROP Parameters
collection
-
Required
Default: none
The name of the collection the replica belongs to.
shard
-
Required
Default: none
The name of the shard the replica belongs to.
replica
-
Required
Default: none
The replica, e.g.,
core_node1
. property
-
Required
Default: none
The property to delete.