Skip to content
This repository was archived by the owner on Oct 17, 2022. It is now read-only.

Commit e27b050

Browse files
davispflimzy
davisp
and
flimzy
committed
Documentation for partitioned dbs
Co-Authored-By: Jonathan Hall <flimzy@flimzy.com>
1 parent 760f741 commit e27b050

File tree

6 files changed

+598
-0
lines changed

6 files changed

+598
-0
lines changed

‎src/api/database/common.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,8 @@
8686
:>json string update_seq: An opaque string that describes the state
8787
of the database. Do not rely on this string for counting the number
8888
of updates.
89+
:>json boolean props.partitioned: (optional) If present and true this
90+
indicates the the database is partitioned.
8991
:code 200: Request completed successfully
9092
:code 404: Requested database not found
9193

@@ -126,6 +128,7 @@
126128
"other": {
127129
"data_size": 66982448
128130
},
131+
"props": {},
129132
"purge_seq": 0,
130133
"sizes": {
131134
"active": 65031503,
@@ -159,6 +162,8 @@
159162
:query integer n: Replicas. The number of copies of the database in the
160163
cluster. The default is 3, unless overridden in the
161164
:config:option:`cluster config <cluster/n>` .
165+
:query boolean partitioned: Whether to create a partitioned database.
166+
Default is false.
162167
:<header Accept: - :mimetype:`application/json`
163168
- :mimetype:`text/plain`
164169
:>header Content-Type: - :mimetype:`application/json`

‎src/api/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,4 +38,5 @@ This reference is structured according to the URL structure, as below.
3838
database/index
3939
document/index
4040
ddoc/index
41+
partitioned-dbs
4142
local

‎src/api/partitioned-dbs.rst‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
2+
.. use this file except in compliance with the License. You may obtain a copy of
3+
.. the License at
4+
..
5+
.. http://www.apache.org/licenses/LICENSE-2.0
6+
..
7+
.. Unless required by applicable law or agreed to in writing, software
8+
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
9+
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
10+
.. License for the specific language governing permissions and limitations under
11+
.. the License.
12+
13+
.. _api/partioned-dbs:
14+
15+
=====================
16+
Partitioned Databases
17+
=====================
18+
19+
Partitioned databases allow for data colocation in a cluster, which provides
20+
significant performance improvements for queries constrained to a single
21+
partition.
22+
23+
See the guide for
24+
:ref:`getting started with partitioned databases <partitioned-dbs>`
25+
26+
``/db/_partition/partition``
27+
============================
28+
29+
.. http:get:: /{db}/_partition/{partition}
30+
:synopsis: Returns document and size info for the given partition
31+
32+
This endpoint returns information describing the provided partition.
33+
It includes document and deleted document counts along with external
34+
and active data sizes.
35+
36+
:code 200: Request completed successfully
37+
38+
**Request**:
39+
40+
.. code-block:: http
41+
42+
GET /db/_partition/foo HTTP/1.1
43+
Accept: application/json
44+
Host: localhost:5984
45+
46+
**Response**:
47+
48+
.. code-block:: http
49+
50+
HTTP/1.1 200 OK
51+
Cache-Control: must-revalidate
52+
Content-Length: 119
53+
Content-Type: application/json
54+
Date: Thu, 24 Jan 2019 17:19:59 GMT
55+
Server: CouchDB/2.3.0-a1e11cea9 (Erlang OTP/21)
56+
57+
{
58+
"db_name": "my_new_db",
59+
"doc_count": 1,
60+
"doc_del_count": 0,
61+
"partition": "sensor-260",
62+
"sizes": {
63+
"active": 244,
64+
"external": 347
65+
}
66+
}
67+
68+
69+
``/db/_partition/partition/_all_docs``
70+
======================================
71+
72+
.. http:get:: /{db}/_partition/{partition}/_all_docs
73+
:synopsis: Return all docs in the specified partition
74+
75+
:param db: Database name
76+
:param partition: Partition name
77+
78+
This endpoint is a convenience endpoint for automatically setting
79+
bounds on the provided partition range. Similar results can be had
80+
by using the global ``/db/_all_docs`` end point with appropriately
81+
configured values for ``start_key`` and ``end_key``.
82+
83+
Refer to the :ref:`view endpoint <api/ddoc/view>` documentation for
84+
a complete description of the available query parameters and the format
85+
of the returned data.
86+
87+
**Request**:
88+
89+
.. code-block:: http
90+
91+
GET /db/_partition/sensor-260/_all_docs HTTP/1.1
92+
Accept: application/json
93+
Host: localhost:5984
94+
95+
**Response**:
96+
97+
.. code-block:: http
98+
99+
HTTP/1.1 200 OK
100+
Cache-Control: must-revalidate
101+
Content-Type: application/json
102+
Date: Sat, 10 Aug 2013 16:22:56 GMT
103+
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
104+
Server: CouchDB (Erlang/OTP)
105+
Transfer-Encoding: chunked
106+
107+
{
108+
"offset": 0,
109+
"rows": [
110+
{
111+
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
112+
"key": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
113+
"value": {
114+
"rev": "1-05ed6f7abf84250e213fcb847387f6f5"
115+
}
116+
}
117+
],
118+
"total_rows": 1
119+
}
120+
121+
122+
123+
``/db/_partition/partition/_design/design-doc/_view/view-name``
124+
===============================================================
125+
126+
.. http:get:: /{db}/_partition/{partition}/_design/{ddoc}/_view/{view}
127+
:synopsis: Execute a partitioned query
128+
129+
:param db: Database name
130+
:param partition: Partition name
131+
:param ddoc: Design document id
132+
:param view: View name
133+
134+
This endpoint is responsible for executing a partitioned query. The
135+
returned view result will only contain rows with the specified
136+
partition name.
137+
138+
Refer to the :ref:`view endpoint <api/ddoc/view>` documentation for
139+
a complete description of the available query parameters and the format
140+
of the returned data.
141+
142+
.. code-block:: http
143+
144+
GET /db/_partition/sensor-260/_design/sensor-readings/_view/by_sensor HTTP/1.1
145+
Accept: application/json
146+
Host: localhost:5984
147+
148+
**Response**:
149+
150+
.. code-block:: http
151+
152+
HTTP/1.1 200 OK
153+
Cache-Control: must-revalidate
154+
Content-Type: application/json
155+
Date: Wed, 21 Aug 2013 09:12:06 GMT
156+
ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
157+
Server: CouchDB (Erlang/OTP)
158+
Transfer-Encoding: chunked
159+
160+
161+
{
162+
"offset": 0,
163+
"rows": [
164+
{
165+
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
166+
"key": [
167+
"sensor-260",
168+
"0"
169+
],
170+
"value": null
171+
},
172+
{
173+
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
174+
"key": [
175+
"sensor-260",
176+
"1"
177+
],
178+
"value": null
179+
},
180+
{
181+
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
182+
"key": [
183+
"sensor-260",
184+
"2"
185+
],
186+
"value": null
187+
},
188+
{
189+
"id": "sensor-260:sensor-reading-ca33c748-2d2c-4ed1-8abf-1bca4d9d03cf",
190+
"key": [
191+
"sensor-260",
192+
"3"
193+
],
194+
"value": null
195+
}
196+
],
197+
"total_rows": 4
198+
}

‎src/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ Apache CouchDB
4747
api/index
4848
json-structure
4949
query-server/index
50+
partitioned-dbs/index
5051

5152
.. toctree::
5253
:caption: Other

0 commit comments

Comments
 (0)