= Cluster and Node Managment Commands
:page-toclevels: 1
:page-tocclass: right
// 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 cluster is a set of Solr nodes operating in coordination with each other.

These API commands work with a SolrCloud cluster at the entire cluster level, or on individual nodes.

[[clusterstatus]]
== CLUSTERSTATUS: Cluster Status

Fetch the cluster status including collections, shards, replicas, configuration name as well as collection aliases and cluster properties.

`/admin/collections?action=CLUSTERSTATUS`

=== CLUSTERSTATUS Parameters

`collection`::
The collection or alias name for which information is requested. If omitted, information on all collections in the cluster will be returned. If an alias is supplied, information on the collections in the alias will be returned.

`shard`::
The shard(s) for which information is requested. Multiple shard names can be specified as a comma-separated list.

`\_route_`::
This can be used if you need the details of the shard where a particular document belongs to and you don't know which shard it falls under.

=== CLUSTERSTATUS Response

The response will include the status of the request and the status of the cluster.

=== Examples using CLUSTERSTATUS

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS
----

*Output*

[source,json]
----
{
  "responseHeader":{
    "status":0,
    "QTime":333},
  "cluster":{
    "collections":{
      "collection1":{
        "shards":{
          "shard1":{
            "range":"80000000-ffffffff",
            "state":"active",
            "replicas":{
              "core_node1":{
                "state":"active",
                "core":"collection1",
                "node_name":"127.0.1.1:8983_solr",
                "base_url":"http://127.0.1.1:8983/solr",
                "leader":"true"},
              "core_node3":{
                "state":"active",
                "core":"collection1",
                "node_name":"127.0.1.1:8900_solr",
                "base_url":"http://127.0.1.1:8900/solr"}}},
          "shard2":{
            "range":"0-7fffffff",
            "state":"active",
            "replicas":{
              "core_node2":{
                "state":"active",
                "core":"collection1",
                "node_name":"127.0.1.1:7574_solr",
                "base_url":"http://127.0.1.1:7574/solr",
                "leader":"true"},
              "core_node4":{
                "state":"active",
                "core":"collection1",
                "node_name":"127.0.1.1:7500_solr",
                "base_url":"http://127.0.1.1:7500/solr"}}}},
        "maxShardsPerNode":"1",
        "router":{"name":"compositeId"},
        "replicationFactor":"1",
        "znodeVersion": 11,
        "autoCreated":"true",
        "configName" : "my_config",
        "aliases":["both_collections"]
      },
      "collection2":{
        "..."
      }
    },
    "aliases":{ "both_collections":"collection1,collection2" },
    "roles":{
      "overseer":[
        "127.0.1.1:8983_solr",
        "127.0.1.1:7574_solr"]
    },
    "live_nodes":[
      "127.0.1.1:7574_solr",
      "127.0.1.1:7500_solr",
      "127.0.1.1:8983_solr",
      "127.0.1.1:8900_solr"]
  }
}
----

[[clusterprop]]
== CLUSTERPROP: Cluster Properties

Add, edit or delete a cluster-wide property.

`/admin/collections?action=CLUSTERPROP&name=_propertyName_&val=_propertyValue_`

=== CLUSTERPROP Parameters

`name`::
The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode` and `urlScheme`. Other properties can be set
(for example, if you need them for custom plugins) but they must begin with the prefix `ext.`. Unknown properties that don't begin with `ext.` will be rejected.

`val`::
The value of the property. If the value is empty or null, the property is unset.

=== CLUSTERPROP Response

The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

=== Examples using CLUSTERPROP

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
</response>
----

=== Setting Cluster-Wide Defaults

It is possible to set cluster-wide default values for certain attributes of a collection, using the `defaults` parameter.

*Set/update default values*
[source,bash]
----
curl -X POST -H 'Content-type:application/json' --data-binary '
{
  "set-obj-property": {
    "defaults" : {
      "collection": {
        "numShards": 2,
        "nrtReplicas": 1,
        "tlogReplicas": 1,
        "pullReplicas": 1
      }
    }
  }
}' http://localhost:8983/api/cluster
----

*Unset the only value of `nrtReplicas`*
[source,bash]
----
curl -X POST -H 'Content-type:application/json' --data-binary '
{
  "set-obj-property": {
    "defaults" : {
      "collection": {
        "nrtReplicas": null
      }
    }
  }
}' http://localhost:8983/api/cluster
----

*Unset all values in `defaults`*
[source,bash]
----
curl -X POST -H 'Content-type:application/json' --data-binary '
{ "set-obj-property" : {
    "defaults" : null
}' http://localhost:8983/api/cluster
----

NOTE: Until Solr 7.5, cluster properties supported a `collectionDefaults` key which is now deprecated and
replaced with `defaults`. Using the `collectionDefaults` parameter in Solr 7.4 or 7.5 will continue to work
 but the format of the properties will automatically be converted to the new nested structure.
Support for the "collectionDefaults" key will be removed in Solr 9.

[[balanceshardunique]]
== BALANCESHARDUNIQUE: Balance a Property Across Nodes

`/admin/collections?action=BALANCESHARDUNIQUE&collection=_collectionName_&property=_propertyName_`

Insures that a particular property is distributed evenly amongst the physical nodes that make up a collection. If the property already exists on a replica, every effort is made to leave it there. If the property is *not* on any replica on a shard, one is chosen and the property is added.

=== BALANCESHARDUNIQUE Parameters

`collection`::
The name of the collection to balance the property in. This parameter is required.

`property`::
The property to balance. The literal `property.` is prepended to this property if not specified explicitly. This parameter is required.

`onlyactivenodes`::
Defaults to `true`. Normally, the property is instantiated on active nodes only. If this parameter is specified as `false`, then inactive nodes are also included for distribution.

`shardUnique`::
Something of a safety valve. There is one pre-defined property (`preferredLeader`) that defaults this value to `true`. For all other properties that are balanced, this must be set to `true` or an error message will be returned.

=== BALANCESHARDUNIQUE 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 BALANCESHARDUNIQUE

*Input*

Either of these commands would put the "preferredLeader" property on one replica in every shard in the "collection1" collection.

[source,text]
----
http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=preferredLeader&wt=xml

http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=property.preferredLeader&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">9</int>
  </lst>
</response>
----

Examining the clusterstate after issuing this call should show exactly one replica in each shard that has this property.

[[utilizenode]]
== UTILIZENODE: Utilize a New Node

This command can be used to move some replicas from the existing nodes to either a new node or a less loaded node to reduce the load on the existing node.

This uses your autoscaling policies and preferences to identify which replica needs to be moved. It tries to fix any policy violations first and then it tries to move some load off of the most loaded nodes according to the preferences.

`/admin/collections?action=UTILIZENODE&node=nodeName`

=== UTILIZENODE Parameters

`node`:: The name of the node that needs to be utilized. This parameter is required.

[[replacenode]]
== REPLACENODE: Move All Replicas in a Node to Another

This command recreates replicas in one node (the source) to another node(s) (the target). After each replica is copied, the replicas in the source node are deleted.

For source replicas that are also shard leaders the operation will wait for the number of seconds set with the `timeout` parameter to make sure there's an active replica that can become a leader (either an existing replica becoming a leader or the new replica completing recovery and becoming a leader).

The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replicas 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=REPLACENODE&sourceNode=_source-node_&targetNode=_target-node_`

=== REPLACENODE Parameters

`sourceNode`::
The source node from which the replicas need to be copied from. This parameter is required.

`targetNode`::
The target node where replicas will be copied. If this parameter is not provided, Solr will identify nodes automatically based on policies or number of cores in each node.

`parallel`::
If this flag is set to `true`, all replicas are created in separate threads. Keep in mind that this can lead to very high network and disk I/O if the replicas have very large indices. The default is `false`.

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

`timeout`::
Time in seconds to wait until new replicas are created, and until leader replicas are fully recovered. The default is `300`, or 5 minutes.

[IMPORTANT]
====
This operation does not hold necessary locks on the replicas that belong to on the source node. So don't perform other collection operations in this period.
====

[[deletenode]]
== DELETENODE: Delete Replicas in a Node

Deletes all replicas of all collections in that node. Please note that the node itself will remain as a live node after this operation.

`/admin/collections?action=DELETENODE&node=nodeName`

=== DELETENODE Parameters

`node`::
The node to be removed. This parameter is required.

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

[[addrole]]
== ADDROLE: Add a Role

`/admin/collections?action=ADDROLE&role=_roleName_&node=_nodeName_`

Assigns a role to a given node in the cluster. The only supported role is `overseer`.

Use this command to dedicate a particular node as Overseer. Invoke it multiple times to add more nodes. This is useful in large clusters where an Overseer is likely to get overloaded. If available, one among the list of nodes which are assigned the 'overseer' role would become the overseer. The system would assign the role to any other node if none of the designated nodes are up and running.

=== ADDROLE Parameters

`role`::
The name of the role. The only supported role as of now is `overseer`. This parameter is required.

`node`::
The name of the node that will be assigned the role. It is possible to assign a role even before that node is started. This parameter is started.

=== ADDROLE Response

The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

=== Examples using ADDROLE

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=ADDROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
</response>
----

[[removerole]]
== REMOVEROLE: Remove Role

Remove an assigned role. This API is used to undo the roles assigned using ADDROLE operation

`/admin/collections?action=REMOVEROLE&role=_roleName_&node=_nodeName_`

=== REMOVEROLE Parameters

`role`::
The name of the role. The only supported role as of now is `overseer`. This parameter is required.

`node`::
The name of the node where the role should be removed.


=== REMOVEROLE Response

The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

=== Examples using REMOVEROLE

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=REMOVEROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">0</int>
  </lst>
</response>
----

[[overseerstatus]]
== OVERSEERSTATUS: Overseer Status and Statistics

Returns the current status of the overseer, performance statistics of various overseer APIs, and the last 10 failures per operation type.

`/admin/collections?action=OVERSEERSTATUS`

=== Examples using OVERSEERSTATUS

*Input:*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=OVERSEERSTATUS
----

[source,json]
----
{
  "responseHeader":{
    "status":0,
    "QTime":33},
  "leader":"127.0.1.1:8983_solr",
  "overseer_queue_size":0,
  "overseer_work_queue_size":0,
  "overseer_collection_queue_size":2,
  "overseer_operations":[
    "createcollection",{
      "requests":2,
      "errors":0,
      "avgRequestsPerSecond":0.7467088842794136,
      "5minRateRequestsPerSecond":7.525069023276674,
      "15minRateRequestsPerSecond":10.271274280947182,
      "avgTimePerRequest":0.5050685,
      "medianRequestTime":0.5050685,
      "75thPcRequestTime":0.519016,
      "95thPcRequestTime":0.519016,
      "99thPcRequestTime":0.519016,
      "999thPcRequestTime":0.519016},
    "removeshard",{
      "..."
  }],
  "collection_operations":[
    "splitshard",{
      "requests":1,
      "errors":1,
      "recent_failures":[{
          "request":{
            "operation":"splitshard",
            "shard":"shard2",
            "collection":"example1"},
          "response":[
            "Operation splitshard caused exception:","org.apache.solr.common.SolrException:org.apache.solr.common.SolrException: No shard with the specified name exists: shard2",
            "exception",{
              "msg":"No shard with the specified name exists: shard2",
              "rspCode":400}]}],
      "avgRequestsPerSecond":0.8198143044809885,
      "5minRateRequestsPerSecond":8.043840552427673,
      "15minRateRequestsPerSecond":10.502079828515368,
      "avgTimePerRequest":2952.7164175,
      "medianRequestTime":2952.7164175000003,
      "75thPcRequestTime":5904.384052,
      "95thPcRequestTime":5904.384052,
      "99thPcRequestTime":5904.384052,
      "999thPcRequestTime":5904.384052},
    "..."
  ],
  "overseer_queue":[
    "..."
  ],
  "..."
 }
----

[[migratestateformat]]
== MIGRATESTATEFORMAT: Migrate Cluster State

A expert level utility API to move a collection from shared `clusterstate.json` ZooKeeper node (created with `stateFormat=1`, the default in all Solr releases prior to 5.0) to the per-collection `state.json` stored in ZooKeeper (created with `stateFormat=2`, the current default) seamlessly without any application down-time.

`/admin/collections?action=MIGRATESTATEFORMAT&collection=<collection_name>`

=== MIGRATESTATEFORMAT Parameters

`collection`::
The name of the collection to be migrated from `clusterstate.json` to its own `state.json` ZooKeeper node. This parameter is required.

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

This API is useful in migrating any collections created prior to Solr 5.0 to the more scalable cluster state format now used by default. If a collection was created in any Solr 5.x version or higher, then executing this command is not necessary.
