[couchdb-documentation] branch partitioned_dbs created (now 780f3ac)

[rn...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rnewson pushed a change to branch partitioned_dbs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.


      at 780f3ac  initial thoughts on partitioned db doccumentation

This branch includes the following new commits:

     new 780f3ac  initial thoughts on partitioned db doccumentation

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.

[couchdb-documentation] 01/01: initial thoughts on partitioned db doccumentation

[rn...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rnewson pushed a commit to branch partitioned_dbs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit 780f3ac8fb761aabd92fcb3b636087c214e448c6
Author: Robert Newson <rn...@apache.org>
AuthorDate: Mon Sep 24 19:53:44 2018 +0100

    initial thoughts on partitioned db doccumentation
---
 src/api/database/common.rst     |  3 ++
 src/api/database/index.rst      |  1 +
 src/api/database/partitions.rst | 85 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 89 insertions(+)

diff --git a/src/api/database/common.rst b/src/api/database/common.rst
index 74b968d..a252d10 100644
--- a/src/api/database/common.rst
+++ b/src/api/database/common.rst
@@ -154,6 +154,9 @@
     :param db: Database name
     :query integer q: Shards, aka the number of range partitions. Default is
       8, unless overridden in the :config:option:`cluster config <cluster/q>`.
+    :query boolean partitioned: Specifies whether the database
+                                supports :ref:`user-defined
+                                partitions <api/db/_partition>`. Default is ``false``.
     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :>header Content-Type: - :mimetype:`application/json`
diff --git a/src/api/database/index.rst b/src/api/database/index.rst
index 1846166..2b42a4b 100644
--- a/src/api/database/index.rst
+++ b/src/api/database/index.rst
@@ -43,4 +43,5 @@ Where ``db`` is the name of any database.
     changes
     compact
     security
+    partitions
     misc
diff --git a/src/api/database/partitions.rst b/src/api/database/partitions.rst
new file mode 100644
index 0000000..37337a6
--- /dev/null
+++ b/src/api/database/partitions.rst
@@ -0,0 +1,85 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. _api/db/_partition:
+
+Ordinarily, the documents inside a database are arbitrarily assigned
+into a shard range. This has an adverse affect on query performance as
+it is necessary to contact every shard range to answer each query (it
+is not possible to know, a priori, which shard ranges have no
+matches).
+
+A partitioned database (created with ``?partitioned=true``) provides a
+solution to this if your use case is suitable. All documents within a
+partitioned database have a special format for their document id's
+
+.. code-block:: text
+
+    partition:id
+
+Where both ``partition`` and ``id`` adhere to the CouchDB document id
+restrictions.
+
+Documents with the same ``partition`` value are placed in the same shard
+range as each other. You should choose your ``partition`` values with
+care, the scalability and performance of this feature critically
+depends on it; ideally you have a natural choice in your application
+(user name or account name, for example) that partitions your data
+such that each partition can be queried meaningfully.
+
+==============================
+``/db/_partition/{partition}``
+==============================
+
+.. http:get:: /{db}/_partition/{partition}
+
+    Returns information about the specified partition.
+
+    **Request**:
+
+    .. code-block:: http
+
+        GET /db/_partition/foo HTTP/1.1
+        Host: localhost:5984
+
+    **Response**:
+
+    .. code-block:: http
+
+        HTTP/1.1 200 OK
+        Content-Type: application/json
+        Server: CouchDB (Erlang/OTP)
+
+        {
+            "ok": true,
+            "db_name": "db",
+            "partition_name": "foo",
+            "doc_count": 10,
+            "doc_del_count": 2,
+            "sizes": {
+                "active": 235,
+                "external": 412
+            }
+        }
+
+==================================
+``/db/_partition/partition/_find``
+==================================
+
+.. http:post:: /{db}/_partition/{partition}/_find
+    :synopsis: Find documents inside a specific partition
+
+    Find documents inside a specific partition, see the main
+    documentation for :ref:`_find <api/db/_find>`.
+
+    :param db: Database name
+    :param partition: Partition name