<commit_before>= Replica Management Commands
:toclevels: 1
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

A replica is a physical copy of a shard.

[[addreplica]]
== 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).

The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replica(s) but only when an Autoscaling preferences or policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.

`/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`.

NOTE: 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 <<shards-and-indexing-data-in-solrcloud.adoc#types-of-replicas,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.adoc#defining-core-properties,Defining core.properties>> for details about supported properties and values.

`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 <<collections-api.adoc#asynchronous-calls,processed asynchronously>>

=== Examples using ADDREPLICA

*Input*

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

[source,text]
----
http://localhost:8983/solr/admin/collections?action=ADDREPLICA&collection=test2&shard=shard2&node=172.16.31.10:8983_solr&wt=xml
----

*Output*

[source,xml]
----
<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.

[source,text]
----
http://localhost:8983/solr/admin/collections?action=addreplica&collection=gettingstarted&shard=shard1&tlogReplicas=1&pullReplicas=1
----

*Output*

[source,json]
----
{
    "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]]
== MOVEREPLICA: Move a Replica to a New Node

This command moves a replica from one node to a new node. In case of shared filesystems the `dataDir` will be reused.

The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the replica to be moved but only when an Autoscaling policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.

`/admin/collections?action=MOVEREPLICA&collection=collection&shard=shard&replica=replica&sourceNode=nodeName&targetNode=nodeName`

=== MOVEREPLICA Parameters

`collection`::
The name of the collection. This parameter is required.

`shard`::
The name of the shard for which a replica should be moved. Either this parameter or replica is required. If replica is specified, this parameter is ignored.

`replica`::
The name of the replica to move. Either this parameter or shard is required.

`sourceNode`::
The name of the node that contains the replica. This parameter is required.

`targetNode`::
The name of the destination node. This parameter is required.

`async`::
Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

[[deletereplica]]
== 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`::<commit_msg>SOLR-13169 Improve docs for MOVEREPLICA - improve examples<commit_after>= Replica Management Commands
:toclevels: 1
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

A replica is a physical copy of a shard.

[[addreplica]]
== 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).

The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replica(s) but only when an Autoscaling preferences or policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.

`/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`.

NOTE: 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 <<shards-and-indexing-data-in-solrcloud.adoc#types-of-replicas,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.adoc#defining-core-properties,Defining core.properties>> for details about supported properties and values.

`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 <<collections-api.adoc#asynchronous-calls,processed asynchronously>>

=== Examples using ADDREPLICA

*Input*

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

[source,text]
----
http://localhost:8983/solr/admin/collections?action=ADDREPLICA&collection=test2&shard=shard2&node=172.16.31.10:8983_solr&wt=xml
----

*Output*

[source,xml]
----
<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.

[source,text]
----
http://localhost:8983/solr/admin/collections?action=addreplica&collection=gettingstarted&shard=shard1&tlogReplicas=1&pullReplicas=1
----

*Output*

[source,json]
----
{
    "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]]
== MOVEREPLICA: Move a Replica to a New Node

This command moves a replica from one node to a new node. In case of shared filesystems the `dataDir` will be reused.

The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the replica to be moved but only when an Autoscaling policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.

=== MOVEREPLICA Parameters

`collection`::
The name of the collection. This parameter is required.

`shard`::
The name of the shard for which a replica should be moved. Either this parameter or replica is required. If replica is specified, this parameter is ignored.

`replica`::
The name of the replica to move. Either this parameter or shard is required.

`sourceNode`::
The name of the node that contains the replica. This parameter is required.

`targetNode`::
The name of the destination node. This parameter is required.

`async`::
Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

=== Examples using MOVEREPLICA

[.dynamic-tabs]
--

[example.tab-pane#v2moveReplica]
====
[.tab-label]*V2 API*
*Input*

`POST /api/c/test2`

[source,json]
----
{
  "move-replica":{
    "replica":"core_node6",
    "sourceNode":"localhost:8982_sol",
    "targetNode": "localhost:8983_solr"
  }
}
----
*Output*

[source,json]
----
{
    "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"
}
----
====

[example.tab-pane#v1createAlias]
====
[.tab-label]*V1 API*

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=MOVEREPLICA&collection=test&targetNode=localhost:8983_solr&fromNode=localhost:8982_solr&replica=core_node6
----

*Output*

[source,json]
----
{
    "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]]
== 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`::
{'fraction_non_alphanumeric': 0.09712755598831548, 'fraction_numerical': 0.01777020447906524, 'mean_word_length': 4.076614148903306, 'pattern_counts': {'":': 40, '<': 67, '<?xml version=': 0, '>': 67, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3946969', 'n_tokens_mistral': 5126, 'n_tokens_neox': 4846, 'n_words': 1916}