= Collections API
:page-children: cluster-node-management, collection-management, collection-aliasing, shard-management, replica-management
:page-toc: false
// 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 SolrCloud cluster includes a number of components. The Collections API is provided to allow you to control your cluster, including the collections, shards, replicas, backups, leader election, and other operations needs.

Because this API has a large number of commands and options, we've grouped the commands into the following sub-sections:

*<<cluster-node-management.adoc#cluster-node-management,Cluster and Node Management>>*: Define properties for the entire cluster; check the status of a cluster; remove replicas from a node; utilize a newly added node; add or remove roles for a node.

*<<collection-management.adoc#collection-management,Collection Management>>*: Create, list, reload and delete collections; set collection properties; migrate documents to another collection; rebalance leaders; backup and restore collections.

*<<collection-aliasing.adoc#collection-aliasing,Collection Aliasing>>*: Create, list or delete collection aliases; set alias properties.

*<<shard-management.adoc#shard-management,Shard Management>>*: Create and delete a shard; split a shard into two or more additional shards; force a shard leader.

*<<replica-management.adoc#replica-management,Replica Management>>*: Add or delete a replica; set replica properties; move a replica to a different node.

== Asynchronous Calls

Since some collection API calls can be long running tasks (such as SPLITSHARD), you can optionally have the calls run asynchronously. Specifying `async=<request-id>` enables you to make an asynchronous call, the status of which can be requested using the <<requeststatus,REQUESTSTATUS>> call at any time.

As of now, REQUESTSTATUS does not automatically clean up the tracking data structures, meaning the status of completed or failed tasks stays stored in ZooKeeper unless cleared manually. DELETESTATUS can be used to clear the stored statuses. However, there is a limit of 10,000 on the number of async call responses stored in a cluster.

=== Examples of Async Requests

*Input*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=collection1&shard=shard1&async=1000&wt=xml
----

*Output*

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


[[requeststatus]]
== REQUESTSTATUS: Request Status of an Async Call

Request the status and response of an already submitted <<Asynchronous Calls,Asynchronous Collection API>> (below) call. This call is also used to clear up the stored statuses.

`/admin/collections?action=REQUESTSTATUS&requestid=_request-id_`

=== REQUESTSTATUS Parameters

`requestid`::
The user defined request ID for the request. This can be used to track the status of the submitted asynchronous task. This parameter is required.

=== Examples using REQUESTSTATUS

*Input: Valid Request ID*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">1</int>
  </lst>
  <lst name="status">
    <str name="state">completed</str>
    <str name="msg">found 1000 in completed tasks</str>
  </lst>
</response>
----

*Input: Invalid Request ID*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1004&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">1</int>
  </lst>
  <lst name="status">
    <str name="state">notfound</str>
    <str name="msg">Did not find taskid [1004] in any tasks queue</str>
  </lst>
</response>
----

[[deletestatus]]
== DELETESTATUS: Delete Status

Deletes the stored response of an already failed or completed <<Asynchronous Calls,Asynchronous Collection API>> call.

`/admin/collections?action=DELETESTATUS&requestid=_request-id_`

=== DELETESTATUS Parameters

`requestid`::
The request ID of the asynchronous call whose stored response should be cleared.

`flush`::
Set to `true` to clear all stored completed and failed async request responses.

=== Examples using DELETESTATUS

*Input: Valid Request ID*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=foo&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">1</int>
  </lst>
  <str name="status">successfully removed stored response for [foo]</str>
</response>
----

*Input: Invalid Request ID*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=bar&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">1</int>
  </lst>
  <str name="status">[bar] not found in stored responses</str>
</response>
----

*Input: Clear All Stored Statuses*

[source,text]
----
http://localhost:8983/solr/admin/collections?action=DELETESTATUS&flush=true&wt=xml
----

*Output*

[source,xml]
----
<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">1</int>
  </lst>
  <str name="status"> successfully cleared stored collection api responses </str>
</response>
----
