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

Alias Management: Create, list or delete collection aliases; set alias properties.

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

Replica Management Commands: 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. The ID provided can be any string so long as it doesn’t have a / in it.

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

V1 API

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

V2 API

curl -X POST http://localhost:8983/api/collections/collection1/shards -H 'Content-Type: application/json' -d '
  {
    "split": {
      "shard": "shard1",
      "async": "1000"
    }
  }
'

Output

{
  "responseHeader":{
    "status":0,
    "QTime":115},
  "requestid":"1000"}

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.

V1 API

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

V2 API

curl -X GET http://localhost:8983/api/cluster/command-status/1000

REQUESTSTATUS Parameters

requestid

Required

Default: none

The user defined request ID for the request. This can be used to track the status of the submitted asynchronous task.

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.

V1 API

http://localhost:8983/solr/admin/collections?action=DELETESTATUS&requestid=1000

V2 API

Delete a single request response:

curl -X DELETE http://localhost:8983/api/cluster/command-status/1000

Flush out all stored completed and failed async request responses:

curl -X DELETE http://localhost:8983/api/cluster/command-status?flush=true

DELETESTATUS Parameters

requestid

Optional

Default: none

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

flush

Optional

Default: none

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>