1.6. Partitioned Databases

Partitioned databases allow for data colocation in a cluster, which provides significant performance improvements for queries constrained to a single partition.

See the guide for getting started with partitioned databases

1.6.1. /db/_partition/partition

GET /{db}/_partition/{partition}

This endpoint returns information describing the provided partition. It includes document and deleted document counts along with external and active data sizes.

  • Status Codes

    • 200 OK – Request completed successfully

Request:

  1. GET /db/_partition/sensor-260 HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 119
  4. Content-Type: application/json
  5. Date: Thu, 24 Jan 2019 17:19:59 GMT
  6. Server: CouchDB/2.3.0-a1e11cea9 (Erlang OTP/21)
  7. {
  8. "db_name": "my_new_db",
  9. "doc_count": 1,
  10. "doc_del_count": 0,
  11. "partition": "sensor-260",
  12. "sizes": {
  13. "active": 244,
  14. "external": 347
  15. }
  16. }

1.6.2. /db/_partition/partition/_all_docs

GET /{db}/_partition/{partition}/_all_docs

  • Parameters

    • db – Database name

    • partition – Partition name

This endpoint is a convenience endpoint for automatically setting bounds on the provided partition range. Similar results can be had by using the global /db/_all_docs endpoint with appropriately configured values for start_key and end_key.

Refer to the view endpoint documentation for a complete description of the available query parameters and the format of the returned data.

Request:

  1. GET /db/_partition/sensor-260/_all_docs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Sat, 10 Aug 2013 16:22:56 GMT
  5. ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  8. {
  9. "offset": 0,
  10. "rows": [
  11. {
  12. "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  13. "key": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  14. "value": {
  15. "rev": "1-05ed6f7abf84250e213fcb847387f6f5"
  16. }
  17. }
  18. ],
  19. "total_rows": 1
  20. }

1.6.3. /db/_partition/partition/_design/design-doc/_view/view-name

GET /{db}/_partition/{partition}/_design/{ddoc}/_view/{view}

  • Parameters

    • db – Database name

    • partition – Partition name

    • ddoc – Design document id

    • view – View name

This endpoint is responsible for executing a partitioned query. The returned view result will only contain rows with the specified partition name.

Refer to the view endpoint documentation for a complete description of the available query parameters and the format of the returned data.

  1. GET /db/_partition/sensor-260/_design/sensor-readings/_view/by_sensor HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Type: application/json
  4. Date: Wed, 21 Aug 2013 09:12:06 GMT
  5. ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
  6. Server: CouchDB (Erlang/OTP)
  7. Transfer-Encoding: chunked
  8. {
  9. "offset": 0,
  10. "rows": [
  11. {
  12. "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  13. "key": [
  14. "sensor-260",
  15. "0"
  16. ],
  17. "value": null
  18. },
  19. {
  20. "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  21. "key": [
  22. "sensor-260",
  23. "1"
  24. ],
  25. "value": null
  26. },
  27. {
  28. "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  29. "key": [
  30. "sensor-260",
  31. "2"
  32. ],
  33. "value": null
  34. },
  35. {
  36. "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
  37. "key": [
  38. "sensor-260",
  39. "3"
  40. ],
  41. "value": null
  42. }
  43. ],
  44. "total_rows": 4
  45. }

1.6.4. /db/_partition/partition_id/_find

POST /{db}/_partition/{partition_id}/_find

  • Parameters

    • db – Database name

    • id (partition) – Name of the partition to query

This endpoint is responsible for finding a partition query by its ID. The returned view result will only contain rows with the specified partition id.

Refer to the find endpoint documentation for a complete description of the available parameters and the format of the returned data.

1.6.5. /db/_partition/partition_id/_explain

POST /{db}/_partition/{partition_id}/_explain

  • Parameters

    • db – Database name

    Partition id

    Name of the partition to query

This endpoint shows which index is being used by the query.

Refer to the explain endpoint documentation for a complete description of the available parameters and the format of the returned data.