1.3.9. /db/_shards

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

    • –

      • 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

    • – Invalid database name

    • 401 Unauthorized – Read privilege required

    • – Bad Content-Type value

    • – Internal server error or timeout

Request:

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 621
  4. Content-Type: application/json
  5. Date: Fri, 18 Jan 2019 19:55:14 GMT
  6. Server: CouchDB/2.4.0 (Erlang OTP/19)
  8. {
  9.   "shards": {
  10.     "00000000-1fffffff": [
  11.       "couchdb@node1.example.com",
  12.       "couchdb@node2.example.com",
  13.       "couchdb@node3.example.com"
  14.     ],
  15.     "20000000-3fffffff": [
  16.       "couchdb@node1.example.com",
  17.       "couchdb@node2.example.com",
  18.       "couchdb@node3.example.com"
  19.     ],
  20.     "40000000-5fffffff": [
  21.       "couchdb@node1.example.com",
  22.       "couchdb@node2.example.com",
  23.       "couchdb@node3.example.com"
  24.     ],
  25.     "60000000-7fffffff": [
  26.       "couchdb@node2.example.com",
  27.       "couchdb@node3.example.com"
  28.     ],
  29.     "80000000-9fffffff": [
  30.       "couchdb@node1.example.com",
  31.       "couchdb@node2.example.com",
  32.       "couchdb@node3.example.com"
  33.     ],
  34.     "a0000000-bfffffff": [
  35.       "couchdb@node1.example.com",
  36.       "couchdb@node2.example.com",
  37.       "couchdb@node3.example.com"
  38.     ],
  39.     "c0000000-dfffffff": [
  40.       "couchdb@node1.example.com",
  41.       "couchdb@node2.example.com",
  42.       "couchdb@node3.example.com"
  43.     ],
  44.     "e0000000-ffffffff": [
  45.       "couchdb@node1.example.com",
  46.       "couchdb@node2.example.com",
  47.       "couchdb@node3.example.com"
  48.     ]
  49.   }
  50. }

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.

    • db – Database name

    • docid – Document ID

    Request Headers

    • –

      • 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

Request:

Response:

  1. HTTP/1.1 200 OK
  3. Content-Type: application/json
  4. Date: Fri, 18 Jan 2019 20:26:33 GMT
  5. Server: CouchDB/2.3.0-9d4cb03c2 (Erlang OTP/19)
  7. {
  8.   "range": "e0000000-ffffffff",
  9.   "nodes": [
  10.     "node1@127.0.0.1",
  11.     "node2@127.0.0.1",
  12.     "node3@127.0.0.1"
  13.   ]
  14. }

1.3.11. /db/_sync_shards

New in version 2.3.1.

POST /{db}/_sync_shards

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

  • Parameters

    • db – Database name

    Request Headers

    • –

      • 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

    • – Request accepted

    • 400 Bad Request – Invalid database name

    • – CouchDB Server Administrator privileges required

    • 404 Not Found – Database not found

    • – Internal server error or timeout

Request:

Response:

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

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