1.3.9. /db/_shards

New in version 2.0.

GET /{db}/_shards

The response will contain a list of database shards. Each shard will have its internal database range, and the nodes on which replicas of those shards are stored.

• Parameters

  • db – Database name

  Request Headers

  • Accept –

    • application/json

    • text/plain

  Response Headers

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  Response JSON Object

  • shards (object) – Mapping of shard ranges to individual shard replicas on each node in the cluster

  Status Codes

  • 200 OK – Request completed successfully

  • 400 Bad Request – Invalid database name

  • 401 Unauthorized – Read privilege required

  • 415 Unsupported Media Type – Bad Content-Type value

  • 500 Internal Server Error – Internal server error or timeout

Request:

GET /db/_shards HTTP/1.1
Accept: */*
Host: localhost:5984

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 621
Content-Type: application/json
Date: Fri, 18 Jan 2019 19:55:14 GMT
Server: CouchDB/2.4.0 (Erlang OTP/19)
{
  "shards": {
    "00000000-1fffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "20000000-3fffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "40000000-5fffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "60000000-7fffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "80000000-9fffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "a0000000-bfffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "c0000000-dfffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ],
    "e0000000-ffffffff": [
      "couchdb@node1.example.com",
      "couchdb@node2.example.com",
      "couchdb@node3.example.com"
    ]
  }
}

1.3.10. /db/_shards/doc

GET /{db}/_shards/{docid}

Returns information about the specific shard into which a given document has been stored, along with information about the nodes on which that shard has a replica.

• Parameters

  • db – Database name

  • docid – Document ID

  Request Headers

  • Accept –

    • application/json

    • text/plain

  Response Headers

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  Response JSON Object

  • range (string) – The shard range in which the document is stored

  • nodes (array) – List of nodes serving a replica of the shard

  Status Codes

  • 200 OK – Request completed successfully

  • 401 Unauthorized – Read privilege required

  • 404 Not Found – Database or document not found

  • 500 Internal Server Error – Internal server error or timeout

Request:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 94
Content-Type: application/json
Date: Fri, 18 Jan 2019 20:08:07 GMT
Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 94
Content-Type: application/json
Date: Fri, 18 Jan 2019 20:26:33 GMT
Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)
{
  "range": "e0000000-ffffffff",
  "nodes": [
    "node1@127.0.0.1",
    "node2@127.0.0.1",
    "node3@127.0.0.1"
  ]
}

1.3.11. /db/_sync_shards

New in version 2.3.1.

POST /{db}/_sync_shards

For the given database, force-starts internal shard synchronization for all replicas of all database shards.

This is typically only used when performing cluster maintenance, such as moving a shard.

• Parameters

  • db – Database name

  Request Headers

  • Accept –

    • application/json

    • text/plain

  Response Headers

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  Response JSON Object

  • ok (boolean) – Operation status. Available in case of success

  • error (string) – Error type. Available if response code is 4xx

  • reason (string) – Error description. Available if response code is 4xx

  Status Codes

  • 202 Accepted – Request accepted

  • 400 Bad Request – Invalid database name

  • 401 Unauthorized – CouchDB Server Administrator privileges required

  • 404 Not Found – Database not found

  • 500 Internal Server Error – Internal server error or timeout

Request:

POST /db/_sync_shards HTTP/1.1
Host: localhost:5984
Accept: */*

Response:

HTTP/1.1 202 Accepted
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Fri, 18 Jan 2019 20:19:23 GMT
Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)
X-Couch-Request-ID: 14f0b8d252
X-CouchDB-Body-Time: 0
{
    "ok": true
}

Note

Admins may want to bump their [mem3] sync_concurrency value to a larger figure for the duration of the shards sync.