1.6. Partitioned Databases — Apache CouchDB® 3.5 Documentation

# 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_id}`

GET /{db}/_partition/{partition_id}

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

  Parameters:

    - db – Database name

    - partition_id – Name of the partition to query

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

  Request:

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

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 119
      Content-Type: application/json
      Date: Thu, 24 Jan 2019 17:19:59 GMT
      Server: CouchDB/2.3.0-a1e11cea9 (Erlang OTP/21)

      {
        "db_name": "my_new_db",
        "doc_count": 1,
        "doc_del_count": 0,
        "partition": "sensor-260",
        "sizes": {
          "active": 244,
          "external": 347
        }
      }

## 1.6.2. `/{db}/_partition/{partition_id}/_all_docs`

GET /{db}/_partition/{partition_id}/_all_docs

  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.

  Parameters:

    - db – Database name

    - partition_id – Partition name

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

  Request:

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

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Type: application/json
      Date: Sat, 10 Aug 2013 16:22:56 GMT
      ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
      Server: CouchDB (Erlang/OTP)
      Transfer-Encoding: chunked

      {
        "offset": 0,
        "rows": [
          {
            "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "key": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "value": {
              "rev": "1-05ed6f7abf84250e213fcb847387f6f5"
            }
          }
        ],
        "total_rows": 1
      }

## 1.6.3. `/{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}`

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

  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.

  Parameters:

    - db – Database name

    - partition_id – Partition name

    - ddoc – Design document id

    - view – View name

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

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

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Type: application/json
      Date: Wed, 21 Aug 2013 09:12:06 GMT
      ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
      Server: CouchDB (Erlang/OTP)
      Transfer-Encoding: chunked

      {
        "offset": 0,
        "rows": [
          {
            "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "key": [
              "sensor-260",
              "0"
            ],
            "value": null
          },
          {
            "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "key": [
              "sensor-260",
              "1"
            ],
            "value": null
          },
          {
            "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "key": [
              "sensor-260",
              "2"
            ],
            "value": null
          },
          {
            "id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
            "key": [
              "sensor-260",
              "3"
            ],
            "value": null
          }
        ],
        "total_rows": 4
      }

## 1.6.4. `/{db}/_partition/{partition_id}/_find`

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

  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.

  Parameters:

    - db – Database name

    - partition_id – Name of the partition to query

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

## 1.6.5. `/{db}/_partition/{partition_id}/_explain`

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

  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.

  Parameters:

    - db – Database name

    - partition_id – Name of the partition to query

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials