Collections API

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 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: Create, list, reload and delete collections; set collection properties; migrate documents to another collection; rebalance leaders; backup and restore collections.

Collection Aliasing: Create, list or delete collection aliases; set alias properties.

Shard Management: Create and delete a shard; split a shard into two or more additional shards; force a shard leader.

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

http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=collection1&shard=shard1&async=1000&wt=xml

Output

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">99</int>
  </lst>
  <str name="requestid">1000</str>
</response>

REQUESTSTATUS: Request Status of an Async Call

Request the status and response of an already submitted 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

http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1000&wt=xml

Output

<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

http://localhost:8983/solr/admin/collections?action=REQUESTSTATUS&requestid=1004&wt=xml

Output

<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: Delete Status

Deletes the stored response of an already failed or completed 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

http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=foo&wt=xml

Output

<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

http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=bar&wt=xml

Output

<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

http://localhost:8983/solr/admin/collections?action=DELETESTATUS&flush=true&wt=xml

Output

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