You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/09/27 20:03:02 UTC
[01/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Updated Branches:
refs/heads/1781-reorganize-and-improve-docs e5a101f8b -> 2375d0056 (forced update)
Better API index naming.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/bad9e87c
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/bad9e87c
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/bad9e87c
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: bad9e87cd97c85a49061ad917ade6986c7a4959d
Parents: a14a432
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 14 22:06:34 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:44 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bad9e87c/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index 255e85a..fb7cff0 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -435,7 +435,7 @@ class HTTPIndex(Index):
name = 'api'
localname = 'CouchDB HTTP API Reference'
- shortname = 'api'
+ shortname = 'API Reference'
def generate(self, docnames=None):
content = {}
[11/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Some markup fixes.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/e475c726
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/e475c726
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/e475c726
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: e475c726dd3e92a033d59eacf12aaff4e3837258
Parents: faaf97e
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 18 10:24:35 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/document/attachments.rst | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/e475c726/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index b3bb538..3f3e8d4 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -71,7 +71,7 @@
.. http:get:: /{db}/{docid}/{attname}
- Returns the file attachment associated with the document.
+ Returns the file attachment associated with the document.
The raw data of the associated attachment is returned (just as if you were
accessing a static file. The returned :http:header:`Content-Type`
will be the same as the content type set when the document attachment
@@ -264,8 +264,8 @@ streams alike. This is available for all attachments inside CouchDB.
This is just a real quick run through how this looks under the hood.
Usually, you will have larger binary files to serve from CouchDB, like
MP3s and videos, but to make things a little more obvious, I use a text
-file here (Note that I use the ``application/octet-stream`` Content-Type
-instead of ``text/plain``).
+file here (Note that I use the :mimetype:`application/octet-stream`
+:http:header`Content-Type` instead of :mimetype:`text/plain`).
.. code-block:: bash
@@ -304,7 +304,7 @@ But say we only want the first 13 bytes:
My hovercraft
HTTP supports many ways to specify single and even multiple byte
-ranges. Read all about it in `RFC 2616`_.
+ranges. Read all about it in :rfc:`2616#section-14.27`.
.. note::
Databases that have been created with CouchDB 1.0.2 or earlier will
@@ -312,5 +312,3 @@ ranges. Read all about it in `RFC 2616`_.
algorithm. If you plan to make heavy use of this feature, make sure
to compact your database with CouchDB |version| to take advantage of a
better algorithm to find byte ranges.
-
-.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
[02/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Don't group items in HTTP API reference.
We're cares about every resource.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a14a4323
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a14a4323
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a14a4323
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a14a43239bf07c01bd6ffc66becc0569e124408a
Parents: 5cc9f67
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 14 22:06:11 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:44 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 18 +-----------------
1 file changed, 1 insertion(+), 17 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a14a4323/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index f2051f4..255e85a 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -437,21 +437,6 @@ class HTTPIndex(Index):
localname = 'CouchDB HTTP API Reference'
shortname = 'api'
- def __init__(self, *args, **kwargs):
- super(HTTPIndex, self).__init__(*args, **kwargs)
-
- self.ignore = [
- [l for l in x.split('/') if l]
- for x in self.domain.env.config['http_index_ignore_prefixes']]
- self.ignore.sort(key=lambda x: -len(x))
-
- def grouping_prefix(self, path):
- letters = [x for x in path.split('/') if x]
- for prefix in self.ignore:
- if letters[:len(prefix)] == prefix:
- return '/' + '/'.join(letters[:len(prefix) + 1])
- return '/%s' % (letters[0] if letters else '',)
-
def generate(self, docnames=None):
content = {}
items = ((method, path, info)
@@ -459,7 +444,7 @@ class HTTPIndex(Index):
for path, info in routes.items())
items = sorted(items, key=lambda item: item[1])
for method, path, info in items:
- entries = content.setdefault(self.grouping_prefix(path), [])
+ entries = content.setdefault(path, [])
entries.append([
method.upper() + ' ' + path, 0, info[0],
http_resource_anchor(method, path), '', '', info[1]
@@ -633,4 +618,3 @@ def setup(app):
get_lexer_by_name('http')
except ClassNotFound:
app.add_lexer('http', HTTPLexer())
- app.add_config_value('http_index_ignore_prefixes', [], None)
[47/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Describe some performance tips.
Source: http://wiki.apache.org/couchdb/Performance
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/71abc8f1
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/71abc8f1
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/71abc8f1
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 71abc8f1672cdabc5fa66f5ad706f7b8eee9e51f
Parents: 47ff863
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:20:30 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +
share/doc/src/maintenance/index.rst | 1 +
share/doc/src/maintenance/performance.rst | 295 +++++++++++++++++++++++++
3 files changed, 299 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index f59e557..c13f8a2 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -119,6 +119,7 @@ html_files = \
html/_sources/intro/why.txt \
html/_sources/maintenance/compaction.txt \
html/_sources/maintenance/index.txt \
+ html/_sources/maintenance/performance.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -235,6 +236,7 @@ html_files = \
html/intro/why.html \
html/maintenance/compaction.html \
html/maintenance/index.html \
+ html/maintenance/performance.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -373,6 +375,7 @@ src_files = \
../src/intro/why.rst \
../src/maintenance/compaction.rst \
../src/maintenance/index.rst \
+ ../src/maintenance/performance.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/src/maintenance/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/index.rst b/share/doc/src/maintenance/index.rst
index 86cc761..b0072fe 100644
--- a/share/doc/src/maintenance/index.rst
+++ b/share/doc/src/maintenance/index.rst
@@ -18,3 +18,4 @@ CouchDB Maintenance
.. toctree::
compaction
+ performance
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71abc8f1/share/doc/src/maintenance/performance.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/performance.rst b/share/doc/src/maintenance/performance.rst
new file mode 100644
index 0000000..918b1cf
--- /dev/null
+++ b/share/doc/src/maintenance/performance.rst
@@ -0,0 +1,295 @@
+.. 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.
+
+.. default-domain:: http
+
+
+.. _performance:
+
+===========
+Performance
+===========
+
+With up to tens of thousands of documents you will generally find CouchDB to
+perform well no matter how you write your code. Once you start getting into
+the millions of documents you need to be a lot more careful.
+
+
+Disk I/O
+========
+
+File Size
+---------
+
+The smaller your file size, the less `I/O` operations there will be,
+the more of the file can be cached by CouchDB and the operating system,
+the quicker it is to replicate, backup etc. Consequently you should carefully
+examine the data you are storing. For example it would be silly to use keys
+that are hundreds of characters long, but your program would be hard to
+maintain if you only used single character keys. Carefully consider data
+that is duplicated by putting it in views.
+
+
+Disk and File System Performance
+--------------------------------
+
+Using faster disks, striped RAID arrays and modern file systems can all speed
+up your CouchDB deployment. However, there is one option that can increase
+the responsiveness of your CouchDB server when disk performance is a
+bottleneck. From the Erlang documentation for the file module:
+
+ On operating systems with thread support, it is possible to let file
+ operations be performed in threads of their own, allowing other Erlang
+ processes to continue executing in parallel with the file operations.
+ See the `command line flag +A in erl(1)`_.
+
+Setting this argument to a number greater than zero can keep your CouchDB
+installation responsive even during periods of heavy disk utilization. The
+easiest way to set this option is through the ``ERL_FLAGS`` environment
+variable. For example, to give Erlang four threads with which to perform I/O
+operations add the following to ``(prefix)/etc/defaults/couchdb``
+(or equivalent)::
+
+ export ERL_FLAGS="+A 4"
+
+
+.. _command line flag +A in erl(1): http://erlang.org/doc/man/erl.html
+
+
+System Resource Limits
+======================
+
+One of the problems that administrators run into as their deployments become
+large are resource limits imposed by the system and by the application
+configuration. Raising these limits can allow your deployment to grow beyond
+what the default configuration will support.
+
+
+CouchDB Configuration Options
+-----------------------------
+
+delayed_commits
+^^^^^^^^^^^^^^^
+
+The :ref:`delayed commits <config/couchdb/delayed_commits>` allows it to
+achieve better write performance for some workloads while sacrificing a small
+amount of durability. The setting causes CouchDB to wait up to a full second
+before committing new data after an update. If the server crashes before
+the header is written then any writes since the last commit are lost. Keep this
+option enabled on your own risk.
+
+max_dbs_open
+^^^^^^^^^^^^
+
+In your :ref:`configuration <config>` (local.ini or similar) familiarize
+yourself with the :ref:`max_dbs_open <config/couchdb/max_dbs_open>`:
+
+.. code-block:: ini
+
+ [couchdb]
+ max_dbs_open = 100
+
+This option places an upper bound on the number of databases that can be
+open at one time. CouchDB reference counts database accesses internally and
+will close idle databases when it must. Sometimes it is necessary to keep
+more than the default open at once, such as in deployments where many databases
+will be continuously replicating.
+
+
+Erlang
+------
+
+Even if you've increased the maximum connections CouchDB will allow,
+the Erlang runtime system will not allow more than 1024 connections by
+default. Adding the following directive to ``(prefix)/etc/default/couchdb`` (or
+equivalent) will increase this limit (in this case to 4096)::
+
+ export ERL_MAX_PORTS=4096
+
+CouchDB versions up to 1.1.x also create Erlang Term Storage (`ETS`_) tables for
+each replication. If you are using a version of CouchDB older than 1.2 and
+must support many replications, also set the ``ERL_MAX_ETS_TABLES`` variable.
+The default is approximately 1400 tables.
+
+Note that on Mac OS X, Erlang will not actually increase the file descriptor
+limit past 1024 (i.e. the system header–defined value of ``FD_SETSIZE``). See
+`this tip for a possible workaround`_ and `this thread for a deeper
+explanation`_.
+
+.. _ETS: http://www.erlang.org/doc/man/ets.html
+.. _this tip for a possible workaround: http://erlang.org/pipermail/erlang-questions/2011-December/063119.html
+.. _this thread for a deeper explanation: http://erlang.org/pipermail/erlang-questions/2011-October/061971.html
+
+
+PAM and ulimit
+--------------
+
+Finally, most \*nix operating systems impose various resource limits on every
+process. If your system is set up to use the Pluggable Authentication Modules
+(`PAM`_) system, increasing this limit is straightforward. For example,
+creating a file named ``/etc/security/limits.d/100-couchdb.conf`` with the
+following contents will ensure that CouchDB can open enough file descriptors
+to service your increased maximum open databases and Erlang ports::
+
+ #<domain> <type> <item> <value>
+ couchdb hard nofile 4096
+ couchdb soft nofile 4096
+
+If your system does not use PAM, a `ulimit` command is usually available for
+use in a custom script to launch CouchDB with increased resource limits.
+If necessary, feel free to increase this limits as long as your hardware can
+handle the load.
+
+.. _PAM: http://www.linux-pam.org/
+
+
+Network
+=======
+
+There is latency overhead making and receiving each request/response.
+In general you should do your requests in batches. Most APIs have some
+mechanism to do batches, usually by supplying lists of documents or keys in
+the request body. Be careful what size you pick for the batches. The larger
+batch requires more time your client has to spend encoding the items into JSON
+and more time is spent decoding that number of responses. Do some benchmarking
+with your own configuration and typical data to find the sweet spot.
+It is likely to be between one and ten thousand documents.
+
+If you have a fast I/O system then you can also use concurrency - have
+multiple requests/responses at the same time. This mitigates the latency
+involved in assembling JSON, doing the networking and decoding JSON.
+
+As of CouchDB 1.1.0, users often report lower write performance of documents
+compared to older releases. The main reason is that this release ships with
+the more recent version of the HTTP server library Mochiweb, which by default
+sets the TCP socket option `SO_NODELAY`_ to false. This means that small data
+sent to the TCP socket, like the reply to a document write request (or reading
+a very small document), will not be sent immediately to the network - TCP will
+buffer it for a while hoping that it will be asked to send more data through
+the same socket and then send all the data at once for increased performance.
+This TCP buffering behaviour can be disabled via :ref:`socket_options
+<config/httpd/socket_options>`:
+
+.. code-block:: ini
+
+ [httpd]
+ socket_options = [{nodelay, true}]
+
+.. _SO_NODELAY: http://en.wikipedia.org/wiki/Nagle%27s_algorithm
+
+.. seealso::
+
+ Bulk :ref:`load <api/db/all_docs>` and :ref:`store <api/db/bulk_docs>` API.
+
+
+CouchDB
+=======
+
+DELETE operation
+----------------
+
+When you :method:`DELETE` a document the database will create a new
+revision which contains the ``_id`` and ``_rev`` fields as well as
+the `_deleted` flag. This revision will remain even after a `database
+compaction` so that the deletion can be replicated. Deleted documents, like
+non-deleted documents, can affect view build times, :method:`PUT` and
+:method:`DELETE` requests time and size of database on disk, since they
+increase the size of the B+Tree's. You can see the number of deleted documents
+in :get:`database information </{db}>`. If your use case creates lots of
+deleted documents (for example, if you are storing short-term data like logfile
+entries, message queues, etc), you might want to periodically switch to a new
+database and delete the old one (once the entries in it have all expired).
+
+
+Document's ID
+-------------
+
+The db file size is derived from your document and view sizes but also on a
+multiple of your ``_id`` sizes. Not only is the ``_id`` present in the document,
+but it and parts of it are duplicated in the binary tree structure CouchDB uses
+to navigate the file to find the document in the first place. As a real world
+example for one user switching from 16 byte ids to 4 byte ids made a database
+go from 21GB to 4GB with 10 million documents (the raw JSON text when from
+2.5GB to 2GB).
+
+Inserting with sequential (and at least sorted) ids is faster than random ids.
+Consequently you should consider generating ids yourself, allocating them
+sequentially and using an encoding scheme that consumes fewer bytes.
+For example, something that takes 16 hex digits to represent can be done in
+4 base 62 digits (10 numerals, 26 lower case, 26 upper case).
+
+
+Views
+=====
+
+Views Generation
+----------------
+
+Views with the Javascript query server are extremely slow to generate when
+there are a non-trivial number of documents to process. The generation process
+won't even saturate a single CPU let alone your I/O. The cause is the latency
+involved in the CouchDB server and separate `couchjs` query server, dramatically
+indicating how important it is to take latency out of your implementation.
+
+You can let view access be "stale" but it isn't practical to determine when
+that will occur giving you a quick response and when views will be updated
+which will take a long time. (A 10 million document database took about 10
+minutes to load into CouchDB but about 4 hours to do view generation).
+
+View information isn't replicated - it is rebuilt on each database so you
+can't do the view generation on a separate sever.
+
+
+Builtin Reduce Functions
+------------------------
+
+If you’re using a very simple view function that only performs a sum or count
+reduction, you can call native Erlang implementations of them by simply
+writing ``_sum`` or ``_count`` in place of your function declaration.
+This will speed up things dramatically, as it cuts down on IO between CouchDB
+and the :ref:`JavaScript query server <query-server/js>`. For example, as
+`mentioned on the mailing list`_, the time for outputting an (already indexed
+and cached) view with about 78,000 items went down from 60 seconds to 4 seconds.
+
+Before:
+
+.. code-block:: javascript
+
+ {
+ "_id": "_design/foo",
+ "views": {
+ "bar": {
+ "map": "function (doc) { emit(doc.author, 1); }",
+ "reduce": "function (keys, values, rereduce) { return sum(values); }"
+ }
+ }
+ }
+
+After:
+
+.. code-block:: javascript
+
+ {
+ "_id": "_design/foo",
+ "views": {
+ "bar": {
+ "map": "function (doc) { emit(doc.author, 1); }",
+ "reduce": "_sum"
+ }
+ }
+ }
+
+.. _mentioned on the mailing list: http://mail-archives.apache.org/mod_mbox/couchdb-user/201003.mbox/%3c5E07E00E-3D69-4A8C-ADA3-1B20CF0BA4C8@julianstahnke.com%3e
+
+.. seealso::
+
+ :ref:`reducefun/builtin`
[23/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Use acinclude.m4 as single source of project information.
There is no reason to edit two files to make the release.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1e23d25e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1e23d25e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1e23d25e
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 1e23d25e875d2c6d7d026c863bc2ecd9b4bb0a35
Parents: 1eb6047
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 13:40:48 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:30 2013 +0400
----------------------------------------------------------------------
share/doc/src/conf.py | 47 ++++++++++++++++++++++++++++++++++++++++------
1 file changed, 41 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1e23d25e/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 2e5234a..9606213 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -10,26 +10,55 @@
## License for the specific language governing permissions and limitations under
## the License.
+import datetime
import os
+import re
import sys
sys.path.insert(0, os.path.abspath('../ext'))
extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github', 'httpdomain']
+_info = {}
+_regex = re.compile('m4_define\(\[(.+)\],\s+\[(.+)\]\)')
+_acinclude_m4 = '../../../acinclude.m4'
+_acinclude_m4_in = '../../../acinclude.m4.in'
+if os.path.exists(_acinclude_m4):
+ _source = _acinclude_m4
+elif os.path.exists(_acinclude_m4_in):
+ _source = _acinclude_m4_in
+else:
+ _source = None
+if _source is not None:
+ _info = dict(_regex.findall(open(_source).read()))
+else:
+ raise ValueError('''Project information source wasn't found. We're assume
+that it's located within "acinclude.m4" file at the root of the project, but
+looks like there is no such file there.''')
+
source_suffix = ".rst"
master_doc = "index"
nitpicky = True
-version = "1.4"
+version = '.'.join([
+ _info['LOCAL_VERSION_MAJOR'],
+ _info['LOCAL_VERSION_MINOR']
+])
-release = "1.4.0"
+release = '.'.join([
+ _info['LOCAL_VERSION_MAJOR'],
+ _info['LOCAL_VERSION_MINOR'],
+ _info['LOCAL_VERSION_REVISION']
+]) + _info['LOCAL_VERSION_STAGE'] + '' + _info['LOCAL_VERSION_RELEASE']
-project = u"Apache CouchDB"
+project = _info['LOCAL_PACKAGE_NAME']
-copyright = u"2013, The Apache Software Foundation"
+copyright = '%d, %s' % (
+ datetime.datetime.now().year,
+ _info['LOCAL_PACKAGE_AUTHOR_NAME']
+)
highlight_language = "json"
@@ -41,7 +70,11 @@ templates_path = ["../templates"]
html_static_path = ["../static"]
-html_title = "Apache CouchDB " + version + " Manual"
+html_title = ' '.join([
+ project,
+ version,
+ 'Manual'
+])
html_style = "rtd.css"
@@ -88,7 +121,7 @@ texinfo_documents = [(
)]
extlinks = {
- 'issue': ('https://issues.apache.org/jira/browse/COUCHDB-%s', 'COUCHDB-'),
+ 'issue': ('%s-%%s' % _info['LOCAL_BUG_URI'], 'COUCHDB-'),
'commit': ('https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=%s', '#')
}
@@ -97,3 +130,5 @@ github_project = 'apache/couchdb'
github_branch = 'master'
github_docs_path = 'share/doc/src'
+
+del _info, _regex, _acinclude_m4, _acinclude_m4_in, _source
[41/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Remove duplicate MacPorts instructions.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/738095bb
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/738095bb
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/738095bb
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 738095bbf9675eb8650732d9693ef286b83d31b3
Parents: fe961f8
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 11:57:04 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/install/mac.rst | 30 ------------------------------
1 file changed, 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/738095bb/share/doc/src/install/mac.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/mac.rst b/share/doc/src/install/mac.rst
index 2f7a12d..81afa6b 100644
--- a/share/doc/src/install/mac.rst
+++ b/share/doc/src/install/mac.rst
@@ -42,36 +42,6 @@ That's all, now CouchDB is installed on your Mac:
.. _Open up Futon: http://localhost:5984/_utils
-
-.. _install/mac/macports:
-
-Installation from MacPorts
-==========================
-
-To install CouchDB using MacPorts you have 2 package choices:
-
-- ``couchdb`` - the latest release version
-- ``couchdb-devel`` - updated every few weeks from the master branch
-
-::
-
- $ sudo port install couchdb
-
-or, if you want the last development version:
-
- $ sudo port install couchdb-devel
-
-MacPorts takes care of installing all necessary dependencies.
-It should now be up and accessible via Futon at http://127.0.0.1:5984/_utils.
-
-If you want to run CouchDB as a service, load the launchd configuration which
-comes with the project, with this command::
-
- $ sudo port load couchdb
-
-Now CouchDB should be started automatically after every reboot.
-
-
.. _install/mac/homebrew:
Installation with HomeBrew
[43/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Swap maintenance-replication sections.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/de48ff31
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/de48ff31
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/de48ff31
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: de48ff311b223563b302b5e93bd9feba66543c47
Parents: 71abc8f
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 11 20:16:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/de48ff31/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index bb491de..f00aed6 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -21,8 +21,8 @@
intro/index
install/index
config/index
- maintenance/index
replication/index
+ maintenance/index
couchapp/index
externals
query-server/index
[15/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Source article remembers old map function. Now it's actual.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/3017c9af
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/3017c9af
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/3017c9af
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 3017c9af4f5c4a3160735a8ea7e0881e2bf652c7
Parents: ebaf890
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 20:49:32 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/couchapp/views/joins.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/3017c9af/share/doc/src/couchapp/views/joins.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/views/joins.rst b/share/doc/src/couchapp/views/joins.rst
index 392bf5b..3abae9d 100644
--- a/share/doc/src/couchapp/views/joins.rst
+++ b/share/doc/src/couchapp/views/joins.rst
@@ -208,7 +208,7 @@ all blog posts, keyed by author:
function(doc) {
for (var i in doc.comments) {
- map(doc.comments[i].author, doc.comments[i].content);
+ emit(doc.comments[i].author, doc.comments[i].content);
}
}
@@ -286,7 +286,7 @@ ID:
function(doc) {
if (doc.type == "comment") {
- map(doc.post, {author: doc.author, content: doc.content});
+ emit(doc.post, {author: doc.author, content: doc.content});
}
}
@@ -299,7 +299,7 @@ Viewing all comments by author is just as easy as before:
function(doc) {
if (doc.type == "comment") {
- map(doc.author, {post: doc.post, content: doc.content});
+ emit(doc.author, {post: doc.post, content: doc.content});
}
}
@@ -332,9 +332,9 @@ some use of that:
function(doc) {
if (doc.type == "post") {
- map([doc._id, 0], doc);
+ emit([doc._id, 0], doc);
} else if (doc.type == "comment") {
- map([doc.post, 1], doc);
+ emit([doc.post, 1], doc);
}
}
[20/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update NOTICE.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ec2452b3
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ec2452b3
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ec2452b3
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: ec2452b3c6602a0544809919b73b4c8197efca1d
Parents: 67de5f5
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 22:08:15 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:00:24 2013 +0400
----------------------------------------------------------------------
NOTICE | 18 +++++++++++++++++-
1 file changed, 17 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ec2452b3/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index 95d4ff6..6c51a48 100644
--- a/NOTICE
+++ b/NOTICE
@@ -146,7 +146,7 @@ This product also includes the following third-party components:
Copyright 2012, Benoît Chesneau <be...@refuge.io>
-* mocha.js (https://github.com/visionmedia/mocha)
+ * mocha.js (https://github.com/visionmedia/mocha)
Copyright (c) 2011-2013 TJ Holowaychuk <tj...@vision-media.ca>
@@ -166,3 +166,19 @@ This product also includes the following third-party components:
Copyright (c) 2013 Dave Gandy
+ * httpdomain.py (https://bitbucket.org/birkenfeld/sphinx-contrib/src/6a3a8ca714cfce957530890d0431d9a7b88c930f/httpdomain/sphinxcontrib/httpdomain.py?at=httpdomain-1.1.9)
+
+ Copyright (c) 2010, Hong Minhee <mi...@dahlia.kr>
+
+ * externals.rst (http://davispj.com/2010/09/26/new-couchdb-externals-api.html)
+
+ Copyright 2008-2010, Paul Joseph Davis <pa...@gmail.com>
+
+ * protocol.rst (http://www.dataprotocols.org/en/latest/couchdb_replication.html)
+
+ Copyright 2011-2013, Benoît Chesneau <be...@refuge.io>
+
+ * views/intro.rst views/nosql.rst views/pagination.rst
+
+ Copyright 2013, Creative Commons Attribution license
+
[45/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Fix main TOC tree reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/2375d005
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/2375d005
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/2375d005
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 2375d0056a9fb866a06ec59a632ccc8b5cf4cbf9
Parents: ebaac5c
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri Sep 27 21:15:26 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 6 +++---
share/doc/src/conf.py | 4 ++--
2 files changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2375d005/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 729313a..d03eb30 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -139,9 +139,9 @@ html_files = \
html/_sources/whatsnew/1.3.txt \
html/_sources/whatsnew/1.4.txt \
html/_sources/whatsnew/index.txt \
+ html/_sources/contents.txt \
html/_sources/contributing.txt \
html/_sources/externals.txt \
- html/_sources/index.txt \
html/_sources/json-structure.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
@@ -256,8 +256,8 @@ html_files = \
html/whatsnew/1.3.html \
html/whatsnew/1.4.html \
html/whatsnew/index.html \
+ html/contents.html \
html/externals.html \
- html/index.html \
html/json-structure.html \
html/objects.inv \
html/http-api.html \
@@ -395,9 +395,9 @@ src_files = \
../src/whatsnew/1.3.rst \
../src/whatsnew/1.4.rst \
../src/whatsnew/index.rst \
+ ../src/contents.rst \
../src/contributing.rst \
../src/externals.rst \
- ../src/index.rst \
../src/json-structure.rst \
../src/conf.py
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2375d005/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index f60e545..6cdb9ef 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -108,7 +108,7 @@ html_sidebars = {
text_newlines = "native"
latex_documents = [(
- "index",
+ "contents",
"CouchDB.tex",
project,
"",
@@ -121,7 +121,7 @@ latex_elements = {
}
texinfo_documents = [(
- "index",
+ "contents",
"CouchDB",
project,
"",
[17/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update Rewrite API reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/efb76556
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/efb76556
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/efb76556
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: efb765561e87496759649bc40506087217f956ab
Parents: d5d3c8a
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 16:27:03 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/rewrites.rst | 79 +++++++++++++++++++++++++++++---
1 file changed, 72 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/efb76556/share/doc/src/api/ddoc/rewrites.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/rewrites.rst b/share/doc/src/api/ddoc/rewrites.rst
index e1998aa..3bcf6b4 100644
--- a/share/doc/src/api/ddoc/rewrites.rst
+++ b/share/doc/src/api/ddoc/rewrites.rst
@@ -13,12 +13,77 @@
.. _api/ddoc/rewrite:
-``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-=============================================================
+``/db/_design/design-doc/_rewrite/path``
+========================================
-.. todo:: ALL /db/_design/design-doc/_rewrite/rewrite-name/anything
+.. http:any:: /{db}/_design/{ddocname}/_rewrite/{path}
-* **Method**: ``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
+ Rewrites the specified path by rules defined in the specified design document.
+
+ The rewrite rules are defined in *array* field of the design document called
+ ``rewrites``. Each rule is an *object* with next structure:
+
+ - **from** (*string*): The path rule used to bind current uri to the rule.
+ It use pattern matching for that
+ - **to** (*string*): Rule to rewrite an url. It can contain variables
+ depending on binding variables discovered during pattern matching and
+ query args (url args and from the query member)
+ - **method** (*string*): Method to bind the request method to the rule.
+ Default is ``"*"``
+ - **query** (*object*): Query args you want to define they can contain
+ dynamic variable by binding the key
+
+ The ``to``and ``from`` paths may contains string patterns with leading ``:``
+ or ``*`` characters.
+
+ For example: ``/somepath/:var/*``
+
+ - This path is converted in Erlang list by splitting ``/``
+ - Each ``var`` are converted in atom
+ - ``""`` are converted to ``''`` atom
+ - The pattern matching is done by splitting ``/`` in request url in a list of
+ token
+ - A string pattern will match equal token
+ - The star atom (``'*'`` in single quotes) will match any number of tokens,
+ but may only be present as the last `pathterm` in a `pathspec`
+ - If all tokens are matched and all `pathterms` are used, then the `pathspec`
+ matches
+
+ The pattern matching is done by first matching the request method to a rule.
+ By default all methods match a rule. (method is equal to ``"*"`` by default).
+ Then It will try to match the path to one rule. If no rule match, then a
+ :http:statuscode:`404` response returned.
+
+ Once a rule is found we rewrite the request url using the ``to`` and ``query``
+ fields. The identified token are matched to the rule and will replace var.
+ If ``'*'`` is found in the rule it will contain the remaining part if it
+ exists.
+
+ Examples:
+
+ +--------------------------------------+----------+------------------+-------+
+ | Rule | Url | Rewrite to | Tokens|
+ +======================================+==========+==================+=======+
+ | {"from": "/a", "to": "/some"} | /a | /some | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/\*", "to": "/some/\*} | /a/b/c | /some/b/c | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/b", "to": "/some"} | /a/b?k=v | /some?k=v | k=v |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/b", "to": "/some/:var"} | /a/b | /some/b?var=b | var=b |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/:foo/", | /a/b/c | /some/b/c?foo=b | foo=b |
+ | "to": "/some/:foo/"} | | | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/:foo", "to": "/some", | /a/b | /some/?k=b&foo=b | foo=b |
+ | "query": { "k": ":foo" }} | | | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a", "to": "/some/:foo"} | /a?foo=b | /some/?b&foo=b | foo=b |
+ +--------------------------------------+----------+------------------+-------+
+
+ Request method, header, query parameters, request payload and response body
+ are depended on endpoint to which url will be rewrited.
+
+ :param db: Database name
+ :param ddocname: Design document name
+ :param path: URL path to rewrite
[25/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Externals API article cleanup.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b35bf757
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b35bf757
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b35bf757
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: b35bf757e2376dac20b5a295e08bf208e5aa3ba0
Parents: fe79a4d
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 16:52:13 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/externals.rst | 77 ++++++++++++++++++----------------------
1 file changed, 35 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b35bf757/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 10ed34a..9b4530f 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -19,9 +19,10 @@ CouchDB Externals API
:Author: Paul Joseph Davis
:Date: 2010-09-26
+:Source: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
-For a bit of background, CouchDB has had an API for managing external OS
-processes [1] that are capable of handling HTTP requests for a given
+For a bit of background, CouchDB has had an API for managing `external OS
+processes`_ that are capable of handling HTTP requests for a given
URL prefix. These OS processes communicate with CouchDB using JSON over
stdio. They're dead simple to write and provide CouchDB users an easy way to
extend CouchDB functionality.
@@ -50,7 +51,7 @@ fringe benefits as well. I'm always a fan of extra awesomeness.
After hitting on the idea of adding a reverse proxy, people quickly pointed
out that it would require users to start manually managing their external
-processes using something like Runit [2] or Supervisord [3]. After some
+processes using something like `Runit`_ or `Supervisord`_. After some
more discussions I ran into people that wanted something like _externals that
didn't handle HTTP requests. After that it was easy to see that adding a second
feature that managed OS processes was the way to go.
@@ -60,26 +61,23 @@ of working but requiring more testing. In the case of the HTTP proxy I have no
tests because I can't decide how to test the thing. If you have ideas, I'd
sure like to hear them.
-[Update]: I woke up the other morning realizing that I was being an idiot and
-that Erlang is awesome. There's no reason that I can't have an HTTP client,
+**[Update]**: I woke up the other morning realizing that I was being an idiot
+and that Erlang is awesome. There's no reason that I can't have an HTTP client,
proxy, and server all hosted in the same process. So that's what I did. It
turns out to be a fairly nice way of configuring matching assertions between
the client and the server to test the proxy transmissions.
-The code for both features is in this branch:
-
- http://github.com/davisp/couchdb/tree/new_externals
-
How does it work? - HTTP Proxying
---------------------------------
-To configure a proxy handler, edit your local.ini and add a section like such:
+To configure a :ref:`proxy handler <config/proxy>`, edit your `local.ini` and
+add a section like such::
[httpd_global_handlers]
_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
-This would be approximately what you'd need to do to get CouchDB-Lucene handled
-through this interface. The URL you use to access a query would be:
+This would be approximately what you'd need to do to get `CouchDB-Lucene`_
+handled through this interface. The URL you use to access a query would be:
http://127.0.0.1:5984/_fti/db_name/_design/foo/by_content?q=hello
@@ -105,7 +103,7 @@ one instance of it is alive. If you have something where you want multiple
processes, you need to either tell CouchDB about each one, or have a main
process that forks off the required sub-processes.
-To configure an OS daemon, add this to your local.ini::
+To configure an :ref:`OS daemon <config/os_daemons>`, add this to your local.ini::
[os_daemons]
my_daemon = /path/to/command -with args
@@ -116,8 +114,8 @@ Configuration API
As an added benefit, because stdio is now free, I implemented a simple API
that OS daemons can use to read the configuration of their CouchDB host. This
way you can have them store their configuration inside CouchDB's config system
-if you desire. Or they can peek at things like the bind_address and port that
-CouchDB is using.
+if you desire. Or they can peek at things like the :ref:`bind_address
+<config/httpd/bind_address>` and port that CouchDB is using.
A request for a config section looks like this::
@@ -135,7 +133,7 @@ And the response::
"/path/to/command -with args"\n
-All requests and responses are terminated with a newline (indicated by \n).
+All requests and responses are terminated with a newline (indicated by ``\n``).
Logging API
+++++++++++
@@ -144,24 +142,26 @@ There's also an API for adding messages to CouchDB's logs. Its simply::
["log", $MESG]\n
-Where $MESG is any arbitrary JSON. There is no response from this command. As
-with the config API, the trailing "\n" represents a newline byte.
+Where ``$MESG`` is any arbitrary JSON. There is no response from this command. As
+with the config API, the trailing ``\n`` represents a newline byte.
Dynamic Daemons
+++++++++++++++
The OS daemons react in real time to changes to the configuration system. If
-you set or delete keys in the os_daemons section, the corresponding daemons
-will be started or killed as appropriate.
+you set or delete keys in the :ref:`os_daemons <config/os_daemons>` section,
+the corresponding daemons will be started or killed as appropriate.
Neat. But So What?
------------------
-It was suggested that a good first demo would be a Node.js [5] handler. So, I
+It was suggested that a good first demo would be a `Node.js`_ handler. So, I
present to you a "Hello, World" Node.js handler. Also, remember that this
-currently relies on code in my fork on GitHub [6].
+currently relies on code in my fork on `GitHub`_.
+
+File `node-hello-world.js`:
-File `node-hello-world.js`::
+.. code-block:: javascript
var http = require('http');
var sys = require('sys');
@@ -202,7 +202,9 @@ File `node-hello-world.js`::
console.log(JSON.stringify(["get", "node_hello", "port"]));
-File `local.ini` (Just add these to what you have)::
+File `local.ini` (Just add these to what you have):
+
+.. code-block:: ini
[log]
level = info
@@ -216,7 +218,9 @@ File `local.ini` (Just add these to what you have)::
[httpd_global_handlers]
_hello = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:8000">>}
-And then start CouchDB and try::
+And then start CouchDB and try:
+
+.. code-block:: bash
$ curl -v http://127.0.0.1:5984/_hello
* About to connect() to 127.0.0.1 port 5984 (#0)
@@ -247,20 +251,9 @@ The corresponding CouchDB logs look like::
[info] [<0.95.0>] Daemon "node-hello" :: GET /
-[1]: http://wiki.apache.org/couchdb/ExternalProcesses
-[2]: http://smarden.org/runit/
-[3]: http://supervisord.org/
-[4]: http://www.mikealrogers.com/
-[5]: http://nodejs.org/
-[6]: http://github.com/davisp/couchdb/tree/new_externals
-
-
-Copyright Notice
-----------------
-
-Copyright 2008-2010 Paul Joseph Davis
-
-License
--------
-
-http://creativecommons.org/licenses/by/3.0/
+.. _external OS processes: http://wiki.apache.org/couchdb/ExternalProcesses
+.. _Runit: http://smarden.org/runit/
+.. _Supervisord: http://supervisord.org/
+.. _Node.js: http://nodejs.org/
+.. _GitHub: http://github.com/davisp/couchdb/tree/new_externals
+.. _CouchDB-Lucene: https://github.com/rnewson/couchdb-lucene
[44/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Limit sections enumeration.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ebaac5cc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ebaac5cc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ebaac5cc
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: ebaac5cc519210d81ed9857d12c850b672a0cd30
Parents: 508b565
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 18 10:51:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/contents.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ebaac5cc/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
index f00aed6..700e90a 100644
--- a/share/doc/src/contents.rst
+++ b/share/doc/src/contents.rst
@@ -16,7 +16,7 @@
.. toctree::
:maxdepth: 3
- :numbered:
+ :numbered: 3
intro/index
install/index
[04/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update Views API Reference.
Remove TBC sections: better to revert with content in future than having them empty.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/233cc4f0
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/233cc4f0
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/233cc4f0
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 233cc4f00ae53942d2b738f5a4276659461bb387
Parents: b8b0773
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 15:40:52 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/views.rst | 1035 ++++++++++++++++++---------------
1 file changed, 553 insertions(+), 482 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/233cc4f0/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 1ae0a60..00aa077 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -12,125 +12,193 @@
.. _api/ddoc/view:
-.. _api/ddoc/view.get:
-``GET /db/_design/design-doc/_view/view-name``
-==============================================
-
-* **Method**: ``GET /db/_design/design-doc/_view/view-name``
-* **Request**: None
-* **Response**: JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: descending
-
- * **Description**: Return the documents in descending by key order
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: endkey
-
- * **Description**: Stop returning records when the specified key is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: endkey_docid
-
- * **Description**: Stop returning records when the specified document
- ID is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: group
-
- * **Description**: Group the results using the reduce function to a
- group or single row
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: group_level
-
- * **Description**: Specify the group level to be used
- * **Optional**: yes
- * **Type**: numeric
+``/db/_design/design-doc/_view/view-name``
+==========================================
+
+.. http:get:: /{db}/_design/{ddocname}/_view/{viewname}
+
+ Executes the specified view function from the specified design document.
+
+ :param db: Database name
+ :param ddocname: Design document name
+ :param viewname: View function name
+
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+
+ :query boolean conflicts: Includes `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``
+ :query boolean descending: Return the documents in descending by key order.
+ Default is ``false``
+ :query string endkey: Stop returning records when the specified key is
+ reached. *Optional*
+ :query string end_key: Alias for `endkey` param
+ :query string endkey_docid: Stop returning records when the specified
+ document ID is reached. *Optional*
+ :query string end_key_doc_id: Alias for `endkey_docid` param
+ :query boolean group: Group the results using the reduce function to a group
+ or single row. Default is ``false``
+ :query number group_level: Specify the group level to be used. *Optional*
+ :query boolean include_docs: Include the full content of the documents in
+ the return. Default is ``false``
+ :query boolean inclusive_end: Specifies whether the specified end key should
+ be included in the result. Default is ``true``
+ :query string key: Return only documents that match the specified key.
+ *Optional*
+ :query number limit: Limit the number of the returned documents to the
+ specified number. *Optional*
+ :query boolean reduce: Use the reduction function. Default is ``true``
+ :query number skip: Skip this number of records before starting to return
+ the results. Default is ``0``
+ :query string stale: Allow the results from a stale view to be used.
+ Supported values: ``ok`` and ``update_after``. *Optional*
+ :query string startkey: Return records starting with the specified key.
+ *Optional*
+ :query string start_key: Alias for `startkey` param
+ :query string startkey_docid: Return records starting with the specified
+ document ID. *Optional*
+ :query string start_key_doc_id: Alias for `startkey_docid` param
+ :query boolean update_seq: Response includes an ``update_seq`` value
+ indicating which sequence id of the database the view reflects.
+ Default is ``false``
+
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+
+ :>json number offset: Offset where the document list started
+ :>json array rows: Array of view row objects. By default the information
+ returned contains only the document ID and revision
+ :>json number total_rows: Number of documents in the database/view
+ :>json number update_seq: Current update sequence for the database
+
+ :code 200: Request completed successfully
+ :code 400: Invalid request
+ :code 401: Read permission required
+ :code 404: Specified database, design document or view is missed
+ :code 500: View function execution error
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/_design/ingredients/_view/by_name HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **Argument**: include_docs
+ **Response**:
- * **Description**: Include the full content of the documents in the return
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
+ .. code-block:: http
- * **Argument**: inclusive_end
+ 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/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
- * **Description**: Specifies whether the specified end key should be
- included in the result
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
+ {
+ "offset": 0,
+ "rows": [
+ {
+ "id": "SpaghettiWithMeatballs",
+ "key": "meatballs",
+ "value": 1
+ },
+ {
+ "id": "SpaghettiWithMeatballs",
+ "key": "spaghetti",
+ "value": 1
+ },
+ {
+ "id": "SpaghettiWithMeatballs",
+ "key": "tomato sauce",
+ "value": 1
+ }
+ ],
+ "total_rows": 3
+ }
- * **Argument**: key
- * **Description**: Return only documents that match the specified key
- * **Optional**: yes
- * **Type**: string
+.. http:post:: /{db}/_design/{ddocname}/_view/{viewname}
- * **Argument**: limit
+ Executes the specified view function from the specified design document.
+ Unlike the :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` method
+ for accessing views, the :http:method:`POST` method supports the specification
+ of explicit keys to be retrieved from the view results. The remainder of the
+ :http:method:`POST` view functionality is identical to the
+ :http:get:`/{db}/_design/{ddocname}/_view/{viewname}` API.
- * **Description**: Limit the number of the returned documents to the
- specified number
- * **Optional**: yes
- * **Type**: numeric
+ **Request**:
- * **Argument**: reduce
+ .. code-block:: http
- * **Description**: Use the reduction function
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
+ POST /recipes/_design/ingredients/_view/by_name HTTP/1.1
+ Accept: application/json
+ Content-Length: 37
+ Host: localhost:5984
- * **Argument**: skip
+ {
+ "keys": [
+ "meatballs",
+ "spaghetti"
+ ]
+ }
- * **Description**: Skip this number of records before starting to return
- the results
- * **Optional**: yes
- * **Type**: numeric
- * **Default**: 0
+ **Response**:
- * **Argument**: stale
+ .. code-block:: http
- * **Description**: Allow the results from a stale view to be used
- * **Optional**: yes
- * **Type**: string
- * **Default**:
- * **Supported Values**
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 09:14:13 GMT
+ ETag: "6R5NM8E872JIJF796VF7WI3FZ"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
- * **ok**: Allow stale views
+ {
+ "offset": 0,
+ "rows": [
+ {
+ "id": "SpaghettiWithMeatballs",
+ "key": "meatballs",
+ "value": 1
+ },
+ {
+ "id": "SpaghettiWithMeatballs",
+ "key": "spaghetti",
+ "value": 1
+ }
+ ],
+ "total_rows": 3
+ }
- * **Argument**: startkey
- * **Description**: Return records starting with the specified key
- * **Optional**: yes
- * **Type**: string
+.. _api/ddoc/view/options:
- * **Argument**: startkey_docid
+View Options
+------------
- * **Description**: Return records starting with the specified document ID
- * **Optional**: yes
- * **Type**: string
+There are two view indexing options that can be defined in a design document
+as boolean properties of an ``options`` object. Unlike the others querying
+options, these aren't URL parameters because they take effect when the view
+index is generated, not when it's accessed:
- * **Argument**: update_seq
+- **local_seq** (*boolean*): Makes documents' local sequence numbers available
+ to map functions (as a ``_local_seq`` document property)
+- **include_design** (*boolean*): Allows map functions to be called on design
+ documents as well as regular documents
- * **Description**: Include the update sequence in the generated results
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
+In additional to these options, you may specify :ref:`any other <api/ddoc/view>`
+with their default value. E.g. having option ``"include_docs": true`` will
+automatically includes document body for view results response. You still may
+override such by explicitly defining same query parameter name with other value.
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document.
+.. _api/ddoc/view/indexing:
Querying Views and Indexes
--------------------------
@@ -182,14 +250,13 @@ completely eliminate, these issues. These include:
either before users are allowed to use the view, or you can access
the view manually after documents are added or updated.
-- Use the ``/db/_changes`` method to monitor for changes to the
+- Use the :ref:`changes feed <api/db/changes>` to monitor for changes to the
database and then access the view to force the corresponding view
- index to be updated. See :ref:`api/db/changes` for more information.
+ index to be updated.
-- Use a monitor with the ``update_notification`` section of the CouchDB
- configuration file to monitor for changes to your database, and
- trigger a view query to force the view to be updated. For more
- information, see :ref:`update-notifications`.
+- Use a monitor with the :ref:`update notification <update-notifications>`
+ section of the CouchDB configuration file to monitor for changes to your
+ database, and trigger a view query to force the view to be updated.
None of these can completely eliminate the need for the indexes to be
rebuilt or updated when the view is accessed, but they may lessen the
@@ -206,7 +273,7 @@ For example, to access the existing stale view ``by_recipe`` in the
.. code-block:: text
- http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
+ http://localhost:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
Accessing a stale view:
@@ -230,6 +297,9 @@ which the view was generated. The returned value can be compared this to
the current update sequence exposed in the database information
(returned by :http:get:`/{db}`).
+
+.. _api/ddoc/view/sorting:
+
Sorting Returned Rows
---------------------
@@ -251,118 +321,261 @@ content. The basic order of output is as follows:
- Objects (according to the values of keys, in key order)
-You can reverse the order of the returned view information by using the
-``descending`` query value set to true. For example, Retrieving the list
-of recipes using the ``by_title`` (limited to 5 records) view:
+**Request**:
+
+.. code-block:: http
-.. code-block:: javascript
+ GET /db/_design/test/_view/sorting HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "offset" : 0,
- "rows" : [
- {
- "id" : "3-tiersalmonspinachandavocadoterrine",
- "key" : "3-tier salmon, spinach and avocado terrine",
- "value" : [
- null,
- "3-tier salmon, spinach and avocado terrine"
- ]
- },
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 10:09:25 GMT
+ ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+
+ {
+ "offset": 0,
+ "rows": [
{
- "id" : "Aberffrawcake",
- "key" : "Aberffraw cake",
- "value" : [
- null,
- "Aberffraw cake"
- ]
- },
+ "id": "dummy-doc",
+ "key": null,
+ "value": null
+ },
{
- "id" : "Adukiandorangecasserole-microwave",
- "key" : "Aduki and orange casserole - microwave",
- "value" : [
- null,
- "Aduki and orange casserole - microwave"
- ]
- },
+ "id": "dummy-doc",
+ "key": false,
+ "value": null
+ },
{
- "id" : "Aioli-garlicmayonnaise",
- "key" : "Aioli - garlic mayonnaise",
- "value" : [
- null,
- "Aioli - garlic mayonnaise"
- ]
- },
+ "id": "dummy-doc",
+ "key": true,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 0,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 1,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 10,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 42,
+ "value": null
+ },
{
- "id" : "Alabamapeanutchicken",
- "key" : "Alabama peanut chicken",
- "value" : [
- null,
- "Alabama peanut chicken"
- ]
+ "id": "dummy-doc",
+ "key": "10",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "hello",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "Hello",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "привет",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": [],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": [
+ 1,
+ 2,
+ 3
+ ],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": [
+ 2,
+ 3
+ ],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": [
+ 3
+ ],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": {},
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": {
+ "foo": "bar"
+ },
+ "value": null
}
- ],
- "total_rows" : 2667
- }
+ ],
+ "total_rows": 17
+ }
-Requesting the same in descending order will reverse the entire view
-content. For example the request
+
+You can reverse the order of the returned view information by using the
+``descending`` query value set to true:
+
+**Request**:
.. code-block:: http
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true
- Accept: application/json
- Content-Type: application/json
+ GET /db/_design/test/_view/sorting?descending=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-Returns the last 5 records from the view:
-.. code-block:: javascript
+**Response**:
- {
- "offset" : 0,
- "rows" : [
- {
- "id" : "Zucchiniinagrodolcesweet-sourcourgettes",
- "key" : "Zucchini in agrodolce (sweet-sour courgettes)",
- "value" : [
- null,
- "Zucchini in agrodolce (sweet-sour courgettes)"
- ]
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 10:09:25 GMT
+ ETag: "Z4N468R15JBT98OM0AMNSR8U"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+
+ {
+ "offset": 0,
+ "rows": [
+ {
+ "id": "dummy-doc",
+ "key": {
+ "foo": "bar"
+ },
+ "value": null
},
{
- "id" : "Zingylemontart",
- "key" : "Zingy lemon tart",
- "value" : [
- null,
- "Zingy lemon tart"
- ]
+ "id": "dummy-doc",
+ "key": {},
+ "value": null
},
{
- "id" : "Zestyseafoodavocado",
- "key" : "Zesty seafood avocado",
- "value" : [
- null,
- "Zesty seafood avocado"
- ]
+ "id": "dummy-doc",
+ "key": [
+ 3
+ ],
+ "value": null
},
{
- "id" : "Zabaglione",
- "key" : "Zabaglione",
- "value" : [
- null,
- "Zabaglione"
- ]
+ "id": "dummy-doc",
+ "key": [
+ 2,
+ 3
+ ],
+ "value": null
},
{
- "id" : "Yogurtraita",
- "key" : "Yogurt raita",
- "value" : [
- null,
- "Yogurt raita"
- ]
+ "id": "dummy-doc",
+ "key": [
+ 1,
+ 2,
+ 3
+ ],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": [],
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "привет",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "Hello",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "hello",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": "10",
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 42,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 10,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 1,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": 0,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": true,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": false,
+ "value": null
+ },
+ {
+ "id": "dummy-doc",
+ "key": null,
+ "value": null
}
- ],
- "total_rows" : 2667
- }
+ ],
+ "total_rows": 17
+ }
+
+
+Sorting order and startkey/endkey
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The sorting direction is applied before the filtering applied using the
``startkey`` and ``endkey`` query arguments. For example the following
@@ -372,27 +585,23 @@ query:
GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22
Accept: application/json
- Content-Type: application/json
-Will operate correctly when listing all the matching entries between
-“carrots” and ``egg``. If the order of output is reversed with the
+will operate correctly when listing all the matching entries between
+``carrots`` and ``egg``. If the order of output is reversed with the
``descending`` query argument, the view request will return no entries:
.. code-block:: http
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22
- Accept: application/json
- Content-Type: application/json
-The returned result is empty:
+ GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-.. code-block:: javascript
-
- {
- "total_rows" : 26453,
- "rows" : [],
- "offset" : 21882
- }
+ {
+ "total_rows" : 26453,
+ "rows" : [],
+ "offset" : 21882
+ }
The results will be empty because the entries in the view are reversed
before the key filter is applied, and therefore the ``endkey`` of “egg”
@@ -405,304 +614,166 @@ keys. Changing the previous example to:
.. code-block:: http
- GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22
- Accept: application/json
- Content-Type: application/json
-
-Specifying Start and End Values
--------------------------------
-
-.. todo:: Specifying Start and End Values
-
-The ``startkey`` and ``endkey`` query arguments can be used to specify
-the range of values to be displayed when querying the view.
-
-Using Limits and Skipping Rows
-------------------------------
-
-.. todo:: Using Limits and Skipping Rows
-
-TBC
-
-View Reduction and Grouping
----------------------------
-
-.. todo:: View Reduction and Grouping
-
-TBC
-
-.. _api/ddoc/view.post:
-
-``POST /db/_design/design-doc/_view/view-name``
-===============================================
-
-* **Method**: ``POST /db/_design/design-doc/_view/view-name``
-* **Request**: List of keys to be returned from specified view
-* **Response**: JSON of the documents returned by the view
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: descending
-
- * **Description**: Return the documents in descending by key order
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
-
- * **Argument**: endkey
-
- * **Description**: Stop returning records when the specified key is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: endkey_docid
-
- * **Description**: Stop returning records when the specified document ID
- is reached
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: group
-
- * **Description**: Group the results using the reduce function to a group
- or single row
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
+ GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **Argument**: group_level
- * **Description**: Specify the group level to be used
- * **Optional**: yes
- * **Type**: numeric
+.. _api/ddoc/view/sorting/raw:
- * **Argument**: include_docs
+Raw collation
+^^^^^^^^^^^^^
- * **Description**: Include the full content of the documents in the return
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
+By default CouchDB using `ICU`_ driver for sorting view results. It's possible
+use binary collation instead for faster view builds where Unicode collation is
+not important.
- * **Argument**: inclusive_end
+To use raw collation add ``"collation": "raw"`` key-value pair to the design
+documents ``options`` object at the root level. After that, views will be
+regenerated and new order applied.
- * **Description**: Specifies whether the specified end key should be
- included in the result
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
+.. seealso::
- * **Argument**: key
+ :ref:`views/collation`
- * **Description**: Return only documents that match the specified key
- * **Optional**: yes
- * **Type**: string
+.. _ICU: http://site.icu-project.org/
- * **Argument**: limit
+.. _api/ddoc/view/limiting:
- * **Description**: Limit the number of the returned documents to the
- specified number
- * **Optional**: yes
- * **Type**: numeric
-
- * **Argument**: reduce
-
- * **Description**: Use the reduction function
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: true
-
- * **Argument**: skip
-
- * **Description**: Skip this number of records before starting to return
- the results
- * **Optional**: yes
- * **Type**: numeric
- * **Default**: 0
-
- * **Argument**: stale
-
- * **Description**: Allow the results from a stale view to be used
- * **Optional**: yes
- * **Type**: string
- * **Default**:
- * **Supported Values**:
-
- * **ok**: Allow stale views
-
- * **Argument**: startkey
-
- * **Description**: Return records starting with the specified key
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: startkey_docid
-
- * **Description**: Return records starting with the specified document ID
- * **Optional**: yes
- * **Type**: string
-
- * **Argument**: update_seq
+Using Limits and Skipping Rows
+------------------------------
- * **Description**: Include the update sequence in the generated results
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
+By default requestion views result returns all records for it. That's ok when
+they are small, but this may lead to problems when there are billions of them
+since the clients might have to read them all and consume all available memory.
-Executes the specified ``view-name`` from the specified ``design-doc``
-design document. Unlike the ``GET`` method for accessing views, the
-``POST`` method supports the specification of explicit keys to be
-retrieved from the view results. The remainder of the ``POST`` view
-functionality is identical to the :ref:`api/ddoc/view.get` API.
+But it's possible to reduce output result rows by specifying ``limit`` query
+parameter. For example, retrieving the list of recipes using the ``by_title``
+view and limited to 5 returns only 5 records, while there are total 2667 records
+in view:
-For example, the request below will return all the recipes where the key
-for the view matches either “claret” or “clear apple cider” :
+**Request**:
.. code-block:: http
- POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
- Content-Type: application/json
-
- {
- "keys" : [
- "claret",
- "clear apple juice"
- ]
- }
-
+ GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-The returned view data contains the standard view information, but only
-where the keys match.
+**Response**:
-.. code-block:: javascript
-
- {
- "total_rows" : 26484,
- "rows" : [
- {
- "value" : [
- "Scotch collops"
- ],
- "id" : "Scotchcollops",
- "key" : "claret"
- },
- {
- "value" : [
- "Stand pie"
- ],
- "id" : "Standpie",
- "key" : "clear apple juice"
- }
- ],
- "offset" : 6324
- }
-
-Multi-document Fetching
------------------------
-
-By combining the ``POST`` method to a given view with the
-``include_docs=true`` query argument you can obtain multiple documents
-from a database. The result is more efficient than using multiple
-:http:get:`/{db}/{docid}` requests.
+.. code-block:: http
-For example, sending the following request for ingredients matching
-“claret” and “clear apple juice”:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 09:14:13 GMT
+ ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+
+ {
+ "offset" : 0,
+ "rows" : [
+ {
+ "id" : "3-tiersalmonspinachandavocadoterrine",
+ "key" : "3-tier salmon, spinach and avocado terrine",
+ "value" : [
+ null,
+ "3-tier salmon, spinach and avocado terrine"
+ ]
+ },
+ {
+ "id" : "Aberffrawcake",
+ "key" : "Aberffraw cake",
+ "value" : [
+ null,
+ "Aberffraw cake"
+ ]
+ },
+ {
+ "id" : "Adukiandorangecasserole-microwave",
+ "key" : "Aduki and orange casserole - microwave",
+ "value" : [
+ null,
+ "Aduki and orange casserole - microwave"
+ ]
+ },
+ {
+ "id" : "Aioli-garlicmayonnaise",
+ "key" : "Aioli - garlic mayonnaise",
+ "value" : [
+ null,
+ "Aioli - garlic mayonnaise"
+ ]
+ },
+ {
+ "id" : "Alabamapeanutchicken",
+ "key" : "Alabama peanut chicken",
+ "value" : [
+ null,
+ "Alabama peanut chicken"
+ ]
+ }
+ ],
+ "total_rows" : 2667
+ }
+
+To omit some records you may use ``skip`` query parameter:
+
+**Request**:
.. code-block:: http
- POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
- Content-Type: application/json
+ GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "keys" : [
- "claret",
- "clear apple juice"
- ]
- }
-
-Returns the full document for each recipe:
+**Response**:
-.. code-block:: javascript
+.. code-block:: http
- {
- "offset" : 6324,
- "rows" : [
- {
- "doc" : {
- "_id" : "Scotchcollops",
- "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178",
- "cooktime" : "8",
- "ingredients" : [
- {
- "ingredient" : "onion",
- "ingredtext" : "onion, peeled and chopped",
- "meastext" : "1"
- },
- ...
- ],
- "keywords" : [
- "cook method.hob, oven, grill@hob",
- "diet@wheat-free",
- "diet@peanut-free",
- "special collections@classic recipe",
- "cuisine@british traditional",
- "diet@corn-free",
- "diet@citrus-free",
- "special collections@very easy",
- "diet@shellfish-free",
- "main ingredient@meat",
- "occasion@christmas",
- "meal type@main",
- "diet@egg-free",
- "diet@gluten-free"
- ],
- "preptime" : "10",
- "servings" : "4",
- "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.",
- "title" : "Scotch collops",
- "totaltime" : "18"
- },
- "id" : "Scotchcollops",
- "key" : "claret",
- "value" : [
- "Scotch collops"
- ]
- },
- {
- "doc" : {
- "_id" : "Standpie",
- "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a",
- "cooktime" : "92",
- "ingredients" : [
- ... ],
- "keywords" : [
- "diet@dairy-free",
- "diet@peanut-free",
- "special collections@classic recipe",
- "cuisine@british traditional",
- "diet@corn-free",
- "diet@citrus-free",
- "occasion@buffet party",
- "diet@shellfish-free",
- "occasion@picnic",
- "special collections@lunchbox",
- "main ingredient@meat",
- "convenience@serve with salad for complete meal",
- "meal type@main",
- "cook method.hob, oven, grill@hob / oven",
- "diet@cow dairy-free"
- ],
- "preptime" : "30",
- "servings" : "6",
- "subtitle" : "Serve this pie with pickled vegetables and potato salad.",
- "title" : "Stand pie",
- "totaltime" : "437"
- },
- "id" : "Standpie",
- "key" : "clear apple juice",
- "value" : [
- "Stand pie"
- ]
- }
- ],
- "total_rows" : 26484
- }
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 09:14:13 GMT
+ ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+
+ {
+ "offset" : 2,
+ "rows" : [
+ {
+ "id" : "Adukiandorangecasserole-microwave",
+ "key" : "Aduki and orange casserole - microwave",
+ "value" : [
+ null,
+ "Aduki and orange casserole - microwave"
+ ]
+ },
+ {
+ "id" : "Aioli-garlicmayonnaise",
+ "key" : "Aioli - garlic mayonnaise",
+ "value" : [
+ null,
+ "Aioli - garlic mayonnaise"
+ ]
+ },
+ {
+ "id" : "Alabamapeanutchicken",
+ "key" : "Alabama peanut chicken",
+ "value" : [
+ null,
+ "Alabama peanut chicken"
+ ]
+ }
+ ],
+ "total_rows" : 2667
+ }
+
+.. warning::
+
+ Using ``limit`` and ``skip`` parameters is not recommended for results
+ pagination. Read :ref:`pagination recipe <views/pagination>` why it's so
+ and how to make it better.
[33/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Import introduction to the API from Guide to CouchDB.
http://guide.couchdb.org/draft/api.html
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/360381ac
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/360381ac
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/360381ac
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 360381ac07ede47ae26e80be17dcf3f75ce23ef5
Parents: 5562be1
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 7 20:44:09 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 3 +
share/doc/src/intro/api.rst | 784 +++++++++++++++++++++++++++++++++++++
share/doc/src/intro/index.rst | 5 +
3 files changed, 792 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 16ed5d6..bc4af7b 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -109,6 +109,7 @@ html_files = \
html/_sources/install/mac.txt \
html/_sources/install/unix.txt \
html/_sources/install/windows.txt \
+ html/_sources/intro/api.txt \
html/_sources/intro/consistency.txt \
html/_sources/intro/curl.txt \
html/_sources/intro/futon.txt \
@@ -222,6 +223,7 @@ html_files = \
html/install/mac.html \
html/install/unix.html \
html/install/windows.html \
+ html/intro/api.html \
html/intro/consistency.html \
html/intro/curl.html \
html/intro/futon.html \
@@ -357,6 +359,7 @@ src_files = \
../src/install/mac.rst \
../src/install/unix.rst \
../src/install/windows.rst \
+ ../src/intro/api.rst \
../src/intro/consistency.rst \
../src/intro/curl.rst \
../src/intro/futon.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
new file mode 100644
index 0000000..f617df0
--- /dev/null
+++ b/share/doc/src/intro/api.rst
@@ -0,0 +1,784 @@
+.. 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.
+
+.. default-domain:: http
+
+.. _intro/api:
+
+============
+The Core API
+============
+
+This chapter explores the CouchDB in minute detail. It shows all the
+nitty-gritty and clever bits. We show you best practices and guide you around
+common pitfalls.
+
+We start out by revisiting the basic operations we ran in the last chapter,
+looking behind the scenes. We also show what Futon needs to do behind its
+user interface to give us the nice features we saw earlier.
+
+This chapter is both an introduction to the core CouchDB API as well as a
+reference. If you can't remember how to run a particular request or why some
+parameters are needed, you can always come back here and look things up (we
+are probably the heaviest users of this chapter).
+
+While explaining the API bits and pieces, we sometimes need to take a larger
+detour to explain the reasoning for a particular request. This is a good
+opportunity for us to tell you why CouchDB works the way it does.
+
+The API can be subdivided into the following sections. We'll explore them
+individually:
+
+.. contents::
+ :depth: 1
+ :local:
+
+
+Server
+======
+
+This one is basic and simple. It can serve as a sanity check to see if
+CouchDB is running at all. It can also act as a safety guard for libraries
+that require a certain version of CouchDB. We're using the `curl`_ utility
+again::
+
+ curl http://127.0.0.1:5984/
+
+CouchDB replies, all excited to get going:
+
+.. code-block:: javascript
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
+You get back a JSON string, that, if parsed into a native object or data
+structure of your programming language, gives you access to the welcome
+string and version information.
+
+This is not terribly useful, but it illustrates nicely the way CouchDB
+behaves. You send an HTTP request and you receive a JSON string in the HTTP
+response as a result.
+
+.. _curl: http://curl.haxx.se/
+
+
+Databases
+=========
+
+Now let's do something a little more useful: *create databases*.
+For the strict, CouchDB is a *database management system* (DMS). That means it
+can hold multiple databases. A database is a bucket that holds "related data".
+We'll explore later what that means exactly. In practice, the terminology is
+overlapping -- often people refer to a DMS as "a database" and also a database
+within the DMS as "a database." We might follow that slight oddity, so don't
+get confused by it. In general, it should be clear from the context if we are
+talking about the whole of CouchDB or a single database within CouchDB.
+
+Now let's make one! We want to store our favorite music albums,
+and we creatively give our database the name albums. Note that we're now
+using the ``-X`` option again to tell curl to send a :method:`PUT` request
+instead of the default :method:`GET` request::
+
+ curl -X PUT http://127.0.0.1:5984/albums
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+That's it. You created a database and CouchDB told you that all went well.
+What happens if you try to create a database that already exists? Let's try
+to create that database again::
+
+ curl -X PUT http://127.0.0.1:5984/albums
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"error":"file_exists","reason":"The database could not be created, the file already exists."}
+
+We get back an error. This is pretty convenient. We also learn a little bit
+about how CouchDB works. CouchDB stores each database in a single file.
+Very simple.
+
+Let's create another database, this time with curl's ``-v`` (for "verbose")
+option. The verbose option tells curl to show us not only the essentials --
+the HTTP response body -- but all the underlying request and response details::
+
+ curl -vX PUT http://127.0.0.1:5984/albums-backup
+
+curl elaborates::
+
+ * About to connect() to 127.0.0.1 port 5984 (#0)
+ * Trying 127.0.0.1... connected
+ * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
+ > PUT /albums-backup HTTP/1.1
+ > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
+ > Host: 127.0.0.1:5984
+ > Accept: */*
+ >
+ < HTTP/1.1 201 Created
+ < Server: CouchDB/0.9.0 (Erlang OTP/R12B)
+ < Date: Sun, 05 Jul 2009 22:48:28 GMT
+ < Content-Type: text/plain;charset=utf-8
+ < Content-Length: 12
+ < Cache-Control: must-revalidate
+ <
+ {"ok":true}
+ * Connection #0 to host 127.0.0.1 left intact
+ * Closing connection #0
+
+What a mouthful. Let's step through this line by line to understand what's
+going on and find out what's important. Once you've seen this output a few
+times, you'll be able to spot the important bits more easily.
+
+::
+
+ * About to connect() to 127.0.0.1 port 5984 (#0)
+
+This is curl telling us that it is going to establish a TCP connection to the
+CouchDB server we specified in our request URI. Not at all important,
+except when debugging networking issues.
+
+::
+
+ * Trying 127.0.0.1... connected
+ * Connected to 127.0.0.1 (127.0.0.1) port 5984 (#0)
+
+curl tells us it successfully connected to CouchDB. Again,
+not important if you aren't trying to find problems with your network.
+
+The following lines are prefixed with ``>`` and ``<`` characters.
+The ``>`` means the line was sent to CouchDB verbatim (without the actual
+``>``). The ``<`` means the line was sent back to curl by CouchDB.
+
+::
+
+ > PUT /albums-backup HTTP/1.1
+
+This initiates an HTTP request. Its *method* is :method:`PUT`, the *URI* is
+``/albums-backup``, and the HTTP version is ``HTTP/1.1``. There is also
+``HTTP/1.0``, which is simpler in some cases, but for all practical reasons
+you should be using ``HTTP/1.1``.
+
+Next, we see a number of *request headers*. These are used to provide
+additional details about the request to CouchDB.
+
+::
+
+ > User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3
+
+The User-Agent header tells CouchDB which piece of client software is doing
+the HTTP request. We don't learn anything new: it's curl. This header is
+often useful in web development when there are known errors in client
+implementations that a server might want to prepare the response for.
+It also helps to determine which platform a user is on. This information
+can be used for technical and statistical reasons. For CouchDB, the
+:header:`User-Agent` header is irrelevant.
+
+::
+
+ > Host: 127.0.0.1:5984
+
+The :header:`Host` header is required by ``HTTP 1.1``. It tells the server
+the hostname that came with the request.
+
+::
+
+ > Accept: */*
+
+The :header:`Accept` header tells CouchDB that curl accepts any media type.
+We'll look into why this is useful a little later.
+
+::
+
+ >
+
+An empty line denotes that the request headers are now finished and the rest
+of the request contains data we're sending to the server. In this case,
+we're not sending any data, so the rest of the curl output is dedicated to
+the HTTP response.
+
+::
+
+ < HTTP/1.1 201 Created
+
+The first line of CouchDB's HTTP response includes the HTTP version
+information (again, to acknowledge that the requested version could be
+processed), an HTTP *status code*, and a *status code message*.
+Different requests trigger different response codes. There's a whole range of
+them telling the client (curl in our case) what effect the request had on the
+server. Or, if an error occurred, what kind of error. :rfc:`2616` (the HTTP 1.1
+specification) defines clear behavior for response codes. CouchDB fully
+follows the RFC.
+
+The :statuscode:`201` status code tells the client that the resource
+the request was made against was successfully created. No surprise here,
+but if you remember that we got an error message when we tried to create this
+database twice, you now know that this response could include a different
+response code. Acting upon responses based on response codes is a common
+practice. For example, all response codes of :statuscode:`400` or larger
+tell you that some error occurred. If you want to shortcut your logic and
+immediately deal with the error, you could just check a >= ``400`` response
+code.
+
+::
+
+ < Server: CouchDB/0.10.1 (Erlang OTP/R13B)
+
+The :header:`Server` header is good for diagnostics. It tells us which
+CouchDB version and which underlying Erlang version we are talking to.
+In general, you can ignore this header, but it is good to know it's there if
+you need it.
+
+::
+
+ < Date: Sun, 05 Jul 2009 22:48:28 GMT
+
+The :header:`Date` header tells you the time of the server. Since client
+and server time are not necessarily synchronized, this header is purely
+informational. You shouldn't build any critical application logic on top
+of this!
+
+::
+
+ < Content-Type: text/plain;charset=utf-8
+
+The :header:`Content-Type` header tells you which MIME type
+the HTTP response body is and its encoding. We already know CouchDB returns
+JSON strings. The appropriate :header:`Content-Type` header is
+:mimetype:`application/json`. Why do we see :mimetype:`text/plain`?
+This is where pragmatism wins over purity. Sending an
+:mimetype:`application/json` :header:`Content-Type` header will make
+a browser offer you the returned JSON for download instead of
+just displaying it. Since it is extremely useful to be able to test CouchDB
+from a browser, CouchDB sends a :mimetype:`text/plain` content type, so all
+browsers will display the JSON as text.
+
+.. note::
+
+ There are some extensions that make your browser JSON-aware,
+ but they are not installed by default. For more information, look at
+ the popular `JSONView`_ extension, available for both Firefox and Chrome.
+
+ .. _JSONView: http://jsonview.com/
+
+Do you remember the :header:`Accept` request header and how it is set to
+``\*/\* -> */*`` to express interest in any MIME type? If you send ``Accept:
+application/json`` in your request, CouchDB knows that you can deal with a pure
+JSON response with the proper :header:`Content-Type` header and will
+use it instead of :mimetype:`text/plain`.
+
+::
+
+ < Content-Length: 12
+
+The :header:`Content-Length` header simply tells us how many bytes
+the response body has.
+
+::
+
+ < Cache-Control: must-revalidate
+
+This :header:`Cache-Control` header tells you, or any proxy server between
+CouchDB and you, not to cache this response.
+
+::
+
+ <
+
+This empty line tells us we're done with the response headers and what
+follows now is the response body.
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+We've seen this before.
+
+::
+
+ * Connection #0 to host 127.0.0.1 left intact
+ * Closing connection #0
+
+The last two lines are curl telling us that it kept the TCP connection it
+opened in the beginning open for a moment, but then closed it after it
+received the entire response.
+
+Throughout the book, we'll show more requests with the ``-v`` option,
+but we'll omit some of the headers we've seen here and include only those
+that are important for the particular request.
+
+Creating databases is all fine, but how do we get rid of one? Easy -- just
+change the HTTP method::
+
+ > curl -vX DELETE http://127.0.0.1:5984/albums-backup
+
+This deletes a CouchDB database. The request will remove the file that the
+database contents are stored in. There is no *"Are you sure?"* safety net or
+any *"Empty the trash"* magic you've got to do to delete a database. Use this
+command with care. Your data will be deleted without a chance to bring it
+back easily if you don't have a backup copy.
+
+This section went knee-deep into HTTP and set the stage for discussing the
+rest of the core CouchDB API. Next stop: documents.
+
+
+Documents
+=========
+
+.. _GUID: http://en.wikipedia.org/wiki/Globally_unique_identifier
+.. _UUID: http://en.wikipedia.org/wiki/Universally_unique_identifier
+
+Documents are CouchDB's central data structure. The idea behind a document
+is, unsurprisingly, that of a real-world document -- a sheet of paper such as
+an invoice, a recipe, or a business card. We already learned that CouchDB uses
+the JSON format to store documents. Let's see how this storing works at the
+lowest level.
+
+Each document in CouchDB has an *ID*. This ID is unique per database. You are
+free to choose any string to be the ID, but for best results we recommend a
+`UUID`_ (or `GUID`_), i.e., a Universally (or Globally) Unique IDentifier.
+UUIDs are random numbers that have such a low collision probability that
+everybody can make thousands of UUIDs a minute for millions of years without
+ever creating a duplicate. This is a great way to ensure two independent people
+cannot create two different documents with the same ID. Why should you care
+what somebody else is doing? For one, that somebody else could be you at a
+later time or on a different computer; secondly, CouchDB replication lets you
+share documents with others and using UUIDs ensures that it all works.
+But more on that later; let's make some documents::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"1-2902191555"}
+
+The curl command appears complex, but let's break it down.
+First, ``-X PUT`` tells curl to make a :method:`PUT` request.
+It is followed by the URL that specifies your CouchDB IP address and port.
+The resource part of the URL ``/albums/6e1295ed6c29495e54cc05947f18c8af``
+specifies the location of a document inside our albums database.
+The wild collection of numbers and characters is a UUID. This UUID is your
+document's ID. Finally, the ``-d`` flag tells curl to use the following
+string as the body for the :method:`PUT` request. The string is a simple JSON
+structure including ``title`` and ``artist`` attributes with their respective
+values.
+
+.. note::
+
+ If you don't have a UUID handy, you can ask CouchDB to give you one (in fact,
+ that is what we did just now without showing you). Simply send a
+ :get:`/_uuids` request::
+
+ curl -X GET http://127.0.0.1:5984/_uuids
+
+ CouchDB replies:
+
+ .. code-block:: javascript
+
+ {"uuids":["6e1295ed6c29495e54cc05947f18c8af"]}
+
+ Voilà, a UUID. If you need more than one, you can pass in the ``?count=10`` HTTP
+ parameter to request 10 UUIDs, or really, any number you need.
+
+To double-check that CouchDB isn't lying about having saved your document (it
+usually doesn't), try to retrieve it by sending a GET request::
+
+ curl -X GET http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+
+We hope you see a pattern here. Everything in CouchDB has an address, a URI,
+and you use the different HTTP methods to operate on these URIs.
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}
+
+This looks a lot like the document you asked CouchDB to save, which is good.
+But you should notice that CouchDB added two fields to your JSON structure.
+The first is ``_id``, which holds the UUID we asked CouchDB to save our document
+under. We always know the ID of a document if it is included, which is very
+convenient.
+
+The second field is ``_rev``. It stands for *revision*.
+
+Revisions
+---------
+
+If you want to change a document in CouchDB, you don't tell it to go and find
+a field in a specific document and insert a new value. Instead, you load
+the full document out of CouchDB, make your changes in the JSON structure
+(or object, when you are doing actual programming), and save the entire new
+revision (or version) of that document back into CouchDB. Each revision is
+identified by a new ``_rev`` value.
+
+If you want to update or delete a document, CouchDB expects you to include
+the ``_rev`` field of the revision you wish to change. When CouchDB accepts
+the change, it will generate a new revision number. This mechanism ensures that,
+in case somebody else made a change without you knowing before you got to
+request the document update, CouchDB will not accept your update because you
+are likely to overwrite data you didn't know existed. Or simplified: whoever
+saves a change to a document first, wins. Let's see what happens if we don't
+provide a ``_rev`` field (which is equivalent to providing a outdated value)::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {"error":"conflict","reason":"Document update conflict."}
+
+If you see this, add the latest revision number of your document to the JSON
+structure::
+
+ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ -d '{"_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
+
+Now you see why it was handy that CouchDB returned that ``_rev`` when we made
+the initial request. CouchDB replies:
+
+.. code-block:: javascript
+
+ {"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"2-8aff9ee9d06671fa89c99d20a4b3ae"}
+
+CouchDB accepted your write and also generated a new revision number.
+The revision number is the *MD5 hash* of the transport representation of a
+document with an ``N-`` prefix denoting the number of times a document got
+updated. This is useful for replication. See :ref:`replication/conflicts` for
+more information.
+
+There are multiple reasons why CouchDB uses this revision system,
+which is also called Multi-Version Concurrency Control (`MVCC`_). They all work
+hand-in-hand, and this is a good opportunity to explain some of them.
+
+.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
+
+One of the aspects of the HTTP protocol that CouchDB uses is that it is
+stateless. What does that mean? When talking to CouchDB you need to make
+requests. Making a request includes opening a network connection to CouchDB,
+exchanging bytes, and closing the connection. This is done every time you
+make a request. Other protocols allow you to open a connection, exchange bytes,
+keep the connection open, exchange more bytes later -- maybe depending on the
+bytes you exchanged at the beginning -- and eventually close the connection.
+Holding a connection open for later use requires the server to do extra work.
+One common pattern is that for the lifetime of a connection, the client has
+a consistent and static view of the data on the server. Managing huge amounts
+of parallel connections is a significant amount of work. HTTP connections are
+usually short-lived, and making the same guarantees is a lot easier.
+As a result, CouchDB can handle many more concurrent connections.
+
+Another reason CouchDB uses MVCC is that this model is simpler conceptually
+and, as a consequence, easier to program. CouchDB uses less code to make this
+work, and less code is always good because the ratio of defects per lines of
+code is static.
+
+The revision system also has positive effects on replication and storage
+mechanisms, but we'll explore these later in the book.
+
+.. warning::
+
+ The terms *version* and *revision* might sound familiar (if you are
+ programming without version control, drop this book right now and start
+ learning one of the popular systems). Using new versions for document changes
+ works a lot like version control, but there's an important difference:
+ **CouchDB does not guarantee that older versions are kept around**.
+
+
+Documents in Detail
+-------------------
+
+Now let's have a closer look at our document creation requests with the curl
+``-v`` flag that was helpful when we explored the database API earlier.
+This is also a good opportunity to create more documents that we can use in
+later examples.
+
+We'll add some more of our favorite music albums. Get a fresh UUID from the
+``/_uuids`` resource. If you don't remember how that works, you can look it up
+a few pages back.
+
+::
+
+ curl -vX PUT http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
+ -d '{"title":"Blackened Sky","artist":"Biffy Clyro","year":2002}'
+
+.. note::
+
+ By the way, if you happen to know more information about your favorite
+ albums, don't hesitate to add more properties. And don't worry about not
+ knowing all the information for all the albums. CouchDB's schema-less
+ documents can contain whatever you know. After all, you should relax and not
+ worry about data.
+
+Now with the ``-v`` option, CouchDB's reply (with only the important bits shown)
+looks like this::
+
+ > PUT /albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 HTTP/1.1
+ >
+ < HTTP/1.1 201 Created
+ < Location: http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0
+ < ETag: "1-e89c99d29d06671fa0a4b3ae8aff9e"
+ <
+ {"ok":true,"id":"70b50bfa0a4b3aed1f8aff9e92dc16a0","rev":"1-e89c99d29d06671fa0a4b3ae8aff9e"}
+
+We're getting back the :statuscode:`201` HTTP status code in the response
+headers, as we saw earlier when we created a database. The :header:`Location`
+header gives us a full URL to our newly created document. And there's a new
+header. An :header:`ETag` in HTTP-speak identifies a specific version of a
+resource. In this case, it identifies a specific version (the first one) of our
+new document. Sound familiar? Yes, conceptually, an :header:`ETag` is the same
+as a CouchDB document revision number, and it shouldn't come as a surprise that
+CouchDB uses revision numbers for ETags. ETags are useful for caching
+infrastructures.
+
+
+Attachments
+-----------
+
+CouchDB documents can have attachments just like an email message can have
+attachments. An attachment is identified by a name and includes its MIME type
+(or :header:`Content-Type`) and the number of bytes the attachment
+contains. Attachments can be any data. It is easiest to think about attachments
+as files attached to a document. These files can be text, images, Word
+documents, music, or movie files. Let's make one.
+
+Attachments get their own URL where you can upload data. Say we want to add
+the album artwork to the ``6e1295ed6c29495e54cc05947f18c8af`` document
+(*"There is Nothing Left to Lose"*), and let's also say the artwork is in a file
+artwork `.jpg` in the current directory::
+
+ curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 \
+ --data-binary @artwork.jpg -H "Content-Type:image/jpg"
+
+.. note::
+
+ The ``--data-binary`` ``@`` option tells curl to read a file's contents into
+ the HTTP request body. We're using the ``-H`` option to tell CouchDB that
+ we're uploading a JPEG file. CouchDB will keep this information around and
+ will send the appropriate header when requesting this attachment; in case of
+ an image like this, a browser will render the image instead of offering you
+ the data for download. This will come in handy later. Note that you need
+ to provide the current revision number of the document you're attaching
+ the artwork to, just as if you would update the document. Because, after all,
+ attaching some data is changing the document.
+
+You should now see your artwork image if you point your browser to
+http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg
+
+If you request the document again, you'll see a new member::
+
+ curl http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+
+CouchDB replies:
+
+.. code-block:: javascript
+
+ {
+ "_id": "6e1295ed6c29495e54cc05947f18c8af",
+ "_rev": "3-131533518",
+ "title": "There is Nothing Left to Lose",
+ "artist": "Foo Fighters",
+ "year": "1997",
+ "_attachments": {
+ "artwork.jpg": {
+ "stub": true,
+ "content_type": "image/jpg",
+ "length": 52450
+ }
+ }
+ }
+
+``_attachments`` is a list of keys and values where the values are JSON objects
+containing the attachment metadata. ``stub=true`` tells us that this entry is
+just the metadata. If we use the ``?attachments=true`` HTTP option when
+requesting this document, we'd get a `Base64`_ encoded string containing the
+attachment data.
+
+.. _Base64: http://en.wikipedia.org/wiki/Base64
+
+We'll have a look at more document request options later as we explore more
+features of CouchDB, such as replication, which is the next topic.
+
+
+Replication
+===========
+
+CouchDB replication is a mechanism to synchronize databases. Much like `rsync`_
+synchronizes two directories locally or over a network, replication synchronizes
+two databases locally or remotely.
+
+.. _rsync: http://en.wikipedia.org/wiki/Rsync
+
+In a simple :method:`POST` request, you tell CouchDB the *source* and the
+*target* of a replication and CouchDB will figure out which documents and new
+document revisions are on *source* that are not yet on *target*, and will
+proceed to move the missing documents and revisions over.
+
+We'll take an in-depth look at replication later in the book; in this
+chapter, we'll just show you how to use it.
+
+First, we'll create a target database. Note that CouchDB won't automatically
+create a target database for you, and will return a replication failure if
+the target doesn't exist (likewise for the source, but that mistake isn't as
+easy to make)::
+
+ curl -X PUT http://127.0.0.1:5984/albums-replica
+
+Now we can use the database `albums-replica` as a replication target::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"albums","target":"albums-replica"}' \
+ -H "Content-Type: application/json"
+
+.. note::
+
+ CouchDB supports the option ``"create_target":true`` placed in the JSON POSTed
+ to the :ref:`_replicate <api/server/replicate>` URL. It implicitly creates
+ the target database if it doesn't exist.
+
+CouchDB replies (this time we formatted the output so you can read it more
+easily):
+
+.. code-block:: javascript
+
+ {
+ "history": [
+ {
+ "start_last_seq": 0,
+ "missing_found": 2,
+ "docs_read": 2,
+ "end_last_seq": 5,
+ "missing_checked": 2,
+ "docs_written": 2,
+ "doc_write_failures": 0,
+ "end_time": "Sat, 11 Jul 2009 17:36:21 GMT",
+ "start_time": "Sat, 11 Jul 2009 17:36:20 GMT"
+ }
+ ],
+ "source_last_seq": 5,
+ "session_id": "924e75e914392343de89c99d29d06671",
+ "ok": true
+ }
+
+CouchDB maintains a *session history* of replications. The response for a
+replication request contains the history entry for this *replication session*.
+It is also worth noting that the request for replication will stay open until
+replication closes. If you have a lot of documents, it'll take a while until
+they are all replicated and you won't get back the replication response
+until all documents are replicated. It is important to note that
+replication replicates the database only as it was at the point in time
+when replication was started. So, any additions, modifications,
+or deletions subsequent to the start of replication will not be replicated.
+
+We'll punt on the details again -- the ``"ok": true`` at the end tells us all
+went well. If you now have a look at the albums-replica database,
+you should see all the documents that you created in the albums database.
+Neat, eh?
+
+What you just did is called local replication in CouchDB terms. You created a
+local copy of a database. This is useful for backups or to keep snapshots of
+a specific state of your data around for later. You might want to do this
+if you are developing your applications but want to be able to roll back to
+a stable version of your code and data.
+
+There are more types of replication useful in other situations. The source
+and target members of our replication request are actually links (like in
+HTML) and so far we've seen links relative to the server we're working on
+(hence local). You can also specify a remote database as the target::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"albums","target":"http://example.org:5984/albums-replica"}' \
+ -H "Content-Type:application/json"
+
+Using a *local source* and a *remote target* database is called *push
+replication*. We're pushing changes to a remote server.
+
+.. note::
+
+ Since we don't have a second CouchDB server around just yet, we'll just use
+ the absolute address of our single server, but you should be able to infer
+ from this that you can put any remote server in there.
+
+This is great for sharing local changes with remote servers or buddies next
+door.
+
+You can also use a *remote source* and a *local target* to do a *pull
+replication*. This is great for getting the latest changes from a server that
+is used by others::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"http://example.org:5984/albums-replica","target":"albums"}' \
+ -H "Content-Type:application/json"
+
+Finally, you can run remote replication, which is mostly useful for management
+operations::
+
+ curl -vX POST http://127.0.0.1:5984/_replicate \
+ -d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}' \
+ -H"Content-Type: application/json"
+
+.. note::
+
+ **CouchDB and REST**
+
+ CouchDB prides itself on having a `RESTful`_ API, but these replication
+ requests don't look very RESTy to the trained eye. What's up with that?
+ While CouchDB's core database, document, and attachment API are RESTful,
+ not all of CouchDB's API is. The replication API is one example. There are
+ more, as we'll see later in the book.
+
+ Why are there RESTful and non-RESTful APIs mixed up here? Have the developers
+ been too lazy to go REST all the way? Remember, REST is an architectural
+ style that lends itself to certain architectures (such as the CouchDB
+ document API). But it is not a one-size-fits-all. Triggering an event like
+ replication does not make a whole lot of sense in the REST world. It is more
+ like a traditional remote procedure call. And there is nothing wrong with
+ this.
+
+ We very much believe in the "use the right tool for the job" philosophy,
+ and REST does not fit every job. For support, we refer to Leonard Richardson
+ and Sam Ruby who wrote `RESTful Web Services`_ (O'Reilly), as they share our
+ view.
+
+ .. _RESTful: http://en.wikipedia.org/wiki/Representational_state_transfer
+ .. _RESTful Web Services: http://oreilly.com/catalog/9780596529260
+
+
+Wrapping Up
+===========
+
+This is still not the full CouchDB API, but we discussed the essentials in
+great detail. We're going to fill in the blanks as we go. For now, we believe
+you're ready to start building CouchDB applications.
+
+.. seealso::
+
+ :ref:`Complete HTTP API Reference <api>`:
+
+ - :ref:`Server API Reference <api/server>`
+ - :ref:`Database API Reference <api/database>`
+ - :ref:`Document API Reference <api/document>`
+ - :ref:`Replication API <api/server/replicate>`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/360381ac/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
index 900dca2..a934fae 100644
--- a/share/doc/src/intro/index.rst
+++ b/share/doc/src/intro/index.rst
@@ -37,6 +37,10 @@ consistent <intro/consistency>`. And we care *a lot* about your data.
CouchDB has a fault-tolerant storage engine that puts the safety of your data
first.
+In this section you'll learn about every basic bit of CouchDB, see upon what
+conceptions and technologies it built and walk through short tutorial that
+teach how to use CouchDB.
+
.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
.. toctree::
@@ -46,5 +50,6 @@ first.
why
consistency
tour
+ api
futon
curl
[12/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
View _all_docs is map-only.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/faaf97eb
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/faaf97eb
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/faaf97eb
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: faaf97eb71ca2066351f158d156fd42c4c15ec17
Parents: 8a69a11
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Aug 17 17:14:40 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 4 ----
1 file changed, 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/faaf97eb/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index faf04c3..148da3d 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -37,9 +37,6 @@
:query string endkey_docid: Stop returning records when the specified
document ID is reached. *Optional*.
:query string end_key_doc_id: Alias for `endkey_docid` param.
- :query boolean group: Group the results using the reduce function to a group
- or single row. Default is ``false``.
- :query number group_level: Specify the group level to be used. *Optional*.
:query boolean include_docs: Include the full content of the documents in
the return. Default is ``false``.
:query boolean inclusive_end: Specifies whether the specified end key should
@@ -48,7 +45,6 @@
*Optional*.
:query number limit: Limit the number of the returned documents to the
specified number. *Optional*.
- :query boolean reduce: Use the reduction function. Default is ``true``.
:query number skip: Skip this number of records before starting to return
the results. Default is ``0``.
:query string stale: Allow the results from a stale view to be used.
[19/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Remove API tables in favor of reference index.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/c92418b6
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/c92418b6
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/c92418b6
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: c92418b635443466c8753e74da5f73d6b76a2ab6
Parents: 4884898
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 20:36:45 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/index.rst | 65 -------------------------
share/doc/src/api/document/index.rst | 28 -----------
share/doc/src/api/server/authn.rst | 13 -----
share/doc/src/api/server/configuration.rst | 18 -------
share/doc/src/api/server/index.rst | 47 ------------------
5 files changed, 171 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c92418b6/share/doc/src/api/database/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/index.rst b/share/doc/src/api/database/index.rst
index 92361e3..2441fd4 100644
--- a/share/doc/src/api/database/index.rst
+++ b/share/doc/src/api/database/index.rst
@@ -19,71 +19,6 @@ Database Methods
The Database methods provide an interface to an entire database withing
CouchDB. These are database, rather than document, level requests.
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| HEAD | /db | Checks database existence |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db | Returns database information |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db | Create a new database |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db | Delete an existing database |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/_all_docs | Returns a built-in view of all documents |
-| | | in this database |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_all_docs | Returns certain rows from the built-in |
-| | | view of all documents |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_bulk_docs | Insert multiple documents in to the |
-| | | database in a single request |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/_changes | Returns changes for the given database |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_compact | Starts a compaction for the database |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_compact/design-doc | Starts a compaction for all the views in |
-| | | the selected design document |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_ensure_full_commit | Makes sure all uncommitted changes are |
-| | | written and synchronized to the disk |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_missing_revs | Given a list of document revisions, |
-| | | returns the document revisions that do not|
-| | | exist in the database |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_purge | Purge some historical documents entirely |
-| | | from database history |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_revs_diff | Given a list of document revisions, |
-| | | returns differences between the given |
-| | | revisions and ones that are in the |
-| | | database |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/_revs_limit | Gets the limit of historical revisions to |
-| | | store for a single document in the |
-| | | database |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/_revs_limit | Sets the limit of historical revisions to |
-| | | store for a single document in the |
-| | | database |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/_security | Returns the special security object for |
-| | | the database |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/_security | Sets the special security object for the |
-| | | database |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_temp_view | Execute a given view function for all |
-| | | documents and return the result |
-+--------+-------------------------+-------------------------------------------+
-| POST | /db/_view_cleanup | Removes view files that are not used by |
-| | | any design document |
-+--------+-------------------------+-------------------------------------------+
-
For all the database methods, the database name within the URL path
should be the database name that you wish to perform the operation on.
For example, to obtain the meta information for the database
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c92418b6/share/doc/src/api/document/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/index.rst b/share/doc/src/api/document/index.rst
index 778e807..8c0460c 100644
--- a/share/doc/src/api/document/index.rst
+++ b/share/doc/src/api/document/index.rst
@@ -20,34 +20,6 @@ Document Methods
The CouchDB API Server Document methods detail how to create, read,
update and delete documents within a database.
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| POST | /db | Create a new document |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/doc | Returns the latest revision of the |
-| | | document |
-+--------+-------------------------+-------------------------------------------+
-| HEAD | /db/doc | Returns bare information in the HTTP |
-| | | Headers for the document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/doc | Inserts a new document, or new version |
-| | | of an existing document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/doc | Deletes the document |
-+--------+-------------------------+-------------------------------------------+
-| COPY | /db/doc | Copies the document |
-+--------+-------------------------+-------------------------------------------+
-| GET | /db/doc/attachment | Gets the attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/doc/attachment | Adds an attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/doc/attachment | Deletes an attachment of a document |
-+--------+-------------------------+-------------------------------------------+
-
-
.. toctree::
common
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c92418b6/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index bdf75af..0b44920 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -19,19 +19,6 @@ Authentication Methods
The CouchDB Authentication methods provide an interface for obtaining
session and authorization data.
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | /_session | Returns cookie based login user |
-| | | information |
-+--------+-------------------------+-------------------------------------------+
-| POST | /_session | Do cookie based user login |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /_session | Logout cookie based user |
-+--------+-------------------------+-------------------------------------------+
-
.. note:: We're also strongly recommend you to
:ref:`setup SSL <config/ssl>` to improve all authentication methods security.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c92418b6/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index b27d341..41270dd 100644
--- a/share/doc/src/api/server/configuration.rst
+++ b/share/doc/src/api/server/configuration.rst
@@ -20,24 +20,6 @@ The CouchDB API Server Configuration Methods provide an interface to
query and update the various configuration values within a running
CouchDB instance.
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | /_config | Obtain a list of the entire server |
-| | | configuration |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_config/section | Get all the configuration values for the |
-| | | specified section |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_config/section/key | Get a specific section/configuration value|
-+--------+-------------------------+-------------------------------------------+
-| PUT | /_config/section/key | Set the specified configuration value |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /_config/section/key | Delete the current setting |
-+--------+-------------------------+-------------------------------------------+
-
``/_config``
============
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c92418b6/share/doc/src/api/server/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/index.rst b/share/doc/src/api/server/index.rst
index fb3229f..1151bea 100644
--- a/share/doc/src/api/server/index.rst
+++ b/share/doc/src/api/server/index.rst
@@ -21,53 +21,6 @@ The CouchDB server interface provides the basic interface to a
CouchDB server for obtaining CouchDB information and getting and setting
configuration information.
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | / | Get the welcome message and version |
-| | | information |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_active_tasks | Obtain a list of the tasks running in the|
-| | | server |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_all_dbs | Get a list of all the DBs |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_config | Obtain a list of the entire server |
-| | | configuration |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_config/section | Get all the configuration values for the |
-| | | specified section |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_config/section/key | Get a specific section/config value |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /_config/section/key | Set the specified configuration value |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /_config/section/key | Delete the current setting |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_log | Return the server log file |
-+--------+-------------------------+-------------------------------------------+
-| POST | /_replicate | Set or cancel replication |
-+--------+-------------------------+-------------------------------------------+
-| POST | /_restart | Restart the server |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_session | Returns cookie based login user |
-| | | information |
-+--------+-------------------------+-------------------------------------------+
-| POST | /_session | Do cookie based user login |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /_session | Logout cookie based user |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_stats | Return server statistics |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_utils | CouchDB administration interface (Futon) |
-+--------+-------------------------+-------------------------------------------+
-| GET | /_uuids | Get generated UUIDs from the server |
-+--------+-------------------------+-------------------------------------------+
-| GET | /favicon.ico | Get the site icon |
-+--------+-------------------------+-------------------------------------------+
-
.. toctree::
common
[08/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update Document API ref.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5dbd9054
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5dbd9054
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5dbd9054
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5dbd90547905139426cd787efe154aeb70079568
Parents: 38d1a48
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Aug 15 00:50:47 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/common.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/ddoc/index.rst | 2 +-
share/doc/src/api/ddoc/views.rst | 2 +-
share/doc/src/api/document/common.rst | 1241 +++++++++++++++++---------
share/doc/src/api/document/index.rst | 3 +-
share/doc/src/api/local.rst | 8 +-
share/doc/src/config/misc.rst | 14 +
share/doc/src/replication/protocol.rst | 4 +-
10 files changed, 866 insertions(+), 414 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index ba0af48..d703ecb 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -139,7 +139,7 @@
The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :ref:`api/doc.get`
+ documents in a single request, in place of multiple :http:get:`/{db}/{docid}`
requests.
The request body should contain a list of the keys to be returned as an
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index efc3b37..dc17465 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -274,7 +274,7 @@
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Quoted new document's revision
- :>header Location: Document URI
+ :>header Location: Document's URI
:>json string id: Created document ID
:>json boolean ok: Operation status
:>json string rev: Revision info
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index eb3d740..c5ba9ce 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -74,7 +74,7 @@ The returned string will be the JSON of the design document:
A list of the revisions can be obtained by using the ``revs`` query
argument, or an extended list of revisions using the ``revs_info`` query
argument. This operates in the same way as for other documents. Fur
-further examples, see :ref:`api/doc.get`.
+further examples, see :http:get:`/{db}/{docid}`.
.. _api/ddoc.put:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/ddoc/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/index.rst b/share/doc/src/api/ddoc/index.rst
index a8049f4..12b9007 100644
--- a/share/doc/src/api/ddoc/index.rst
+++ b/share/doc/src/api/ddoc/index.rst
@@ -11,7 +11,7 @@
.. the License.
-.. _api/ddoc:
+.. _api/design-docs:
=======================
Design Document Methods
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 59b830b..1ae0a60 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -602,7 +602,7 @@ Multi-document Fetching
By combining the ``POST`` method to a given view with the
``include_docs=true`` query argument you can obtain multiple documents
from a database. The result is more efficient than using multiple
-:ref:`api/doc.get` requests.
+:http:get:`/{db}/{docid}` requests.
For example, sending the following request for ingredients matching
“claret” and “clear apple juice”:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index ff2aa65..e9ca7dc 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -11,581 +11,1018 @@
.. the License.
-.. _api/doc.get:
+.. _api/doc:
-``GET /db/doc``
-===============
+``/db/doc``
+===========
-* **Method**: ``GET /db/doc``
-* **Request**: None
-* **Response**: Returns the JSON for the document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. http:head:: /{db}/{docid}
- * **Argument**: conflicts
+ Returns the HTTP Headers containing a minimal amount of information
+ about the specified document. The method supports the same query
+ arguments as the :http:get:`/{db}/{docid}` method, but only the header
+ information (including document size, and the revision as an ETag), is
+ returned.
- * **Description**: Returns the conflict tree for the document.
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
- * **Supported Values**:
+ The :http:header:`ETag` header shows the current revision for the requested
+ document, and the :http:header:`Content-Length` specifies the length of the
+ data, if the document were requested in full.
- * **true**: Includes the revisions
+ Adding any of the query arguments (see :http:get:`/{db}/{docid}`), then the
+ resulting HTTP Headers will correspond to what would be returned.
- * **Argument**: rev
+ :param db: Database name
+ :param docid: Document ID
+ :<header If-None-Match: Double quoted document's revision token
+ :>header Content-Length: Document size
+ :>header ETag: Double quoted document's revision token
+ :code 200: Document exists
+ :code 304: Document wasn't modified since specified revision
+ :code 401: Read privilege required
+ :code 404: Document not found
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
+ **Request**:
- * **true**: Includes the revisions
+ .. code-block:: http
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
+ GET /db/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **true**: Includes the revisions
+ **Response**:
-* **Return Codes**:
+ .. code-block:: http
- * **200**:
- Document retrieved
- * **400**:
- The format of the request or revision was invalid
- * **404**:
- The specified document or revision cannot be found, or has been deleted
- * **409**:
- Conflict - a document with the specified document ID already exists
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+
+.. http:get:: /{db}/{docid}
+
+ Returns document by the specified ``docid`` from the specified ``db``.
+ Unless you request a specific revision, the latest revision of the
+ document will always be returned.
+
+ :param db: Database name
+ :param docid: Document ID
+
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`multipart/mixed`
+ - :mimetype:`text/plain`
+ :<header If-None-Match: Double quoted document's revision token
+
+ :query boolean attachments: Includes attachments bodies in response.
+ Default is ``false``
+ :query boolean att_encoding_info: Includes encoding information into
+ attachment's stubs for compressed ones. Default is ``false``
+ :query array atts_since: Includes attachments only since specified revisions.
+ Doesn't includes attachments for specified revisions. *Optional*
+ :query boolean conflicts: Includes information about conflicts in document.
+ Default is ``false``
+ :query boolean deleted_conflicts: Includes information about deleted
+ conflicted revisions. Default is ``false``
+ :query boolean latest: Forces retrieving latest "leaf" revision, no matter
+ what `rev` was requested. Default is ``false``
+ :query boolean local_seq: Includes last update sequence number for the
+ document. Default is ``false``
+ :query boolean meta: Acts same as specifying all `conflicts`,
+ `deleted_conflicts` and `open_revs` query parameters. Default is ``false``
+ :query array open_revs: Retrieves documents of specified leaf revisions.
+ Additionally, it accepts value as ``all`` to return all leaf revisions.
+ *Optional*
+ :query string rev: Retrieves document of specified revision. *Optional*
+ :query boolean revs: Includes list of all known document revisions.
+ Default is ``false``
+ :query boolean revs_info: Includes detailed information for all known
+ document revisions. Default is ``false``
+
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`multipart/mixed`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's revision token. Not available when
+ retrieving conflicts-related information
+ :>header Transfer-Encoding: ``chunked``. Available if requested with
+ query parameter ``open_revs``
+
+ :>json string _id: Document ID
+ :>json string _rev: Revision MVCC token
+ :>json boolean _deleted: Deletion flag. Available if document was removed
+ :>json object _attachments: Attachment's stubs. Available if document has
+ any attachments
+ :>json array _conflicts: List of conflicted revisions. Available if requested
+ with ``conflicts=true`` query parameter
+ :>json array _deleted_conflicts: List of deleted conflicted revisions.
+ Available if requested with ``deleted_conflicts=true`` query parameter
+ :>json number _local_seq: Document's sequence number in current database.
+ Available if requested with ``local_seq=true`` query parameter
+ :>json array _revs_info: List of objects with information about local
+ revisions and their status. Available if requested with ``open_revs`` query
+ parameter
+ :>json object _revisions: List of local revision tokens without.
+ Available if requested with ``revs=true`` query parameter
+
+ :code 200: Request completed successfully
+ :code 304: Document wasn't modified since specified revision
+ :code 400: The format of the request or revision was invalid
+ :code 401: Read privilege required
+ :code 404: Document not found
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-Returns the specified ``doc`` from the specified ``db``. For example, to
-retrieve the document with the id ``FishStew`` you would send the
-following request:
+ **Response**:
-.. code-block:: http
+ .. code-block:: http
- GET http://couchdb:5984/recipes/FishStew
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
Content-Type: application/json
- Accept: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The returned JSON is the JSON of the document, including the document ID
-and revision number:
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "1-917fa2381192822767f010b95b45325b",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-.. code-block:: javascript
+.. http:put:: /{db}/{docid}
+
+ The :http:method:`PUT` method creates a new named document, or creates a new
+ revision of the existing document. Unlike the :http:post:`/{db}` method, you
+ must specify the document ID in the request URL.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Quoted document's new revision
+ :>header Location: Document URI
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 201: Document created and stored on disk
+ :code 202: Document data accepted, but not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database or document ID doesn't exists
+ :code 409: Document with the specified ID already exists or specified
+ revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 196
+ Content-Type: application/json
+ Host: localhost:5984
{
- "_id" : "FishStew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Irish Fish Stew"
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
}
+ **Response**:
-Unless you request a specific revision, the latest revision of the
-document will always be returned.
+ .. code-block:: http
-Attachments
------------
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 20:31:39 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-If the document includes attachments, then the returned structure will
-contain a summary of the attachments associated with the document, but
-not the attachment data itself.
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
-The JSON for the returned document will include the ``_attachments``
-field, with one or more attachment definitions. For example:
-.. code-block:: javascript
+.. http:delete:: /{db}/{docid}
+
+ Deletes the specified document from the database. You must supply the
+ current (latest) revision, either by using the ``rev`` parameter to
+ specify the revision.
+
+ .. note::
+ Note that deletion of a record increments the revision number.
+ The use of a revision for deletion of the record allows replication of
+ the database to correctly track the deletion in synchronized copies.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Actual document's revision
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Document successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database or document ID doesn't exists
+ :code 409: Specified revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- "_attachments" : {
- "styling.css" : {
- "stub" : true,
- "content-type" : "text/css",
- "length" : 783426,
- },
- },
- }
+ Alternatively, instead of ``rev`` query parameter you may use
+ :http:header:`If-Match` header:
-The format of the returned JSON is shown in the table below:
+ .. code-block:: http
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_attachments** (optional): Document Attachment
+ DELETE /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ If-Match: 1-9c65296036141e575d32ba9c034dd3ee
+ Host: localhost:5984
- * **filename**: Attachment information
+ **Response**:
- * **content_type**: MIME Content type string
- * **length**: Length (bytes) of the attachment data
- * **revpos**: Revision where this attachment exists
- * **stub**: Indicates whether the attachment is a stub
+ .. code-block:: http
-Getting a List of Revisions
----------------------------
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 71
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:13 GMT
+ ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-You can obtain a list of the revisions for a given document by adding
-the ``revs=true`` parameter to the request URL. For example:
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
-.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?revs=true
+.. http:copy:: /{db}/{docid}
+
+ The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ document to a new or existing document.
+
+ The source document is specified on the request line, with the
+ :http:header:`Destination` header of the request specifying the target
+ document.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Destination: Destination document
+ :<header If-Match: Source document's revision. Alternative to `rev` query
+ parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Revision to copy from. *Optional*
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>header Location: Document's URI
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 201: Document successfully created
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Read or write privileges required
+ :code 404: Specified database, document ID or his revision doesn't exists
+ :code 409: Document with the specified ID already exists or specified
+ revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
+ Destination: SpaghettiWithMeatballs_Italian
+ Host: localhost:5984
-The returned JSON structure includes the original document, including a
-``_revisions`` structure that includes the revision information:
+ **Response**:
-.. code-block:: javascript
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
{
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "title" : "Irish Fish Stew",
- "_revisions" : {
- "ids" : [
- "a1a9b39ee3cc39181b796a69cb48521c",
- "7c4740b4dcf26683e941d6641c00c39d",
- "9c65296036141e575d32ba9c034dd3ee"
- ],
- "start" : 3
- },
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ "id": "SpaghettiWithMeatballs_Italian",
+ "ok": true,
+ "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
}
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revisions**: CouchDB Document Revisions
- * **ids** [array]: Array of valid revision IDs, in reverse order
- (latest first)
- * **start**: Prefix number for the latest revision
+.. _api/doc/attachments:
-Obtaining an Extended Revision History
---------------------------------------
+Attachments
+-----------
-You can get additional information about the revisions for a given
-document by supplying the ``revs_info`` argument to the query:
+If the document includes attachments, then the returned structure will
+contain a summary of the attachments associated with the document, but
+not the attachment data itself.
+
+The JSON for the returned document will include the ``_attachments``
+field, with one or more attachment definitions.
+
+The ``_attachments`` object keys are attachments names while values are
+information objects with next structure:
+
+- **content_type** (*string*): Attachment MIME type
+- **data** (*string*): Base64-encoded content. Available if attachment content
+ requested by using ``attachments=true`` or ``atts_since`` query parameters
+- **digest** (*string*): Content hash digest.
+ It starts with prefix which announce hash type (``md5-``) and continues with
+ Base64-encoded hash digest
+- **encoded_length** (*number*): Compressed attachment size in bytes
+ Available when query parameter ``att_encoding_info=true`` was specified and
+ ``content_type`` is in :ref:`list of compressiable types
+ <config/attachments/compressible_types>`
+- **encoding** (*string*): Compression codec. Available when query parameter
+ ``att_encoding_info=true`` was specified
+- **length** (*number*): Real attachment size in bytes. Not available if attachment
+ content requested
+- **revpos** (*number*): Revision *number* when attachment was added
+- **stub** (*boolean*): Has ``true`` value if object contains stub info and no
+ content. Otherwise omitted in response
+
+
+Basic Attachments Info
+^^^^^^^^^^^^^^^^^^^^^^
+
+**Request**:
.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?revs_info=true
- Accept: application/json
+ GET /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-This returns extended revision information, including the availability
-and status of each revision:
+**Response**:
-.. code-block:: javascript
+.. code-block:: http
- {
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "_revs_info" : [
- {
- "status" : "available",
- "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
},
- {
- "status" : "available",
- "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "length": 85,
+ "revpos": 5,
+ "stub": true
},
- {
- "status" : "available",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
}
- ],
- "title" : "Irish Fish Stew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
- }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revs_info** [array]: CouchDB Document Extended Revision Info
- * **rev**: Full revision string
- * **status**: Status of the revision
+Retrieving Attachments Content
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Obtaining a Specific Revision
------------------------------
+It's possible to retrieve document with all attached files content by using
+``attachements=true`` query parameter:
-To get a specific revision, use the ``rev`` argument to the request, and
-specify the full revision number:
+**Request**:
.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
- Accept: application/json
-
-The specified revision of the document will be returned, including a
-``_rev`` field specifying the revision that was requested:
+ GET /db/pixel?attachments=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-.. code-block:: javascript
+**Response**:
- {
- "_id" : "FishStew",
- "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Fish Stew"
- }
+.. code-block:: http
-.. _api/doc.head:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 553
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:32:40 GMT
+ ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "pixel.gif": {
+ "content_type": "image/gif",
+ "data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
+ "digest": "md5-2JdGiI2i2VELZKnwMers1Q==",
+ "revpos": 2
+ },
+ "pixel.png": {
+ "content_type": "image/png",
+ "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAAXNSR0IArs4c6QAAAANQTFRFAAAAp3o92gAAAAF0Uk5TAEDm2GYAAAABYktHRACIBR1IAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3QgOCx8VHgmcNwAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=",
+ "digest": "md5-Dgf5zxgGuchWrve73evvGQ==",
+ "revpos": 3
+ }
+ },
+ "_id": "pixel",
+ "_rev": "4-f1bcae4bf7bbb92310079e632abfe3f4"
+ }
-``HEAD /db/doc``
-================
+Or retrieve attached files content since specific revision using ``atts_since``
+query parameter:
-* **Method**: ``HEAD /db/doc``
-* **Request**: None
-* **Response**: None
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+**Request**:
- * **Argument**: rev
+.. code-block:: http
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
+ GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22] HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **Argument**: revs
+**Response**:
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
+.. code-block:: http
- * **Argument**: revs_info
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 760
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
+ },
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "data": "MS4gQ29vayBzcGFnaGV0dGkKMi4gQ29vayBtZWV0YmFsbHMKMy4gTWl4IHRoZW0KNC4gQWRkIHRvbWF0byBzYXVjZQo1LiAuLi4KNi4gUFJPRklUIQ==",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "revpos": 5
+ },
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
+ }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
-* **Return Codes**:
+Retrieving Attachments Encoding Info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * **404**:
- The specified document or revision cannot be found, or has been deleted
+By using ``att_encoding_info=true`` query parameter you may retrieve information
+about compressed attachments size and used codec.
-Returns the HTTP Headers containing a minimal amount of information
-about the specified document. The method supports the same query
-arguments as the ``GET`` method, but only the header information
-(including document size, and the revision as an ETag), is returned. For
-example, a simple ``HEAD`` request:
+**Request**:
.. code-block:: http
- HEAD http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
+ GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+**Response**:
-Returns the following HTTP Headers:
+.. code-block:: http
-.. code-block:: javascript
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 736
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "encoded_length": 693,
+ "encoding": "gzip",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
+ },
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "encoded_length": 100,
+ "encoding": "gzip",
+ "length": 85,
+ "revpos": 5,
+ "stub": true
+ },
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
+ }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
- Date: Fri, 05 Nov 2010 14:54:43 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 136
- Cache-Control: must-revalidate
-The ``Etag`` header shows the current revision for the requested
-document, and the ``Content-Length`` specifies the length of the data,
-if the document were requested in full.
+Getting a List of Revisions
+---------------------------
+
+You can obtain a list of the revisions for a given document by adding
+the ``revs=true`` parameter to the request URL:
-Adding any of the query arguments (as supported by ```GET```_ method),
-then the resulting HTTP Headers will correspond to what would be
-returned. Note that the current revision is not returned when the
-``refs_info`` argument is used. For example:
+**Request**:
.. code-block:: http
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Date: Fri, 05 Nov 2010 14:57:16 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 609
- Cache-Control: must-revalidate
-
-.. _api/doc.put:
+ GET /recipes/SpaghettiWithMeatballs?revs=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-``PUT /db/doc``
-===============
+**Response**:
-* **Method**: ``PUT /db/doc``
-* **Request**: JSON of the new document, or updated version of the existed
- document
-* **Response**: JSON of the document ID and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. code-block:: http
- * **Argument**: batch
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 584
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:38:26 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "_revisions": {
+ "ids": [
+ "6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "77fba3a059497f51ec99b9b478b569d2",
+ "136813b440a00a24834f5cb1ddf5b1f1",
+ "fd96acb3256302bf0dd2f32713161f2a",
+ "874985bc28906155ba0e2e0538f67b05",
+ "0de77a37463bf391d14283e626831f2e",
+ "d795d1b924777732fdea76538c558b62",
+ "917fa2381192822767f010b95b45325b"
+ ],
+ "start": 8
+ },
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- * **Description**: Allow document store request to be batched with others
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
- * **ok**: Enable
+The returned JSON structure includes the original document, including a
+``_revisions`` structure that includes the revision information in next form:
-* **HTTP Headers**
+- **ids** (*array*): Array of valid revision IDs, in reverse order
+ (latest first)
+- **start** (*number*): Prefix number for the latest revision
- * **Header**: ``If-Match``
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+Obtaining an Extended Revision History
+--------------------------------------
-* **Return Codes**:
+You can get additional information about the revisions for a given
+document by supplying the ``revs_info`` argument to the query:
- * **201**:
- Document has been created successfully
- * **202**:
- Document accepted for writing (batch mode)
+**Request**:
+.. code-block:: http
-The ``PUT`` method creates a new named document, or creates a new
-revision of the existing document. Unlike the ``POST`` method, you
-must specify the document ID in the request URL.
+ GET /recipes/SpaghettiWithMeatballs?revs_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-For example, to create the document ``FishStew``, you would send the
-following request:
+**Response**:
.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The return type is JSON of the status, document ID,and revision number:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 802
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:40:55 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "_revs_info": [
+ {
+ "rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "status": "available"
+ },
+ {
+ "rev": "7-77fba3a059497f51ec99b9b478b569d2",
+ "status": "deleted"
+ },
+ {
+ "rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
+ "status": "available"
+ },
+ {
+ "rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "status": "missing"
+ },
+ {
+ "rev": "4-874985bc28906155ba0e2e0538f67b05",
+ "status": "missing"
+ },
+ {
+ "rev": "3-0de77a37463bf391d14283e626831f2e",
+ "status": "missing"
+ },
+ {
+ "rev": "2-d795d1b924777732fdea76538c558b62",
+ "status": "missing"
+ },
+ {
+ "rev": "1-917fa2381192822767f010b95b45325b",
+ "status": "missing"
+ }
+ ],
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-.. code-block:: javascript
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
+The returned document contains ``_rev_info`` field with extended revision
+information, including the availability and status of each revision. This array
+field contains objects with following structure:
-Updating an Existing Document
------------------------------
+- **rev** (*string*): Full revision string
+- **status** (*string*): Status of the revision.
+ Maybe one of:
-To update an existing document you must specify the current revision
-number within the ``_rev`` parameter. For example:
+ - ``available``: Revision is available for retrieving with `rev` query
+ parameter
+ - ``missing``: Revision is not available
+ - ``deleted``: Revision belongs to deleted document
-.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
+Obtaining a Specific Revision
+-----------------------------
- {
- "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
+To get a specific revision, use the ``rev`` argument to the request, and
+specify the full revision number. The specified revision of the document will
+be returned, including a ``_rev`` field specifying the revision that was
+requested.
-Alternatively, you can supply the current revision number in the
-``If-Match`` HTTP header of the request. For example:
+**Request**:
.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
- Content-Type: application/json
+ GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
+**Response**:
-The JSON returned will include the updated revision number:
+.. code-block:: http
-.. code-block:: javascript
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 271
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:40:55 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
- {
- "id" : "FishStew99",
- "ok" : true,
- "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
- }
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-For information on batched writes, which can provide improved
-performance, see :ref:`api/doc/batch-writes`.
-.. _api/doc.delete:
+Retrieving Deleted Documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``DELETE /db/doc``
-==================
+CouchDB doesn't actually deletes documents via :http:delete:`/{db}/{docid}`.
+Instead of this, it leaves tombstone with very basic information about document.
+If you just :http:get:`/{db}/{docid}` CouchDB returns :http:statuscode:`404`
+response:
-* **Method**: ``DELETE /db/doc``
-* **Request**: None
-* **Response**: JSON of the deleted revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+**Request**:
- * **Argument**: rev
+.. code-block:: http
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
+ GET /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-* **HTTP Headers**
+**Response**:
- * **Header**: ``If-Match``
+.. code-block:: http
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+ HTTP/1.1 404 Object Not Found
+ Cache-Control: must-revalidate
+ Content-Length: 41
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:27 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-* **Return Codes**:
+ {
+ "error": "not_found",
+ "reason": "deleted"
+ }
- * **409**:
- Revision is missing, invalid or not the latest
+However, you may retrieve document's tombstone by using ``rev`` query parameter
+with :http:get:`/{db}/{docid}` request:
-Deletes the specified document from the database. You must supply the
-current (latest) revision, either by using the ``rev`` parameter to
-specify the revision:
+**Request**:
.. code-block:: http
- DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
+ GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-Alternatively, you can use ETags with the ``If-Match`` field:
+**Response**:
.. code-block:: http
- DELETE http://couchdb:5984/recipes/FishStew
- If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
-
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 79
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:30:22 GMT
+ ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The returned JSON contains the document ID, revision and status:
+ {
+ "_deleted": true,
+ "_id": "FishStew",
+ "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "4-2719fd41187c60762ff584761b714cfb"
- }
-.. note:: Note that deletion of a record increments the revision number. The
- use of a revision for deletion of the record allows replication of
- the database to correctly track the deletion in synchronized copies.
-
-.. _api/doc.copy:
-
-``COPY /db/doc``
-================
-
-* **Method**: ``COPY /db/doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
+Updating an Existing Document
+-----------------------------
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
+To update an existing document you must specify the current revision
+number within the ``_rev`` parameter.
-* **HTTP Headers**
+**Request**:
- * **Header**: ``Destination``
+.. code-block:: http
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 258
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "_rev": "1-917fa2381192822767f010b95b45325b",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs",
+ "serving": "hot"
+ }
-* **Return Codes**:
+Alternatively, you can supply the current revision number in the
+``If-Match`` HTTP header of the request:
- * **201**:
- Document has been copied and created successfully
- * **409**:
- Revision is missing, invalid or not the latest
+.. code-block:: http
-The ``COPY`` command (which is non-standard HTTP) copies an existing
-document to a new or existing document.
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 258
+ Content-Type: application/json
+ If-Match: 1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
-The source document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
+ {
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs",
+ "serving": "hot"
+ }
-Copying a Document
-------------------
-You can copy the latest version of a document to a new document by
-specifying the current document and target document:
+**Response**:
.. code-block:: http
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 20:33:56 GMT
+ ETag: "2-790895a73b63fb91dd863388398483dd"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The above request copies the document ``FishStew`` to the new document
-``IrishFishStew``. The response is the ID and revision of the new
-document.
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "2-790895a73b63fb91dd863388398483dd"
+ }
-.. code-block:: javascript
-
- {
- "id" : "IrishFishStew",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
Copying from a Specific Revision
--------------------------------
To copy *from* a specific version, use the ``rev`` argument to the query
-string:
+string or :http:header:`If-Match`:
+
+**Request**:
.. code-block:: http
- COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
- Content-Type: application/json
- Destination: IrishFishStew
+ COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Destination: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ If-Match: 1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
-The new document will be created using the information in the specified
-revision of the source document.
Copying to an Existing Document
-------------------------------
To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
+string for the target document by appending the ``rev`` parameter to the
+:http:header:`Destination` header string.
-.. code-block:: http
+**Request**:
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
+.. code-block:: http
-The return value will be the new revision of the copied document:
+ COPY /recipes/SpaghettiWithMeatballs?rev=8-6f5ad8db0f34af24a6e0984cd1a6cfb9 HTTP/1.1
+ Accept: application/json
+ Destination: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original?rev=1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
-.. code-block:: javascript
+**Response**:
- {
- "id" : "IrishFishStew",
- "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
- }
+.. code-block:: http
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "2-62e778c9ec09214dd685a981dcc24074""
+ Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "2-62e778c9ec09214dd685a981dcc24074"
+ }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/document/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/index.rst b/share/doc/src/api/document/index.rst
index d471b90..778e807 100644
--- a/share/doc/src/api/document/index.rst
+++ b/share/doc/src/api/document/index.rst
@@ -10,7 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. _api/doc:
+
+.. _api/document:
================
Document Methods
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index b08de5e..83a64cf 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -59,22 +59,22 @@ A list of the available methods and URL paths are provided below:
Gets the specified local document. The semantics are identical to
accessing a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.get`.
+ document is not replicated. See :http:get:`/{db}/{docid}`.
.. http:put:: /{db}/_local/{id}
Stores the specified local document. The semantics are identical to
storing a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.put`.
+ document is not replicated. See :http:put:`/{db}/{docid}`.
.. http:delete:: /{db}/_local/{id}
Deletes the specified local document. The semantics are identical to
deleting a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.delete`.
+ document is not replicated. See :http:delete:`/{db}/{docid}`.
.. http:copy:: /{db}/_local/{id}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.copy`.
+ document is not replicated. See :http:copy:`/{db}/{docid}`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index b373496..ffd9041 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -171,6 +171,20 @@ Available algorithms:
]
}
+.. note:: **Impact of UUID choices:**
+ The choice of UUID has a significant impact on the layout of the B-tree,
+ prior to compaction.
+
+ For example, a sequential UUID algorithm during uploading thousands of
+ documents, will avoid the need to rewrite many intermediate B-tree nodes.
+ A random UUID algorithm may require rewriting intermediate nodes on a regular
+ basis, with a corresponding decrease of throughput, and significant wasted
+ space due to the append-only B-tree design.
+
+ It is generally recommended to set your own UUIDs, or use the sequential
+ algorithm unless you have a specific need and take into account the likely
+ need for compaction to re-balance the B-tree and reclaim wasted space.
+
.. _config/uuids/utc_id_suffix:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5dbd9054/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index 0aac7a7..3aae5c1 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -164,7 +164,7 @@ Push Only
- :http:post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
Target
- :http:post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
-- :ref:`api/doc.put`?new_edits=false -- Upload a single Document with
+- :http:put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
attachments to the Target
Pull Only
@@ -179,7 +179,7 @@ Pull Only
- ``limit=limit``
- ``heartbeat=heartbeat``
-- :ref:`api/doc.get` -- Retrieve a single Document from Source with attachments.
+- :http:get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
The request uses next query parameters:
- ``open_revs=revid`` - where ``revid`` is the actual Document Revision at the
[35/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Open CouchDB maintenance section about keeping CouchDB live and well.
Import Compaction article. Source: http://wiki.apache.org/couchdb/Compaction
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6f007f86
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6f007f86
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6f007f86
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 6f007f867feb7f9cd88e63a8bef1ee883c2bfce3
Parents: 28e1b1f
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:16:11 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 6 +
share/doc/src/index.rst | 1 +
share/doc/src/maintenance/compaction.rst | 193 ++++++++++++++++++++++++++
share/doc/src/maintenance/index.rst | 20 +++
4 files changed, 220 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index bc4af7b..f59e557 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -117,6 +117,8 @@ html_files = \
html/_sources/intro/overview.txt \
html/_sources/intro/tour.txt \
html/_sources/intro/why.txt \
+ html/_sources/maintenance/compaction.txt \
+ html/_sources/maintenance/index.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -231,6 +233,8 @@ html_files = \
html/intro/overview.html \
html/intro/tour.html \
html/intro/why.html \
+ html/maintenance/compaction.html \
+ html/maintenance/index.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -367,6 +371,8 @@ src_files = \
../src/intro/overview.rst \
../src/intro/tour.rst \
../src/intro/why.rst \
+ ../src/maintenance/compaction.rst \
+ ../src/maintenance/index.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index c41cc9f..bb491de 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -21,6 +21,7 @@
intro/index
install/index
config/index
+ maintenance/index
replication/index
couchapp/index
externals
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
new file mode 100644
index 0000000..c2859bf
--- /dev/null
+++ b/share/doc/src/maintenance/compaction.rst
@@ -0,0 +1,193 @@
+.. 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.
+
+.. _compact:
+
+Compaction
+==========
+
+The `compaction` operation is the way to reduce disk space usage by removing
+unused and old data from database or view index files. This operation is a very
+similar to the `vacuum` (`SQLite`_ ex.) available for other database management
+systems.
+
+.. _SQLite: http://www.sqlite.org/lang_vacuum.html
+
+During compaction of the `target` CouchDB creates new file with the ``.compact``
+extension and transfers only actual data into. Because of this, CouchDB checks
+first for the available disk space - it should be *twice greater* than the
+compacted file's data.
+
+When all actual data successful transferred to the `compacted` file CouchDB
+*removes* the `target` replacing him with it.
+
+
+.. _compact/db:
+
+Database Compaction
+-------------------
+
+Database compaction compresses the database file by removing unused file
+sections created during updates. Old documents revisions are replaced with
+small amount of metadata called `tombstone` which are used for conflicts
+resolution during replication. The number of stored revisions
+(and their `tombstones`) can be configured by using the :http:get:`_revs_limit
+</{db}/_revs_limit>` URL endpoint.
+
+Compaction is manually triggered operation per database and runs as a background
+task. To start it for specific database there is need to send HTTP
+:http:post:`/{db}/_compact` sub-resource of the target database::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/my_db/_compact
+
+On success, HTTP status :http:statuscode:`202` is returned immediately:
+
+.. code-block:: http
+
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 19 Jun 2013 09:43:52 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+Although the request body is not used you must still specify
+:http:header:`Content-Type` header with :mimetype:`application/json` value
+for the request. If you don't, you will be aware about with HTTP status
+:http:statuscode:`415` response:
+
+.. code-block:: http
+
+ HTTP/1.1 415 Unsupported Media Type
+ Cache-Control: must-revalidate
+ Content-Length: 78
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 09:43:44 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ {"error":"bad_content_type","reason":"Content-Type must be application/json"}
+
+When the compaction is successful started and running it is possible to get
+information about it via :ref:`database information resource <api/db>`::
+
+ curl http://localhost:5984/my_db
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 246
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 16:51:20 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ {
+ "committed_update_seq": 76215,
+ "compact_running": true,
+ "data_size": 3787996,
+ "db_name": "my_db",
+ "disk_format_version": 6,
+ "disk_size": 17703025,
+ "doc_count": 5091,
+ "doc_del_count": 0,
+ "instance_start_time": "1371660751878859",
+ "purge_seq": 0,
+ "update_seq": 76215
+ }
+
+
+Note that ``compaction_running`` field is ``true`` indicating that compaction
+is actually running. To track the compaction progress you may query the
+:http:get:`_active_tasks </_active_tasks>` resource::
+
+ curl http://localhost:5984/my_db
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 175
+ Content-Type: application/json
+ Date: Wed, 19 Jun 2013 16:27:23 GMT
+ Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+
+ [
+ {
+ "changes_done": 44461,
+ "database": "my_db",
+ "pid": "<0.218.0>",
+ "progress": 58,
+ "started_on": 1371659228,
+ "total_changes": 76215,
+ "type": "database_compaction",
+ "updated_on": 1371659241
+ }
+ ]
+
+
+.. _compact/views:
+
+Views Compaction
+----------------
+
+`Views` are also need compaction like databases, unlike databases views
+are compacted by groups per `design document`. To start their compaction there
+is need to send HTTP :http:post:`/{db}/_compact/{ddoc}` request::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_compact/designname
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+This compacts the view index from the current version of the specified design
+document. The HTTP response code is :http:statuscode:`202`
+(like :ref:`compaction for databases <compact/db>`) and a compaction background
+task will be created.
+
+
+.. _compact/views/cleanup:
+
+Views cleanup
+^^^^^^^^^^^^^
+
+View indexes on disk are named after their `MD5` hash of the view definition.
+When you change a view, old indexes remain on disk. To clean up all outdated
+view indexes (files named after the MD5 representation of views, that does not
+exist anymore) you can trigger a :ref:`view cleanup <api/db/view_cleanup>`::
+
+ curl -H "Content-Type: application/json" -X POST http://localhost:5984/dbname/_view_cleanup
+
+.. code-block:: javascript
+
+ {"ok":true}
+
+
+.. _compact/auto:
+
+Automatic Compaction
+--------------------
+
+While both :ref:`database <compact/db>` and :ref:`views <compact/views>`
+compactions are required be manually triggered, it is also possible to configure
+automatic compaction, so that compaction of databases and views is automatically
+triggered based on various criteria. Automatic compaction is configured in
+CouchDB's :ref:`configuration files <config/intro>`.
+
+The :ref:`compaction daemon <config/daemons/compaction_daemon>` is responsible
+for triggering the compaction. It is automatically started, but disabled by
+default. The criteria for triggering the compactions is configured in the
+:ref:`compactions <config/compactions>` section.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f007f86/share/doc/src/maintenance/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/index.rst b/share/doc/src/maintenance/index.rst
new file mode 100644
index 0000000..86cc761
--- /dev/null
+++ b/share/doc/src/maintenance/index.rst
@@ -0,0 +1,20 @@
+.. 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.
+
+
+===================
+CouchDB Maintenance
+===================
+
+.. toctree::
+
+ compaction
[09/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update Attachments API reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5cf93067
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5cf93067
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5cf93067
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5cf93067b80b521aef65107c9320c8715db665d3
Parents: 1ec0b0b
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Aug 17 16:15:32 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/document/attachments.rst | 398 ++++++++++++++----------
1 file changed, 236 insertions(+), 162 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5cf93067/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 4af8e8c..b3bb538 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -12,21 +12,245 @@
.. _api/doc/attachment:
-.. _api/doc/attachment.get:
-``GET /db/doc/attachment``
-==========================
+``/db/doc/attachment``
+======================
+
+.. http:head:: /{db}/{docid}/{attname}
+
+ Returns the HTTP headers containing a minimal amount of information
+ about the specified attachment. The method supports the same query
+ arguments as the :http:get:`/{db}/{docid}/{attname}` method, but only
+ the header information (including attachment size, encoding and the MD5 hash
+ as an :http:header:`ETag`), is returned.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
+ *Optional*
+ :query string rev: Document's revision. *Optional*
+ :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
+ Used for attachments with :mimetype:`application/octet-stream` content type
+ :>header Content-Encoding: Used compression codec. Available if attachment's
+ ``content_type`` is in :ref:`list of compressiable types
+ <config/attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec was used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :code 200: Attachment exists
+ :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
+ :http:header:`If-None-Match` header
+ :code 401: Read privilege required
+ :code 404: Specified database, document or attachment was not found
+
+ **Request**:
+
+ .. code-block:: http
+
+ HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Accept-Ranges: none
+ Cache-Control: must-revalidate
+ Content-Encoding: gzip
+ Content-Length: 100
+ Content-MD5: vVa/YgiE1+Gh0WfoFJAcSg==
+ Content-Type: text/plain
+ Date: Thu, 15 Aug 2013 12:42:42 GMT
+ ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+
+.. http:get:: /{db}/{docid}/{attname}
+
+ Returns the file attachment associated with the document.
+ The raw data of the associated attachment is returned (just as if you were
+ accessing a static file. The returned :http:header:`Content-Type`
+ will be the same as the content type set when the document attachment
+ was submitted into the database.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
+ *Optional*
+ :query string rev: Document's revision. *Optional*
+ :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
+ Used for attachments with :mimetype:`application/octet-stream`
+ :>header Content-Encoding: Used compression codec. Available if attachment's
+ ``content_type`` is in :ref:`list of compressiable types
+ <config/attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec is used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :response: Stored content
+ :code 200: Attachment exists
+ :code 304: Attachment wasn't modified if :http:header:`ETag` equals specified
+ :http:header:`If-None-Match` header
+ :code 401: Read privilege required
+ :code 404: Specified database, document or attachment was not found
+
+
+.. http:put:: /{db}/{docid}/{attname}
+
+ Uploads the supplied content as an attachment to the specified document.
+ The attachment name provided must be a URL encoded string. You must also
+ supply either the ``rev`` query argument or the :http:header:`If-Match`
+ HTTP header for validation, and the HTTP headers (to set the attachment
+ content type).
+
+ If case when uploading an attachment using an existing attachment name,
+ CouchDB will update the corresponding stored content of the database.
+ Since you must supply the revision information to add an attachment to
+ the document, this serves as validation to update the existing attachment.
+
+ .. note::
+ Uploading an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual attachments.
+
+ :param db: Database name
+ :param docid: Document ID
+ :param attname: Attachment name
+ :<header Content-Type: Attachment MIME type. *Required*
+ :<header If-Match: Document revision. Alternative to `rev` query parameter
+ :query string rev: Document revision. *Required*
+ :>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
+ Used for attachments with :mimetype:`application/octet-stream`
+ :>header Content-Encoding: Used compression codec. Available if attachment's
+ ``content_type`` is in :ref:`list of compressiable types
+ <config/attachments/compressible_types>`
+ :>header Content-Length: Attachment size. If compression codec is used,
+ this value is about compressed size, not actual
+ :>header Content-MD5: Base64 encoded MD5 binary digest
+ :>header ETag: Double quoted base64 encoded MD5 binary digest
+ :>json string id: Document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Attachment successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database, document or attachment was not found
+ :code 409: Document's revision wasn't specified or it's not the latest
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
+ Accept: application/json
+ Content-Length: 86
+ Content-Type: text/plain
+ Host: localhost:5984
+ If-Match: 1-917fa2381192822767f010b95b45325b
+
+ 1. Cook spaghetti
+ 2. Cook meatballs
+ 3. Mix them
+ 4. Add tomato sauce
+ 5. ...
+ 6. PROFIT!
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Thu, 15 Aug 2013 12:38:04 GMT
+ ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "2-ce91aed0129be8f9b0f650a2edcfd0a4"
+ }
+
-* **Method**: ``GET /db/doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
+.. http:delete:: /{db}/{docid}/{attname}
+
+ Deletes the attachment ``attachment`` of the specified ``doc``. You must
+ supply the ``rev`` query parameter or :http:header:`If-Match` with the current
+ revision to delete the attachment.
+
+ .. note::
+ Deleting an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual attachments.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header If-Match: Document revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Document revision. *Required*
+ :query string batch: Store changes in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>json string id: Document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Attachment successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database, document or attachment was not found
+ :code 409: Document's revision wasn't specified or it's not the latest
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ Alternatively, instead of ``rev`` query parameter you may use
+ :http:header:`If-Match` header:
+
+ .. code-block:: http
+
+ DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ If-Match: 6-440b2dd39c20413045748b42c6aba6e2
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:13 GMT
+ ETag: "7-05185cf5fcdf4b6da360af939431d466"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "7-05185cf5fcdf4b6da360af939431d466"
+ }
-Returns the file attachment ``attachment`` associated with the document
-``doc``. The raw data of the associated attachment is returned (just as
-if you were accessing a static file. The returned HTTP ``Content-type``
-will be the same as the content type set when the document attachment
-was submitted into the database.
.. _api/doc/attachment/range:
@@ -90,153 +314,3 @@ ranges. Read all about it in `RFC 2616`_.
better algorithm to find byte ranges.
.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
-
-
-.. _api/doc/attachment.put:
-
-``PUT /db/doc/attachment``
-==========================
-
-* **Method**: ``PUT /db/doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Content-Length``
-
- * **Description**: Length (bytes) of the attachment being uploaded
- * **Optional**: no
-
- * **Header**: ``Content-Type``
-
- * **Description**: MIME type for the uploaded attachment
- * **Optional**: no
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **201**:
- Attachment has been accepted
-
-Upload the supplied content as an attachment to the specified document
-(``doc``). The ``attachment`` name provided must be a URL encoded
-string. You must also supply either the ``rev`` query argument or the
-``If-Match`` HTTP header for validation, and the HTTP headers (to set
-the attachment content type). The content type is used when the
-attachment is requested as the corresponding content-type in the
-returned document header.
-
-For example, you could upload a simple text document using the following
-request:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
- Content-Length: 10
- Content-Type: text/plain
-
- Roast it
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic
- If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
- Content-Length: 10
- Content-Type: text/plain
-
- Roast it
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
- }
-
-.. note:: Uploading an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual
- attachments.
-
-Updating an Existing Attachment
--------------------------------
-
-Uploading an attachment using an existing attachment name will update
-the corresponding stored content of the database. Since you must supply
-the revision information to add an attachment to a document, this serves
-as validation to update the existing attachment.
-
-.. _api/doc/attachment.delete:
-
-``DELETE /db/doc/attachment``
-=============================
-
-* **Method**: ``DELETE /db/doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **200**:
- Attachment deleted successfully
- * **409**:
- Supplied revision is incorrect or missing
-
-Deletes the attachment ``attachment`` to the specified ``doc``. You must
-supply the ``rev`` argument with the current revision to delete the
-attachment.
-
-For example to delete the attachment ``basic`` from the recipe
-``FishStew``:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
- Content-Type: application/json
-
-
-
-The returned JSON contains the updated revision information:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
- }
-
-.. _JSON object: #table-couchdb-api-db_db-json-changes
-.. _POST: #couchdb-api-dbdoc_db_post
[18/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Fix dead reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ebaf890f
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ebaf890f
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ebaf890f
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: ebaf890f7929fbc120335a9ef32608dd65330a76
Parents: c92418b
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 20:43:29 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/replication/conflicts.rst | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ebaf890f/share/doc/src/replication/conflicts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/conflicts.rst b/share/doc/src/replication/conflicts.rst
index 404d256..d0149b0 100644
--- a/share/doc/src/replication/conflicts.rst
+++ b/share/doc/src/replication/conflicts.rst
@@ -109,9 +109,10 @@ Conflict avoidance
==================
When working on a single node, CouchDB will avoid creating conflicting revisions
-by returning a 409 HTTP error. This is because, when you PUT a new version of a
-document, you must give the ``_rev`` of the previous version. If that ``_rev``
-has already been superseded, the update is rejected with a ``HTTP 409 Conflict``.
+by returning a :http:statuscode:`409` error. This is because, when you
+PUT a new version of a document, you must give the ``_rev`` of the previous
+version. If that ``_rev`` has already been superseded, the update is rejected
+with a :http:statuscode:`409` response.
So imagine two users on the same node are fetching Bob's business card, updating
it concurrently, and writing it back:
@@ -237,7 +238,7 @@ arbitrarily large.
Working with conflicting documents
==================================
-The basic :ref:`GET /db/bob <api/doc.get>` operation will not show you any
+The basic :http:get:`/{doc}/{docid}` operation will not show you any
information about conflicts. You see only the deterministically-chosen winner,
and get no indication as to whether other conflicting revisions exist or not:
[42/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
fix problem when LOCAL_VERSION_RELEASE isn't set
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fe961f83
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fe961f83
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fe961f83
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: fe961f83816d3da5d8e03c98ef07b0fc06536454
Parents: 9454b50
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 11:52:59 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe961f83/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index bfdcd99..f60e545 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -51,7 +51,7 @@ release = '.'.join([
_info['LOCAL_VERSION_REVISION']
]) + (
_info['LOCAL_VERSION_STAGE'] + '' + _info['LOCAL_VERSION_RELEASE']
- if _info['LOCAL_VERSION_RELEASE'] == '%revision%'
+ if _info.get('LOCAL_VERSION_RELEASE') == '%revision%'
else '-dev'
)
[10/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update base DDoc API referece.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9947e588
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9947e588
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9947e588
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 9947e5888a58bc558bbd71296f594e898a2ffac5
Parents: e475c72
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 15:21:40 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/common.rst | 524 ++++++++----------------------
share/doc/src/query-server/index.rst | 1 +
2 files changed, 139 insertions(+), 386 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9947e588/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index c5ba9ce..0d6ec17 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -11,454 +11,206 @@
.. the License.
-.. _api/ddoc.get:
+.. _api/ddoc:
-``GET /db/_design/design-doc``
-==============================
+``/db/_design/design-doc``
+==========================
-* **Method**: ``GET /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the existing design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. http:head:: /{db}/_design/{ddocname}
- * **Argument**: rev
+ Returns the HTTP Headers containing a minimal amount of information
+ about the specified design document.
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
+ .. seealso::
- * **Argument**: revs
+ :http:head:`/{db}/{docid}`
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
- * **true**: Includes the revisions
+.. http:get:: /{db}/_design/{ddocname}
- * **Argument**: revs_info
+ Returns design document with the specified design document` from the specified
+ database. Unless you request a specific revision, the latest revision of the
+ document will always be returned.
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
+ .. seealso::
- * **true**: Includes the revisions
+ :http:get:`/{db}/{docid}`
-Returns the specified design document, ``design-doc`` from the specified
-``db``. For example, to retrieve the design document ``recipes`` you
-would send the following request:
-.. code-block:: http
+.. http:put:: /{db}/_design/{ddocname}
- GET http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
-
-The returned string will be the JSON of the design document:
-
-.. code-block:: javascript
-
- {
- "_id" : "_design/recipes",
- "_rev" : "5-39f56a392b86bbee57e2138921346406"
- "language" : "javascript",
- "views" : {
- "by_recipe" : {
- "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
- },
- },
- }
-
-A list of the revisions can be obtained by using the ``revs`` query
-argument, or an extended list of revisions using the ``revs_info`` query
-argument. This operates in the same way as for other documents. Fur
-further examples, see :http:get:`/{db}/{docid}`.
-
-.. _api/ddoc.put:
-
-``PUT /db/_design/design-doc``
-==============================
-
-* **Method**: ``PUT /db/_design/design-doc``
-* **Request**: JSON of the design document
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-
-Upload the specified design document, ``design-doc``, to the specified
-database. The design document should follow the definition of a design
-document, as summarised in the following table.
-
-* **_id**: Design Document ID
-* **_rev**: Design Document Revision
-* **views**: View
-
- * **viewname**: View Definition
-
- * **map**: Map Function for View
- * **reduce (optional)**: Reduce Function for View
-
-For more information on writing views, see :ref:`api/ddoc/view`.
-
-.. _api/ddoc.delete:
-
-``DELETE /db/_design/design-doc``
-=================================
-
-* **Method**: ``DELETE /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of deleted design document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``If-Match``
-
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
-
-* **Return Codes**:
-
- * **409**:
- Supplied revision is incorrect or missing
-
-Delete an existing design document. Deleting a design document also
-deletes all of the associated view indexes, and recovers the
-corresponding space on disk for the indexes in question.
-
-To delete, you must specify the current revision of the design document
-using the ``rev`` query argument.
-
-For example:
-
-.. code-block:: http
-
- DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
- Content-Type: application/json
-
-The response contains the delete document ID and revision:
-
-.. code-block:: javascript
-
- {
- "id" : "recipe/_design/recipes"
- "ok" : true,
- "rev" : "3-7a05370bff53186cb5d403f861aca154",
- }
-
-.. _api/ddoc.copy:
-
-``COPY /db/_design/design-doc``
-===============================
-
-* **Method**: ``COPY /db/_design/design-doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Destination``
-
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
-
-The ``COPY`` command (non-standard HTTP) copies an existing design
-document to a new or existing document.
-
-The source design document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
+ The :http:method:`PUT` method creates a new named design document, or creates
+ a new revision of the existing design document.
-Copying a Design Document
--------------------------
+ The design documents have some agreement upon their fields and structure.
+ Currently it is the next:
-To copy the latest version of a design document to a new document you
-specify the base document and target document:
+ * **language** (*string*): Defines :ref:`Query Server <query-server>`
+ :ref:`key <config/query_servers>` to process design document functions
+ * **options** (*object*): View's default options
+ * **filters** (*object*): :ref:`Filter functions <filterfun>` definition
+ * **lists** (*object*): :ref:`List functions <listfun>` definition
+ * **rewrites** (*array*): Rewrite rules definition
+ * **shows** (*object*): :ref:`Show functions <showfun>` definition
+ * **updates** (*object*): :ref:`Update functions <updatefun>` definition
+ * **validate_doc_update** (*string*): :ref:`Validate document update <vdufun>`
+ function source
+ * **views** (*object*): :ref:`View functions <viewfun>` definition.
-.. code-block:: http
+ Note, that for ``filters``, ``lists``, ``shows`` and ``updates`` fields
+ objects are mapping of function name to string function source code.
+ For ``views`` mapping is the same except that values are objects with ``map``
+ and ``reduce`` (optional) keys which also contains functions source code.
- COPY http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
- Destination: /recipes/_design/recipelist
-
-The above request copies the design document ``recipes`` to the new
-design document ``recipelist``. The response is the ID and revision of
-the new document.
-
-.. code-block:: javascript
-
- {
- "id" : "recipes/_design/recipelist"
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
- }
+ .. seealso::
-.. note::
- Copying a design document does automatically reconstruct the view
- indexes. These will be recreated, as with other views, the first
- time the new view is accessed.
+ :http:put:`/{db}/{docid}`
-Copying from a Specific Revision
---------------------------------
-To copy *from* a specific version, use the ``rev`` argument to the query
-string:
+.. http:delete:: /{db}/_design/{ddocname}
-.. code-block:: http
+ Deletes the specified document from the database. You must supply the
+ current (latest) revision, either by using the ``rev`` parameter to
+ specify the revision.
- COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
- Content-Type: application/json
- Destination: recipes/_design/recipelist
-
-The new design document will be created using the specified revision of
-the source document.
+ .. seealso::
-Copying to an Existing Design Document
---------------------------------------
+ :http:delete:`/{db}/{docid}`
-To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
+.. http:copy:: /{db}/_design/{ddocname}
-.. code-block:: http
+ The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ design document to a new or existing one.
- COPY http://couchdb:5984/recipes/_design/recipes
- Content-Type: application/json
- Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
+ .. note::
+ Copying a design document does automatically reconstruct the view
+ indexes. These will be recreated, as with other views, the first
+ time the new view is accessed.
-The return value will be the new revision of the copied document:
+ .. seealso::
-.. code-block:: javascript
+ :http:copy:`/{db}/{docid}`
- {
- "id" : "recipes/_design/recipes"
- "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
- }
.. _api/ddoc/attachment:
-.. _api/ddoc/attachment.get:
-
-``GET /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``GET /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: Returns the attachment data
-* **Admin Privileges Required**: no
-
-Returns the file attachment ``attachment`` associated with the design
-document ``/_design_/design-doc``. The raw data of the associated
-attachment is returned (just as if you were accessing a static file. The
-returned HTTP ``Content-type`` will be the same as the content type set
-when the document attachment was submitted into the database.
-
-.. _api/ddoc/attachment.put:
-
-``PUT /db/_design/design-doc/attachment``
-=========================================
-
-* **Method**: ``PUT /db/_design/design-doc/attachment``
-* **Request**: Raw document data
-* **Response**: JSON document status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
-
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
-
-* **HTTP Headers**
-
- * **Header**: ``Content-Length``
-
- * **Description**: Length (bytes) of the attachment being uploaded
- * **Optional**: no
-
- * **Header**: ``Content-Type``
- * **Description**: MIME type for the uploaded attachment
- * **Optional**: no
+``/db/_design/design-doc/attachment``
+=====================================
- * **Header**: ``If-Match``
+.. http:head:: /{db}/_design/{ddocname}/{attname}
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+ Returns the HTTP headers containing a minimal amount of information
+ about the specified attachment.
-Upload the supplied content as an attachment to the specified design
-document (``/_design/design-doc``). The ``attachment`` name provided
-must be a URL encoded string. You must also supply either the ``rev``
-query argument or the ``If-Match`` HTTP header for validation, and the
-HTTP headers (to set the attachment content type). The content type is
-used when the attachment is requested as the corresponding content-type
-in the returned document header.
+ .. seealso::
-For example, you could upload a simple text document using the following
-request:
+ :http:head:`/{db}/{docid}/{attname}`
-.. code-block:: http
+.. http:get:: /{db}/_design/{ddocname}/{attname}
- PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
- Content-Length: 39
- Content-Type: text/plain
+ Returns the file attachment associated with the design document.
+ The raw data of the associated attachment is returned (just as if you were
+ accessing a static file.
- div.recipetitle {
- font-weight: bold;
- }
-
-Or by using the ``If-Match`` HTTP header:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes/FishStew/basic
- If-Match: 7-f7114d4d81124b223283f3e89eee043e
- Content-Length: 39
- Content-Type: text/plain
-
- div.recipetitle {
- font-weight: bold;
- }
-
-The returned JSON contains the new document information:
-
-.. code-block:: javascript
-
- {
- "id" : "_design/recipes"
- "ok" : true,
- "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
- }
-
-.. note::
- Uploading an attachment updates the corresponding document revision.
- Revisions are tracked for the parent document, not individual attachments.
+ .. seealso::
-.. _api/ddoc/attachment.delete:
+ :http:get:`/{db}/{docid}/{attname}`
-``DELETE /db/_design/design-doc/attachment``
-============================================
+.. http:put:: /{db}/_design/{ddocname}/{attname}
-* **Method**: ``DELETE /db/_design/design-doc/attachment``
-* **Request**: None
-* **Response**: JSON status
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+ Uploads the supplied content as an attachment to the specified design
+ document. The attachment name provided must be a URL encoded string.
- * **Argument**: rev
+ .. seealso::
- * **Description**: Current document revision
- * **Optional**: no
- * **Type**: string
+ :http:put:`/{db}/{docid}/{attname}`
-* **HTTP Headers**
+.. http:delete:: /{db}/_design/{ddocname}/{attname}
- * **Header**: ``If-Match``
+ Deletes the attachment of the specified design document.
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+ .. seealso::
-* **Return Codes**:
+ :http:delete:`/{db}/{docid}/{attname}`
- * **200**:
- Attachment deleted successfully
- * **409**:
- Supplied revision is incorrect or missing
-Deletes the attachment ``attachment`` to the specified
-``_design/design-doc``. You must supply the ``rev`` argument with the
-current revision to delete the attachment.
-
-For example to delete the attachment ``view.css`` from the design
-document ``recipes``:
-
-.. code-block:: http
+.. _api/ddoc/info:
- DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
+``/db/_design/design-doc/_info``
+================================
-The returned JSON contains the updated revision information for the
-parent document:
+.. http:get:: /{db}/_design/{ddocname}/_info
-.. code-block:: javascript
+ Obtains information about the specified design document, including the index,
+ index size and current status of the design document and associated
+ index information.
- {
- "id" : "_design/recipes"
- "ok" : true,
- "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
- }
+ :param db: Database name
+ :param ddocname: Design document name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json string name: Design document name
+ :>json object view_index: :ref:`api/ddoc/view_index_info`
+ :code 200: Request completed successfully
+ **Request**:
-.. _api/ddoc/info:
-.. _api/ddoc/info.get:
+ .. code-block:: http
-``GET /db/_design/design-doc/_info``
-====================================
+ GET /recipes/_design/recipe/_info HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-* **Method**: ``GET /db/_design/design-doc/_info``
-* **Request**: None
-* **Response**: JSON of the design document information
-* **Admin Privileges Required**: no
+ **Response**:
-Obtains information about a given design document, including the index,
-index size and current status of the design document and associated
-index information.
+ .. code-block:: http
-For example, to get the information for the ``recipes`` design document:
-
-.. code-block:: http
-
- GET http://couchdb:5984/recipes/_design/recipes/_info
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 263
Content-Type: application/json
-
-This returns the following JSON structure:
-
-.. code-block:: javascript
+ Date: Sat, 17 Aug 2013 12:54:17 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
{
- "name" : "recipes"
- "view_index" : {
- "compact_running" : false,
- "updater_running" : false,
- "language" : "javascript",
- "purge_seq" : 10,
- "waiting_commit" : false,
- "waiting_clients" : 0,
- "signature" : "fc65594ee76087a3b8c726caf5b40687",
- "update_seq" : 375031,
- "disk_size" : 16491
- },
+ "name": "recipe",
+ "view_index": {
+ "compact_running": false,
+ "data_size": 926691,
+ "disk_size": 1982704,
+ "language": "python",
+ "purge_seq": 0,
+ "signature": "a59a1bb13fdf8a8a584bc477919c97ac",
+ "update_seq": 12397,
+ "updater_running": false,
+ "waiting_clients": 0,
+ "waiting_commit": false
+ }
}
-The individual fields in the returned JSON structure are detailed below:
-
-* **name**: Name/ID of Design Document
-* **view_index**: View Index
-
- * **compact_running**: Indicates whether a compaction routine is currently
- running on the view
- * **disk_size**: Size in bytes of the view as stored on disk
- * **language**: Language for the defined views
- * **purge_seq**: The purge sequence that has been processed
- * **signature**: MD5 signature of the views for the design document
- * **update_seq**: The update sequence of the corresponding database that
- has been indexed
- * **updater_running**: Indicates if the view is currently being updated
- * **waiting_clients**: Number of clients waiting on views from this design
- document
- * **waiting_commit**: Indicates if there are outstanding commits to the
- underlying database that need to processed
+
+.. _api/ddoc/view_index_info:
+
+View Index Information
+----------------------
+
+The response from :http:get:`/{db}/_design/{ddocname}/_info` contains
+``view_index`` (*object*) field with the next structure:
+
+* **compact_running** (*boolean*): Indicates whether a compaction routine
+ is currently running on the view
+* **data_size** (*number*): Actual size in bytes of the view
+* **disk_size** (*number*): Size in bytes of the view as stored on disk
+* **language** (*string*): Language for the defined views
+* **purge_seq** (*number*): The purge sequence that has been processed
+* **signature** (*string*): MD5 signature of the views for the design document
+* **update_seq** (*number*): The update sequence of the corresponding database
+ that has been indexed
+* **updater_running** (*boolean*): Indicates if the view is currently
+ being updated
+* **waiting_clients** (*number*): Number of clients waiting on views from
+ this design document
+* **waiting_commit** (*boolean*): Indicates if there are outstanding commits
+ to the underlying database that need to processed
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9947e588/share/doc/src/query-server/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/index.rst b/share/doc/src/query-server/index.rst
index b16e0ac..835ba1b 100644
--- a/share/doc/src/query-server/index.rst
+++ b/share/doc/src/query-server/index.rst
@@ -10,6 +10,7 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. _query-server:
============
Query Server
[30/50] [abbrv] Better introduction into CouchDB.
Posted by kx...@apache.org.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/tour.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/tour.rst b/share/doc/src/intro/tour.rst
new file mode 100644
index 0000000..af91f5e
--- /dev/null
+++ b/share/doc/src/intro/tour.rst
@@ -0,0 +1,534 @@
+.. 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.
+
+
+.. _intro/tour:
+
+===============
+Getting Started
+===============
+
+In this chapter, we'll take a quick tour of CouchDB's features,
+familiarizing ourselves with Futon, the built-in administration interface.
+We'll create our first document and experiment with CouchDB views.
+
+
+All Systems Are Go!
+===================
+
+We'll have a very quick look at CouchDB's bare-bones Application Programming
+Interface (API) by using the command-line utility curl. Please note that this
+is not the only way of talking to CouchDB. We will show you plenty more
+throughout the rest of the book. What's interesting about curl is that it
+gives you control over raw HTTP requests, and you can see exactly what is
+going on "underneath the hood" of your database.
+
+Make sure CouchDB is still running, and then do::
+
+ curl http://127.0.0.1:5984/
+
+This issues a GET request to your newly installed CouchDB instance.
+
+The reply should look something like:
+
+.. code-block:: javascript
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "version": "1.4.0",
+ "vendor": {
+ "version": "1.4.0",
+ "name": "The Apache Software Foundation"
+ }
+ }
+
+Not all that spectacular. CouchDB is saying "hello" with the running version
+number.
+
+Next, we can get a list of databases::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+All we added to the previous request is the _all_dbs string.
+
+The response should look like::
+
+ ["_replicator","_users"]
+
+Oh, that's right, we didn't create any databases yet! All we see is an empty
+list.
+
+.. note::
+
+ The curl command issues GET requests by default. You can issue POST requests
+ using ``curl -X POST``. To make it easy to work with our terminal history,
+ we usually use the ``-X`` option even when issuing GET requests.
+ If we want to send a POST next time, all we have to change is the method.
+
+ HTTP does a bit more under the hood than you can see in the examples here.
+ If you're interested in every last detail that goes over the wire,
+ pass in the ``-v`` option (e.g., ``curl -vX GET``), which will show you
+ the server curl tries to connect to, the request headers it sends,
+ and response headers it receives back. Great for debugging!
+
+Let's create a database::
+
+ curl -X PUT http://127.0.0.1:5984/baseball
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+Retrieving the list of databases again shows some useful results this time::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+::
+
+ ["baseball"]
+
+.. note::
+
+ We should mention JavaScript Object Notation (JSON) here,
+ the data format CouchDB speaks. JSON is a lightweight data interchange format
+ based on JavaScript syntax. Because JSON is natively compatible with
+ JavaScript, your web browser is an ideal client for CouchDB.
+
+ Brackets (``[]``) represent ordered lists, and curly braces (``{}``) represent
+ key/value dictionaries. Keys must be strings, delimited by quotes (``"``),
+ and values can be strings, numbers, booleans, lists,
+ or key/value dictionaries. For a more detailed description of JSON,
+ see Appendix E, JSON Primer.
+
+Let's create another database::
+
+ curl -X PUT http://127.0.0.1:5984/baseball
+
+CouchDB will reply with::
+
+ {"error":"file_exists","reason":"The database could not be created,
+ the file already exists."}
+
+We already have a database with that name, so CouchDB will respond with an
+error. Let's try again with a different database name::
+
+ curl -X PUT http://127.0.0.1:5984/plankton
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+Retrieving the list of databases yet again shows some useful results::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+CouchDB will respond with::
+
+ ["baseball", "plankton"]
+
+To round things off, let's delete the second database::
+
+ curl -X DELETE http://127.0.0.1:5984/plankton
+
+CouchDB will reply with::
+
+ {"ok":true}
+
+The list of databases is now the same as it was before::
+
+ curl -X GET http://127.0.0.1:5984/_all_dbs
+
+CouchDB will respond with::
+
+ ["baseball"]
+
+For brevity, we'll skip working with documents, as the next section covers a
+different and potentially easier way of working with CouchDB that should
+provide experience with this. As we work through the example,
+keep in mind that "under the hood" everything is being done by the
+application exactly as you have been doing here manually.
+Everything is done using GET, PUT, POST, and DELETE with a URI.
+
+
+Welcome to Futon
+================
+
+After having seen CouchDB's raw API, let's get our feet wet by playing with
+Futon, the built-in administration interface. Futon provides full access to
+all of CouchDB's features and makes it easy to work with some of the more
+complex ideas involved. With Futon we can create and destroy databases; view
+and edit documents; compose and run MapReduce views; and trigger replication
+between databases.
+
+To load Futon in your browser, visit::
+
+ http://127.0.0.1:5984/_utils/
+
+If you're running version 0.9 or later, you should see something similar to
+:ref:`intro/tour-01`. In later chapters, we'll focus on using CouchDB from
+server-side languages such as Ruby and Python. As such, this chapter is a great
+opportunity to showcase an example of natively serving up a dynamic web
+application using nothing more than CouchDB's integrated web server, something
+you may wish to do with your own applications.
+
+The first thing we should do with a fresh installation of CouchDB is run the
+test suite to verify that everything is working properly. This assures us
+that any problems we may run into aren't due to bothersome issues with our
+setup. By the same token, failures in the Futon test suite are a red flag,
+telling us to double-check our installation before attempting to use a
+potentially broken database server, saving us the confusion when nothing
+seems to be working quite like we expect!
+
+
+.. _intro/tour-01:
+
+.. figure:: ../../images/intro-tour-01.png
+ :align: center
+ :alt: The Futon welcome screen
+
+ Figure 1. The Futon welcome screen
+
+
+Some common network configurations cause the replication test to fail when
+accessed via the localhost address. You can fix this by accessing CouchDB via
+127.0.0.1, e.g. http://127.0.0.1:5984/_utils/.
+
+Navigate to the test suite by clicking "Test Suite" on the Futon sidebar,
+then click "run all" at the top to kick things off. :ref:`intro/tour-02`
+shows the Futon test suite running some tests.
+
+
+.. _intro/tour-02:
+
+.. figure:: ../../images/intro-tour-02.png
+ :align: center
+ :alt: The Futon test suite running some tests
+
+ Figure 2. The Futon test suite running some tests
+
+
+Because the test suite is run from the browser, not only does it test that
+CouchDB is functioning properly, it also verifies that your browser's
+connection to the database is properly configured, which can be very handy
+for diagnosing misbehaving proxies or other HTTP middleware.
+
+If the test suite has an inordinate number of failures,
+you'll need to see the troubleshooting section in Appendix D,
+Installing from Source for the next steps to fix your installation.
+
+Now that the test suite is finished, you've verified that your CouchDB
+installation is successful and you're ready to see what else Futon has to offer.
+
+
+Your First Database and Document
+================================
+
+Creating a database in Futon is simple. From the overview page,
+click "Create Database." When asked for a name, enter hello-world and click
+the Create button.
+
+After your database has been created, Futon will display a list of all its
+documents. This list will start out empty (:ref:`intro/tour-03`), so let's
+create our first document. Click the "New Document" link and then the Create
+button in the pop up. Make sure to leave the document ID blank,
+and CouchDB will generate a UUID for you.
+
+For demoing purposes, having CouchDB assign a UUID is fine. When you write
+your first programs, we recommend assigning your own UUIDs. If your rely on
+the server to generate the UUID and you end up making two POST requests
+because the first POST request bombed out, you might generate two docs and
+never find out about the first one because only the second one will be
+reported back. Generating your own UUIDs makes sure that you'll never end up
+with duplicate documents.
+
+Futon will display the newly created document, with its _id and _rev as the
+only fields. To create a new field, click the "Add Field" button. We'll call
+the new field hello. Click the green check icon (or hit the Enter key) to
+finalize creating the hello field. Double-click the hello field's value
+(default null) to edit it.
+
+You can experiment with other JSON values; e.g., ``[1, 2, "c"]`` or
+``{"foo": "bar"}``. Once you've entered your values into the document,
+make a note of its ``_rev`` attribute and click "Save Document." The result
+should look like :ref:`intro/tour-04` document in Futon".
+
+
+.. _intro/tour-03:
+
+.. figure:: ../../images/intro-tour-03.png
+ :align: center
+ :alt: An empty database in Futon
+
+ Figure 3. An empty database in Futon
+
+
+.. _intro/tour-04:
+
+.. figure:: ../../images/intro-tour-04.png
+ :align: center
+ :alt: A "hello world" document in Futon
+
+ Figure 4. A "hello world" document in Futon
+
+
+You'll notice that the document's _rev has changed. We'll go into more detail
+about this in later chapters, but for now, the important thing to note is
+that _rev acts like a safety feature when saving a document. As long as you
+and CouchDB agree on the most recent _rev of a document, you can successfully
+save your changes.
+
+Futon also provides a way to display the underlying JSON data,
+which can be more compact and easier to read, depending on what sort of data
+you are dealing with. To see the JSON version of our "hello world" document,
+click the Source tab. The result should look like :ref:`intro/tour-05`.
+
+
+.. _intro/tour-05:
+
+.. figure:: ../../images/intro-tour-05.png
+ :align: center
+ :alt: The JSON source of a "hello world" document in Futon
+
+ Figure 5. The JSON source of a "hello world" document in Futon
+
+
+Running a Query Using MapReduce
+===============================
+
+Traditional relational databases allow you to run any queries you like as
+long as your data is structured correctly. In contrast,
+CouchDB uses predefined map and reduce functions in a style known as
+MapReduce. These functions provide great flexibility because they can adapt
+to variations in document structure, and indexes for each document can be
+computed independently and in parallel. The combination of a map and a reduce
+function is called a view in CouchDB terminology.
+
+For experienced relational database programmers, MapReduce can take some
+getting used to. Rather than declaring which rows from which tables to
+include in a result set and depending on the database to determine the most
+efficient way to run the query, reduce queries are based on simple range
+requests against the indexes generated by your map functions.
+
+Map functions are called once with each document as the argument.
+The function can choose to skip the document altogether or emit one or more
+view rows as key/value pairs. Map functions may not depend on any information
+outside of the document. This independence is what allows CouchDB views to be
+generated incrementally and in parallel.
+
+CouchDB views are stored as rows that are kept sorted by key. This makes
+retrieving data from a range of keys efficient even when there are thousands
+or millions of rows. When writing CouchDB map functions,
+your primary goal is to build an index that stores related data under nearby
+keys.
+
+Before we can run an example MapReduce view, we'll need some data to run it
+on. We'll create documents carrying the price of various supermarket items as
+found at different shops. Let's create documents for apples, oranges,
+and bananas. (Allow CouchDB to generate the _id and _rev fields.) Use Futon
+to create documents that have a final JSON structure that looks like this:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c0001f4",
+ "_rev": "1-2628a75ac8c3abfffc8f6e30c9949fd6",
+ "item": "apple",
+ "prices": {
+ "Fresh Mart": 1.59,
+ "Price Max": 5.99,
+ "Apples Express": 0.79
+ }
+ }
+
+This document should look like :ref:`intro/tour-06` when entered into Futon.
+
+
+.. _intro/tour-06:
+
+.. figure:: ../../images/intro-tour-06.png
+ :align: center
+ :alt: An example document with apple prices in Futon
+
+ Figure 6. An example document with apple prices in Futon
+
+
+OK, now that that's done, let's create the document for oranges:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c0003f0",
+ "_rev": "1-e9680c5d9a688b4ff8dd68549e8e072c",
+ "item": "orange",
+ "prices": {
+ "Fresh Mart": 1.99,
+ "Price Max": 3.19,
+ "Citrus Circus": 1.09
+ }
+ }
+
+And finally, the document for bananas:
+
+.. code-block:: javascript
+
+ {
+ "_id": "00a271787f89c0ef2e10e88a0c00048b",
+ "_rev": "1-60e25d93dc12884676d037400a6fa189",
+ "item": "banana",
+ "prices": {
+ "Fresh Mart": 1.99,
+ "Price Max": 0.79,
+ "Banana Montana": 4.22
+ }
+ }
+
+Imagine we're catering a big luncheon, but the client is very price-sensitive.
+To find the lowest prices, we're going to create our first view,
+which shows each fruit sorted by price. Click "hello-world" to return to the
+hello-world overview, and then from the "select view" menu choose "Temporary
+view…" to create a new view.
+
+Edit the map function, on the left, so that it looks like the following:
+
+.. code-block:: javascript
+
+ function(doc) {
+ var shop, price, value;
+ if (doc.item && doc.prices) {
+ for (shop in doc.prices) {
+ price = doc.prices[shop];
+ value = [doc.item, shop];
+ emit(price, value);
+ }
+ }
+ }
+
+This is a JavaScript function that CouchDB runs for each of our documents as
+it computes the view. We'll leave the reduce function blank for the time being.
+
+Click "Run" and you should see result rows like in :ref:`intro/tour-08`,
+with the various items sorted by price. This map function could be even more
+useful if it grouped the items by type so that all the prices for bananas were
+next to each other in the result set. CouchDB's key sorting system allows any
+valid JSON object as a key. In this case, we'll emit an array of [item, price]
+so that CouchDB groups by item type and price.
+
+
+.. _intro/tour-08:
+
+.. figure:: ../../images/intro-tour-08.png
+ :align: center
+ :alt: The results of running a view in Futon
+
+ Figure 8. The results of running a view in Futon
+
+
+Let's modify the view function so that it looks like this:
+
+.. code-block:: javascript
+
+ function(doc) {
+ var shop, price, key;
+ if (doc.item && doc.prices) {
+ for (shop in doc.prices) {
+ price = doc.prices[shop];
+ key = [doc.item, price];
+ emit(key, shop);
+ }
+ }
+ }
+
+Here, we first check that the document has the fields we want to use. CouchDB
+recovers gracefully from a few isolated map function failures,
+but when a map function fails regularly (due to a missing required field or
+other JavaScript exception), CouchDB shuts off its indexing to prevent any
+further resource usage. For this reason, it's important to check for the
+existence of any fields before you use them. In this case,
+our map function will skip the first "hello world" document we created
+without emitting any rows or encountering any errors. The result of this
+query should look like :ref:`intro/tour-09`.
+
+
+.. _intro/tour-09:
+
+.. figure:: ../../images/intro-tour-09.png
+ :align: center
+ :alt: The results of running a view after grouping by item type and price
+
+ Figure 9. The results of running a view after grouping by item type and price
+
+
+Once we know we've got a document with an item type and some prices,
+we iterate over the item's prices and emit key/values pairs. The key is an
+array of the item and the price, and forms the basis for CouchDB's sorted
+index. In this case, the value is the name of the shop where the item can be
+found for the listed price.
+
+View rows are sorted by their keys -- in this example, first by item,
+then by price. This method of complex sorting is at the heart of creating
+useful indexes with CouchDB.
+
+MapReduce can be challenging, especially if you've spent years working with
+relational databases. The important things to keep in mind are that map
+functions give you an opportunity to sort your data using any key you choose,
+and that CouchDB's design is focused on providing fast,
+efficient access to data within a range of keys.
+
+
+Triggering Replication
+======================
+
+Futon can trigger replication between two local databases,
+between a local and remote database, or even between two remote databases.
+We'll show you how to replicate data from one local database to another,
+which is a simple way of making backups of your databases as we're working
+through the examples.
+
+First we'll need to create an empty database to be the target of replication.
+Return to the overview and create a database called hello-replication.
+Now click "Replicator" in the sidebar and choose hello-world as the source
+and hello-replication as the target. Click "Replicate" to replicate your
+database. The result should look something like :ref:`intro/tour-10`.
+
+
+.. _intro/tour-10:
+
+.. figure:: ../../images/intro-tour-10.png
+ :align: center
+ :alt: Running database replication in Futon
+
+ Figure 10. Running database replication in Futon
+
+
+.. note::
+
+ For larger databases, replication can take much longer. It is important to
+ leave the browser window open while replication is taking place.
+ As an alternative, you can trigger replication via curl or some other HTTP
+ client that can handle long-running connections. If your client closes the
+ connection before replication finishes, you'll have to retrigger it.
+ Luckily, CouchDB's replication can take over from where it left off
+ instead of starting from scratch.
+
+
+Wrapping Up
+===========
+
+Now that you've seen most of Futon's features, you'll be prepared to dive in
+and inspect your data as we build our example application in the next few
+chapters. Futon's pure JavaScript approach to managing CouchDB shows how it's
+possible to build a fully featured web application using only CouchDB's HTTP
+API and integrated web server.
+
+But before we get there, we'll have another look at CouchDB's HTTP API -- now
+with a magnifying glass. Let's curl up on the couch and relax.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/why.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/why.rst b/share/doc/src/intro/why.rst
new file mode 100644
index 0000000..1b902d8
--- /dev/null
+++ b/share/doc/src/intro/why.rst
@@ -0,0 +1,315 @@
+.. 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.
+
+
+.. _intro/why:
+
+============
+Why CouchDB?
+============
+
+Apache CouchDB is one of a new breed of database management systems.
+This chapter explains why there's a need for new systems as well as the
+motivations behind building CouchDB.
+
+As CouchDB developers, we're naturally very excited to be using CouchDB.
+In this chapter we'll share with you the reasons for our enthusiasm.
+We'll show you how CouchDB's schema-free document model is a better fit
+for common applications, how the built-in query engine is a powerful way
+to use and process your data, and how CouchDB's design lends itself
+to modularization and scalability.
+
+
+Relax
+=====
+
+If there's one word to describe CouchDB, it is *relax*. It is in the title of
+this book, it is the byline to CouchDB's official logo,
+and when you start CouchDB, you see::
+
+ Apache CouchDB has started. Time to relax.
+
+Why is relaxation important? Developer productivity roughly doubled in the
+last five years. The chief reason for the boost is more powerful tools that
+are easier to use. Take Ruby on Rails as an example. It is an infinitely
+complex framework, but it's easy to get started with. Rails is a success
+story because of the core design focus on ease of use. This is one reason why
+CouchDB is relaxing: learning CouchDB and understanding its core concepts
+should feel natural to most everybody who has been doing any work on the Web.
+And it is still pretty easy to explain to non-technical people.
+
+Getting out of the way when creative people try to build specialized
+solutions is in itself a core feature and one thing that CouchDB aims to get
+right. We found existing tools too cumbersome to work with during development
+or in production, and decided to focus on making CouchDB easy, even a pleasure,
+to use.
+
+Another area of relaxation for CouchDB users is the production setting.
+If you have a live running application, CouchDB again goes out of its way
+to avoid troubling you. Its internal architecture is fault-tolerant,
+and failures occur in a controlled environment and are dealt with gracefully.
+Single problems do not cascade through an entire server system but stay
+isolated in single requests.
+
+CouchDB's core concepts are simple (yet powerful) and well understood.
+Operations teams (if you have a team; otherwise, that's you) do not have to
+fear random behavior and untraceable errors. If anything should go wrong,
+you can easily find out what the problem is, but these situations are rare.
+
+CouchDB is also designed to handle varying traffic gracefully. For instance,
+if a website is experiencing a sudden spike in traffic, CouchDB will generally
+absorb a lot of concurrent requests without falling over. It may take a little
+more time for each request, but they all get answered. When the spike is over,
+CouchDB will work with regular speed again.
+
+The third area of relaxation is growing and shrinking the underlying hardware
+of your application. This is commonly referred to as scaling. CouchDB enforces
+a set of limits on the programmer. On first look, CouchDB might seem
+inflexible, but some features are left out by design for the simple reason
+that if CouchDB supported them, it would allow a programmer to create
+applications that couldn't deal with scaling up or down.
+
+.. note::
+ CouchDB doesn't let you do things that would get you in trouble later on.
+ This sometimes means you'll have to unlearn best practices you might have
+ picked up in your current or past work.
+
+
+A Different Way to Model Your Data
+==================================
+
+We believe that CouchDB will drastically change the way you build
+document-based applications. CouchDB combines an intuitive document storage
+model with a powerful query engine in a way that's so simple you'll probably
+be tempted to ask, “Why has no one built something like this before?”
+
+ Django may be built for the Web, but CouchDB is built of the Web. I've
+ never seen software that so completely embraces the philosophies behind
+ HTTP. CouchDB makes Django look old-school in the same way that Django
+ makes ASP look outdated.
+
+ -- Jacob Kaplan-Moss, Django developer
+
+CouchDB's design borrows heavily from web architecture and the concepts of
+resources, methods, and representations. It augments this with powerful ways
+to query, map, combine, and filter your data. Add fault tolerance, extreme
+scalability, and incremental replication, and CouchDB defines a sweet spot
+for document databases.
+
+
+A Better Fit for Common Applications
+====================================
+
+We write software to improve our lives and the lives of others. Usually this
+involves taking some mundane information such as contacts, invoices,
+or receipts and manipulating it using a computer application. CouchDB is a
+great fit for common applications like this because it embraces the natural
+idea of evolving, self-contained documents as the very core of its data model.
+
+
+Self-Contained Data
+-------------------
+
+An invoice contains all the pertinent information about a single transaction
+the seller, the buyer, the date, and a list of the items or services sold.
+As shown in :ref:`intro/why-01`, there's no abstract reference on this
+piece of paper that points to some other piece of paper with the seller's
+name and address. Accountants appreciate the simplicity of having everything
+in one place. And given the choice, programmers appreciate that, too.
+
+
+.. _intro/why-01:
+
+.. figure:: ../../images/intro-why-01.png
+ :align: center
+ :alt: Self-contained documents
+
+ Figure 1. Self-contained documents
+
+
+Yet using references is exactly how we model our data in a relational
+database! Each invoice is stored in a table as a row that refers to other
+rows in other tables one row for seller information, one for the buyer,
+one row for each item billed, and more rows still to describe the item
+details, manufacturer details, and so on and so forth.
+
+This isn't meant as a detraction of the relational model, which is widely
+applicable and extremely useful for a number of reasons. Hopefully, though, it
+illustrates the point that sometimes your model may not “fit” your data
+in the way it occurs in the real world.
+
+Let's take a look at the humble contact database to illustrate a different
+way of modeling data, one that more closely “fits” its real-world counterpart
+-- a pile of business cards. Much like our invoice example, a business card
+contains all the important information, right there on the cardstock.
+We call this “self-contained” data, and it's an important concept
+in understanding document databases like CouchDB.
+
+
+Syntax and Semantics
+--------------------
+
+Most business cards contain roughly the same information -- someone's identity,
+an affiliation, and some contact information. While the exact form of this
+information can vary between business cards, the general information being
+conveyed remains the same, and we're easily able to recognize it as a
+business card. In this sense, we can describe a business card as a *real-world
+document*.
+
+Jan's business card might contain a phone number but no fax number,
+whereas J. Chris's business card contains both a phone and a fax number. Jan
+does not have to make his lack of a fax machine explicit by writing something
+as ridiculous as “Fax: None” on the business card. Instead, simply omitting
+a fax number implies that he doesn't have one.
+
+We can see that real-world documents of the same type, such as business cards,
+tend to be very similar in *semantics* -- the sort of information they carry,
+but can vary hugely in *syntax*, or how that information is structured. As human
+beings, we're naturally comfortable dealing with this kind of variation.
+
+While a traditional relational database requires you to model your data
+*up front*, CouchDB's schema-free design unburdens you with a powerful way to
+aggregate your data *after the fact*, just like we do with real-world
+documents. We'll look in depth at how to design applications with this
+underlying storage paradigm.
+
+
+Building Blocks for Larger Systems
+==================================
+
+CouchDB is a storage system useful on its own. You can build many applications
+with the tools CouchDB gives you. But CouchDB is designed with a bigger picture
+in mind. Its components can be used as building blocks that solve storage
+problems in slightly different ways for larger and more complex systems.
+
+Whether you need a system that's crazy fast but isn't too concerned with
+reliability (think logging), or one that guarantees storage in two or more
+physically separated locations for reliability, but you're willing to take a
+performance hit, CouchDB lets you build these systems.
+
+There are a multitude of knobs you could turn to make a system work better in
+one area, but you'll affect another area when doing so. One example would be
+the CAP theorem discussed in the next chapter. To give you an idea of other
+things that affect storage systems, see :ref:`Figure 2 <intro/why-figure-02>`
+and :ref:`Figure 3 <intro/why-figure-03>`.
+
+By reducing latency for a given system (and that is true not only for storage
+systems), you affect concurrency and throughput capabilities.
+
+
+.. _intro/why-figure-02:
+
+.. figure:: ../../images/intro-why-02.png
+ :align: center
+ :alt: Throughput, latency, or concurrency
+
+ Figure 2. Throughput, latency, or concurrency
+
+
+.. _intro/why-figure-03:
+
+.. figure:: ../../images/intro-why-03.png
+ :align: center
+ :alt: Scaling: read requests, write requests, or data
+
+ Figure 3. Scaling: read requests, write requests, or data
+
+
+When you want to scale out, there are three distinct issues to deal with:
+scaling read requests, write requests, and data. Orthogonal to all three and
+to the items shown in :ref:`Figure 2 <intro/why-figure-02>` and :ref:`Figure 3
+<intro/why-figure-03>` are many more attributes like reliability or simplicity.
+You can draw many of these graphs that show how different features or attributes
+pull into different directions and thus shape the system they describe.
+
+CouchDB is very flexible and gives you enough building blocks to create a
+system shaped to suit your exact problem. That's not saying that CouchDB can
+be bent to solve any problem -- CouchDB is no silver bullet -- but in the
+area of data storage, it can get you a long way.
+
+
+CouchDB Replication
+===================
+
+CouchDB replication is one of these building blocks. Its fundamental function
+is to synchronize two or more CouchDB databases. This may sound simple,
+but the simplicity is key to allowing replication to solve a number of
+problems: reliably synchronize databases between multiple machines for
+redundant data storage; distribute data to a cluster of CouchDB instances
+that share a subset of the total number of requests that hit the cluster
+(load balancing); and distribute data between physically distant locations,
+such as one office in New York and another in Tokyo.
+
+CouchDB replication uses the same REST API all clients use. HTTP is
+ubiquitous and well understood. Replication works incrementally; that is,
+if during replication anything goes wrong, like dropping your network
+connection, it will pick up where it left off the next time it runs. It also
+only transfers data that is needed to synchronize databases.
+
+A core assumption CouchDB makes is that things can go wrong,
+like network connection troubles, and it is designed for graceful error
+recovery instead of assuming all will be well. The replication system's
+incremental design shows that best. The ideas behind “things that can go
+wrong” are embodied in the `Fallacies of Distributed Computing`_:
+
+- The network is reliable.
+- Latency is zero.
+- Bandwidth is infinite.
+- The network is secure.
+- Topology doesn't change.
+- There is one administrator.
+- Transport cost is zero.
+- The network is homogeneous.
+
+Existing tools often try to hide the fact that there is a network and that
+any or all of the previous conditions don't exist for a particular system.
+This usually results in fatal error scenarios when something finally goes
+wrong. In contrast, CouchDB doesn't try to hide the network; it just handles
+errors gracefully and lets you know when actions on your end are required.
+
+.. _Fallacies of Distributed Computing: http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing
+
+
+Local Data Is King
+==================
+
+CouchDB takes quite a few lessons learned from the Web,
+but there is one thing that could be improved about the Web: latency.
+Whenever you have to wait for an application to respond or a website to
+render, you almost always wait for a network connection that isn't as fast as
+you want it at that point. Waiting a few seconds instead of milliseconds
+greatly affects user experience and thus user satisfaction.
+
+What do you do when you are offline? This happens all the time -- your DSL or
+cable provider has issues, or your iPhone, G1, or Blackberry has no bars,
+and no connectivity means no way to get to your data.
+
+CouchDB can solve this scenario as well, and this is where scaling is
+important again. This time it is scaling down. Imagine CouchDB installed on
+phones and other mobile devices that can synchronize data with centrally
+hosted CouchDBs when they are on a network. The synchronization is not bound
+by user interface constraints like subsecond response times. It is easier to
+tune for high bandwidth and higher latency than for low bandwidth and very
+low latency. Mobile applications can then use the local CouchDB to fetch
+data, and since no remote networking is required for that,
+latency is low by default.
+
+Can you really use CouchDB on a phone? Erlang, CouchDB's implementation
+language has been designed to run on embedded devices magnitudes smaller and
+less powerful than today's phones.
+
+
+Wrapping Up
+===========
+
+The next chapter further explores the distributed nature of CouchDB. We
+should have given you enough bites to whet your interest. Let's go!
[05/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Import pagination recipe from Guide to CouchDB.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/b8b0773d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/b8b0773d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/b8b0773d
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: b8b0773d409198e5a17d8a4b5798e1b5145ed6a9
Parents: 9947e58
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 15:37:01 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/couchapp/views/index.rst | 1 +
share/doc/src/couchapp/views/pagination.rst | 287 +++++++++++++++++++++++
2 files changed, 288 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b8b0773d/share/doc/src/couchapp/views/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/views/index.rst b/share/doc/src/couchapp/views/index.rst
index 4b007f5..05f476d 100644
--- a/share/doc/src/couchapp/views/index.rst
+++ b/share/doc/src/couchapp/views/index.rst
@@ -27,3 +27,4 @@ applications with CouchDB
collation
joins
nosql
+ pagination
http://git-wip-us.apache.org/repos/asf/couchdb/blob/b8b0773d/share/doc/src/couchapp/views/pagination.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/views/pagination.rst b/share/doc/src/couchapp/views/pagination.rst
new file mode 100644
index 0000000..0d805ae
--- /dev/null
+++ b/share/doc/src/couchapp/views/pagination.rst
@@ -0,0 +1,287 @@
+.. 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.
+
+
+.. _views/pagination:
+
+=================
+Pagination Recipe
+=================
+
+This recipe explains how to paginate over view results.
+Pagination is a user interface (UI) pattern that allows the display of a
+large number of rows (`the result set`) without loading all the rows into the
+UI at once. A fixed-size subset, the `page`, is displayed along with next and
+previous links or buttons that can move the `viewport` over the result set to
+an adjacent page.
+
+We assume you’re familiar with creating and querying documents and views as
+well as the multiple view query options.
+
+Example Data
+============
+
+To have some data to work with, we’ll create a list of bands,
+one document per band::
+
+ { "name":"Biffy Clyro" }
+
+ { "name":"Foo Fighters" }
+
+ { "name":"Tool" }
+
+ { "name":"Nirvana" }
+
+ { "name":"Helmet" }
+
+ { "name":"Tenacious D" }
+
+ { "name":"Future of the Left" }
+
+ { "name":"A Perfect Circle" }
+
+ { "name":"Silverchair" }
+
+ { "name":"Queens of the Stone Age" }
+
+ { "name":"Kerub" }
+
+A View
+=======
+
+We need a simple map function that gives us an alphabetical list of band
+names. This should be easy, but we’re adding extra smarts to filter out “The”
+and “A” in front of band names to put them into the right position:
+
+.. code-block:: javascript
+
+ function(doc) {
+ if(doc.name) {
+ var name = doc.name.replace(/^(A|The) /, "");
+ emit(name, null);
+ }
+ }
+
+The views result is an alphabetical list of band names. Now say we want to
+display band names five at a time and have a link pointing to the next five
+names that make up one page, and a link for the previous five,
+if we’re not on the first page.
+
+We learned how to use the ``startkey``, ``limit``, and ``skip`` parameters in
+earlier chapters. We’ll use these again here. First, let’s have a look at
+the full result set:
+
+.. code-block:: javascript
+
+ {"total_rows":11,"offset":0,"rows":[
+ {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
+ {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
+ {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
+ {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
+ {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null},
+ {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
+ {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
+ {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
+ {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age","value":null},
+ {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null},
+ {"id":"fd590d4ad53771db47b0406054f02243","key":"Tool","value":null}
+ ]}
+
+Setup
+=====
+
+The mechanics of paging are very simple:
+
+- Display first page
+- If there are more rows to show, show next link
+- Draw subsequent page
+- If this is not the first page, show a previous link
+- If there are more rows to show, show next link
+
+Or in a pseudo-JavaScript snippet:
+
+.. code-block:: javascript
+
+
+ var result = new Result();
+ var page = result.getPage();
+
+ page.display();
+
+ if(result.hasPrev()) {
+ page.display_link('prev');
+ }
+
+ if(result.hasNext()) {
+ page.display_link('next');
+ }
+
+Slow Paging (Do Not Use)
+========================
+
+**Don’t use this method!** We just show it because it might seem natural to use,
+and you need to know why it is a bad idea. To get the first five rows from
+the view result, you use the ``?limit=5`` query parameter::
+
+ curl -X GET http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5
+
+The result:
+
+.. code-block:: javascript
+
+ {"total_rows":11,"offset":0,"rows":[
+ {"id":"a0746072bba60a62b01209f467ca4fe2","key":"Biffy Clyro","value":null},
+ {"id":"b47d82284969f10cd1b6ea460ad62d00","key":"Foo Fighters","value":null},
+ {"id":"45ccde324611f86ad4932555dea7fce0","key":"Tenacious D","value":null},
+ {"id":"d7ab24bb3489a9010c7d1a2087a4a9e4","key":"Future of the Left","value":null},
+ {"id":"ad2f85ef87f5a9a65db5b3a75a03cd82","key":"Helmet","value":null}
+ ]}
+
+By comparing the ``total_rows`` value to our ``limit`` value,
+we can determine if there are more pages to display. We also know by the
+`offset` member that we are on the first page. We can calculate the value for
+``skip=`` to get the results for the next page:
+
+.. code-block:: javascript
+
+ var rows_per_page = 5;
+ var page = (offset / rows_per_page) + 1; // == 1
+ var skip = page * rows_per_page; // == 5 for the first page, 10 for the second ...
+
+So we query CouchDB with::
+
+ curl -X GET 'http://127.0.0.1:5984/artists/_design/artists/_view/by-name?limit=5&skip=5'
+
+Note we have to use ``'`` (single quotes) to escape the ``&`` character that is
+special to the shell we execute curl in.
+
+The result:
+
+.. code-block:: javascript
+
+ {"total_rows":11,"offset":5,"rows":[
+ {"id":"a2f31cfa68118a6ae9d35444fcb1a3cf","key":"Nirvana","value":null},
+ {"id":"67373171d0f626b811bdc34e92e77901","key":"Kerub","value":null},
+ {"id":"3e1b84630c384f6aef1a5c50a81e4a34","key":"Perfect Circle","value":null},
+ {"id":"84a371a7b8414237fad1b6aaf68cd16a","key":"Queens of the Stone Age",
+ "value":null},
+ {"id":"dcdaf08242a4be7da1a36e25f4f0b022","key":"Silverchair","value":null}
+ ]}
+
+Implementing the ``hasPrev()`` and ``hasNext()`` method is pretty
+straightforward:
+
+.. code-block:: javascript
+
+ function hasPrev()
+ {
+ return page > 1;
+ }
+
+ function hasNext()
+ {
+ var last_page = Math.floor(total_rows / rows_per_page) +
+ (total_rows % rows_per_page);
+ return page != last_page;
+ }
+
+The dealbreaker
+---------------
+
+This all looks easy and straightforward, but it has one fatal flaw. Remember
+how view results are generated from the underlying B-tree index: CouchDB
+jumps to the first row (or the first row that matches ``startkey``,
+if provided) and reads one row after the other from the index until there are
+no more rows (or ``limit`` or ``endkey`` match, if provided).
+
+The ``skip`` argument works like this: in addition to going to the first row and
+starting to read, skip will skip as many rows as specified, but CouchDB will
+still read from the first row; it just won’t return any values for the skipped
+rows. If you specify ``skip=100``, CouchDB will read 100 rows and not create
+output for them. This doesn’t sound too bad, but it is very bad, when you use
+1000 or even 10000 as skip values. CouchDB will have to look at a lot of rows
+unnecessarily.
+
+As a rule of thumb, skip should be used only with single digit values. While
+it’s possible that there are legitimate use cases where you specify a larger
+value, they are a good indicator for potential problems with your solution.
+Finally, for the calculations to work, you need to add a reduce function and
+make two calls to the view per page to get all the numbering right,
+and there’s still a potential for error.
+
+Fast Paging (Do Use)
+====================
+
+The correct solution is not much harder. Instead of slicing the result set
+into equally sized pages, we look at 10 rows at a time and use ``startkey`` to
+jump to the next 10 rows. We even use skip, but only with the value 1.
+
+Here is how it works:
+
+- Request `rows_per_page + 1` rows from the view
+- Display `rows_per_page` rows, `store + 1` row as `next_startkey` and
+ `next_startkey_docid`
+- As page information, keep ``startkey`` and `next_startkey`
+- Use the `next_*` values to create the next link, and use the others to
+ create the previous link
+
+The trick to finding the next page is pretty simple. Instead of requesting 10
+rows for a page, you request 11 rows, but display only 10 and use the values
+in the 11th row as the ``startkey`` for the next page. Populating the link to
+the previous page is as simple as carrying the current ``startkey`` over to the
+next page. If there’s no previous ``startkey``, we are on the first page. We
+stop displaying the link to the next page if we get `rows_per_page` or less
+rows back. This is called linked list pagination, as we go from page to
+page, or list item to list item, instead of jumping directly to a
+pre-computed page. There is one caveat, though. Can you spot it?
+
+CouchDB view keys do not have to be unique; you can have multiple index
+entries read. What if you have more index entries for a key than rows that
+should be on a page? ``startkey`` jumps to the first row, and you’d be screwed
+if CouchDB didn’t have an additional parameter for you to use. All view keys
+with the same value are internally sorted by `docid`, that is, the ID of
+the document that created that view row. You can use the ``startkey_docid``
+and ``endkey_docid`` parameters to get subsets of these rows. For
+pagination, we still don’t need ``endkey_docid``, but ``startkey_docid`` is very
+handy. In addition to ``startkey`` and ``limit``, you also use
+``startkey_docid`` for pagination if, and only if, the extra row you fetch to
+find the next page has the same key as the current ``startkey``.
+
+It is important to note that the `*_docid` parameters only work in addition to
+the `*key` parameters and are only useful to further narrow down the result set
+of a view for a single key. They do not work on their own (the one exception
+being the built-in :ref:`_all_docs view <api/db/all_docs>` that already sorts
+by document ID).
+
+The advantage of this approach is that all the key operations can be
+performed on the super-fast B-tree index behind the view. Looking up a page
+doesn’t include scanning through hundreds and thousands of rows unnecessarily.
+
+Jump to Page
+============
+
+One drawback of the linked list style pagination is that you can’t
+pre-compute the rows for a particular page from the page number and the rows
+per page. Jumping to a specific page doesn’t really work. Our gut reaction,
+if that concern is raised, is, “Not even Google is doing that!” and we tend
+to get away with it. Google always pretends on the first page to find 10 more
+pages of results. Only if you click on the second page (something very few
+people actually do) might Google display a reduced set of pages. If you page
+through the results, you get links for the previous and next 10 pages,
+but no more. Pre-computing the necessary ``startkey`` and ``startkey_docid``
+for 20 pages is a feasible operation and a pragmatic optimization to know the
+rows for every page in a result set that is potentially tens of thousands
+of rows long, or more.
+
+If you really do need to jump to a page over the full range of documents (we
+have seen applications that require that), you can still maintain an integer
+value index as the view index and take a hybrid approach at solving pagination.
[24/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Better release version for non-bootsrapped CouchDB.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1449a377
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1449a377
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1449a377
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 1449a3777b09282d5fab9310d6eca538332f0b2d
Parents: 7c4a8c4
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Sep 2 00:58:25 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/conf.py | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1449a377/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 3e6d5a3..04b7079 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -51,7 +51,11 @@ release = '.'.join([
_info['LOCAL_VERSION_MAJOR'],
_info['LOCAL_VERSION_MINOR'],
_info['LOCAL_VERSION_REVISION']
-]) + _info['LOCAL_VERSION_STAGE'] + '' + _info['LOCAL_VERSION_RELEASE']
+]) + (
+ _info['LOCAL_VERSION_STAGE'] + '' + _info['LOCAL_VERSION_RELEASE']
+ if _info['LOCAL_VERSION_RELEASE'] == '%revision%'
+ else '-dev'
+)
project = _info['LOCAL_PACKAGE_NAME']
[36/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Add missed figure 7.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d1e3b5d6
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d1e3b5d6
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d1e3b5d6
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: d1e3b5d6c69ac6cf9779a1fe2d77571e7fb48dd5
Parents: c5e0cc5
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:37:40 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/intro/tour.rst | 8 ++++++++
1 file changed, 8 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d1e3b5d6/share/doc/src/intro/tour.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/tour.rst b/share/doc/src/intro/tour.rst
index af91f5e..b8f9975 100644
--- a/share/doc/src/intro/tour.rst
+++ b/share/doc/src/intro/tour.rst
@@ -398,6 +398,14 @@ which shows each fruit sorted by price. Click "hello-world" to return to the
hello-world overview, and then from the "select view" menu choose "Temporary
view…" to create a new view.
+
+.. figure:: ../../images/intro-tour-07.png
+ :align: center
+ :alt: A temporary view in Futon
+
+ Figure 7. A temporary view in Futon
+
+
Edit the map function, on the left, so that it looks like the following:
.. code-block:: javascript
[28/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Remove duplicate content.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a103e74f
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a103e74f
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a103e74f
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a103e74fb7fcccaa8c84837699fb411dbd160e82
Parents: 71ec756
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 17:30:35 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 65 ++-------------------------------------
1 file changed, 2 insertions(+), 63 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a103e74f/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index dd64257..74465b6 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -181,8 +181,8 @@ Request Headers
.. code-block:: http
- Server: CouchDB/|version| (Erlang OTP/R13B)
- Date: Thu, 13 Jan 2011 13:40:11 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Date: Thu, 13 Jan 2013 13:40:11 GMT
Content-Type: application/json
Content-Length: 227
Cache-Control: must-revalidate
@@ -589,64 +589,3 @@ corresponding API call reference.
The request was invalid, either because the supplied JSON was
invalid, or invalid information was supplied as part of the request.
-
-HTTP Range Requests
-===================
-
-HTTP allows you to specify byte ranges for requests. This allows the
-implementation of resumable downloads and skippable audio and video
-streams alike. This is available for all attachments inside CouchDB.
-
-This is just a real quick run through how this looks under the hood.
-Usually, you will have larger binary files to serve from CouchDB, like
-MP3s and videos, but to make things a little more obvious, I use a text
-file here (Note that I use the ``application/octet-stream`` Content-Type
-instead of ``text/plain``).
-
-.. code-block:: bash
-
- shell> cat file.txt
- My hovercraft is full of eels!
-
-Now let's store this text file as an attachment in CouchDB. First, we
-create a database:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/test
- {"ok":true}
-
-Then we create a new document and the file attachment in one go:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
- -H "Content-Type: application/octet-stream" -d@file.txt
- {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
-
-Now we can request the whole file easily:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
- My hovercraft is full of eels!
-
-But say we only want the first 13 bytes:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
- -H "Range: bytes=0-12"
- My hovercraft
-
-HTTP supports many ways to specify single and even multiple byte
-ranges. Read all about it in `RFC 2616`_.
-
-.. note::
- Databases that have been created with CouchDB 1.0.2 or earlier will
- support range requests in |version|, but they are using a less-optimal
- algorithm. If you plan to make heavy use of this feature, make sure
- to compact your database with CouchDB |version| to take advantage of a
- better algorithm to find byte ranges.
-
-.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
[38/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Fix markup for PUT /{db}
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/7ef3ef62
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/7ef3ef62
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/7ef3ef62
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 7ef3ef62eb12f2dda51298461d354f480007d068
Parents: a16de04
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Sep 3 14:09:12 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7ef3ef62/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 4880e61..2fb525f 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -103,7 +103,7 @@
}
-.. http::put /{db}
+.. http:put:: /{db}
Creates a new database. The database name ``{db}`` must be composed by
following next rules:
[50/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Make main page a bit nicer and friendly.
Looks weird and empty, but we'll fix it later with more content and redesign.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/18735b67
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/18735b67
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/18735b67
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 18735b6794fb2a63f37038bb3ebd5fdabe19d643
Parents: de48ff3
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Sep 12 04:58:16 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 4 +-
share/doc/src/conf.py | 7 +-
share/doc/src/contents.rst | 38 ++++++++
share/doc/src/index.rst | 38 --------
share/doc/templates/layout.html | 27 ++++++
share/doc/templates/pages/index.html | 156 ++++++++++++++++++++++++++++++
6 files changed, 227 insertions(+), 43 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index c13f8a2..1030dcd 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -260,7 +260,7 @@ html_files = \
html/index.html \
html/json-structure.html \
html/objects.inv \
- html/genindex.html \
+ html/http-api.html \
html/search.html \
html/searchindex.js
@@ -404,6 +404,8 @@ src_files = \
src_files_html = \
../static/rtd.css \
../templates/pages/download.html \
+ ../templates/pages/index.html \
+ ../templates/layout.html \
../templates/help.html \
../templates/searchbox.html \
../templates/utilities.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 7c49bbf..bfdcd99 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -38,8 +38,6 @@ looks like there is no such file there.''')
source_suffix = ".rst"
-master_doc = "index"
-
nitpicky = True
version = '.'.join([
@@ -79,7 +77,7 @@ html_static_path = ["../static"]
html_title = ' '.join([
project,
version,
- 'Manual'
+ 'Documentation'
])
html_style = "rtd.css"
@@ -91,7 +89,8 @@ html_favicon = "../images/favicon.ico"
html_use_index = False
html_additional_pages = {
- 'download': 'pages/download.html'
+ 'download': 'pages/download.html',
+ 'index': 'pages/index.html'
}
html_context = {}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
new file mode 100644
index 0000000..f00aed6
--- /dev/null
+++ b/share/doc/src/contents.rst
@@ -0,0 +1,38 @@
+.. 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.
+
+
+|Apache CouchDB(TM)|_ |release| Documentation
+=============================================
+
+.. toctree::
+ :maxdepth: 3
+ :numbered:
+
+ intro/index
+ install/index
+ config/index
+ replication/index
+ maintenance/index
+ couchapp/index
+ externals
+ query-server/index
+ fauxton/index
+ api/index
+ json-structure
+ contributing
+ whatsnew/index
+ cve/index
+
+.. This is how you get a TM sign into a link. Haha. Seriously.
+.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122
+.. _Apache CouchDB(TM): http://couchdb.apache.org/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
deleted file mode 100644
index f00aed6..0000000
--- a/share/doc/src/index.rst
+++ /dev/null
@@ -1,38 +0,0 @@
-.. 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.
-
-
-|Apache CouchDB(TM)|_ |release| Documentation
-=============================================
-
-.. toctree::
- :maxdepth: 3
- :numbered:
-
- intro/index
- install/index
- config/index
- replication/index
- maintenance/index
- couchapp/index
- externals
- query-server/index
- fauxton/index
- api/index
- json-structure
- contributing
- whatsnew/index
- cve/index
-
-.. This is how you get a TM sign into a link. Haha. Seriously.
-.. |Apache CouchDB(TM)| unicode:: Apache U+0020 CouchDB U+2122
-.. _Apache CouchDB(TM): http://couchdb.apache.org/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/templates/layout.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/layout.html b/share/doc/templates/layout.html
new file mode 100644
index 0000000..f5d1f2f
--- /dev/null
+++ b/share/doc/templates/layout.html
@@ -0,0 +1,27 @@
+<!--
+
+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.
+
+-->
+
+{% extends "!layout.html" %}
+{{ rellinks.append(('contents', 'Contents', '', 'Contents')) }}
+{%- block rootrellink %}
+ <li><a href="{{ pathto('index') }}">{{ shorttitle|e }}</a>{{ reldelim1 }}</li>
+{%- endblock %}
+{%- block sidebarlogo %}
+ {%- if logo %}
+ <p class="logo"><a href="{{ pathto('index') }}">
+ <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+ </a></p>
+ {%- endif %}
+{%- endblock %}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/18735b67/share/doc/templates/pages/index.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/pages/index.html b/share/doc/templates/pages/index.html
new file mode 100644
index 0000000..5d3b9b4
--- /dev/null
+++ b/share/doc/templates/pages/index.html
@@ -0,0 +1,156 @@
+<!--
+
+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.
+
+-->
+
+{% extends "defindex.html" %}
+{% block tables %}
+<h2>Meet CouchDB</h2>
+<table class="contentstable" align="center">
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("whatsnew/" + version) }}">
+ What's new in CouchDB {{ version }}?
+ </a>
+ <br />
+ <span class="linkdescr">
+ or browse <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a>
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/why") }}">
+ Why CouchDB?
+ </a>
+ <br />
+ <span class="linkdescr">reasons to use CouchDB is there</span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/overview") }}">
+ Technical Overview
+ </a>
+ <br />
+ <span class="linkdescr">quick overview about base technologies</span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/consistency") }}">
+ Eventual Consistency
+ </a>
+ <br />
+ <span class="linkdescr">the main conception of document databases</span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+<h2>Getting started</h2>
+<table class="contentstable" align="center">
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("install/index") }}">
+ Installation guides
+ </a>
+ <br />
+ <span class="linkdescr">
+ install CouchDB on <a href="{{ pathto("install/windows") }}">Windows</a>,
+ <a href="{{ pathto("install/macos") }}">MacOS X</a> or
+ <a href="{{ pathto("install/unix") }}">Linux</a> in few minutes.
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/tour") }}">
+ Tutorial
+ </a>
+ <br />
+ <span class="linkdescr">start using CouchDB with
+ <a href="{{ pathto("intro/futon") }}">Futon</a> and
+ <a href="{{ pathto("intro/curl") }}">cURL</a></span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("intro/api") }}">
+ HTTP API overview
+ </a>
+ <br />
+ <span class="linkdescr">short walk though API basics</span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("couchapp/views/intro") }}">
+ Guide to Views
+ </a>
+ <br />
+ <span class="linkdescr">how query JSON data with no sql</span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("replication/intro") }}">
+ Data Replication
+ </a>
+ <br />
+ <span class="linkdescr">
+ painless master-master data synchronization
+ </span>
+ </p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("config/index") }}">
+ Configuration Reference
+ </a>
+ <br />
+ <span class="linkdescr">tweak CouchDB like you want</span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+<h2>Developing with CouchDB</h2>
+<table class="contentstable" align="center"><tr>
+ <tr>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("api/index") }}">
+ Complete HTTP API Reference
+ </a>
+ <br />
+ <span class="linkdescr">
+ your favourite bookmark
+ </span>
+ </p>
+ <td width="50%">
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("couchapp/ddocs") }}">
+ Design Documents
+ </a>
+ <br />
+ <span class="linkdescr">
+ transform, update and validate documents like a rock star
+ </span>
+ </p>
+ </td>
+ </tr>
+</table>
+
+
+<h2>Links</h2>
+<table class="contentstable" align="center"><tr>
+ <td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Documentation Contents</a></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("http-api") }}">HTTP API Index</a></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("contributing") }}">Contributing to this Documentation</a></p>
+ </td><td width="50%">
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/">CouchDB Web site</a></p>
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/#download">Download</a></p>
+ <p class="biglink"><a class="biglink" href="http://couchdb.org/#mailing-list">Mailing Lists</a></p>
+ </td></tr>
+</table>
+{% endblock %}
[26/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Use own template to override the defaults.
Make HTTP API Index page looks nicer without top flat index.
May be one day we'll redesign docs to fit main site/fauxton style.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/fe79a4dc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/fe79a4dc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/fe79a4dc
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: fe79a4dcab08052ebaba3630e118b3fb5879143d
Parents: 1e23d25
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 15:29:54 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
NOTICE | 3 ++
share/doc/src/conf.py | 4 +-
share/doc/templates/couchdb/domainindex.html | 49 +++++++++++++++++++++++
share/doc/templates/couchdb/theme.conf | 13 ++++++
4 files changed, 68 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index da1b6d4..6a41c6c 100644
--- a/NOTICE
+++ b/NOTICE
@@ -186,3 +186,6 @@ This product also includes the following third-party components:
Copyright 2007, Christopher Lenz <cm...@gmail.com>
+ * share/doc/src/templates/couchdb/domainindex.html
+
+ Copyright 2007-2011 by the Sphinx team
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 9606213..3e6d5a3 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -64,7 +64,9 @@ highlight_language = "json"
pygments_style = "sphinx"
-html_theme = "default"
+html_theme = "couchdb"
+
+html_theme_path = ['../templates']
templates_path = ["../templates"]
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/templates/couchdb/domainindex.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/couchdb/domainindex.html b/share/doc/templates/couchdb/domainindex.html
new file mode 100644
index 0000000..38ff144
--- /dev/null
+++ b/share/doc/templates/couchdb/domainindex.html
@@ -0,0 +1,49 @@
+{#
+ basic/domainindex.html
+ ~~~~~~~~~~~~~~~~~~~~~~
+
+ Template for domain indices (module index, ...).
+
+ :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+#}
+{% extends "layout.html" %}
+{% set title = indextitle %}
+{% block extrahead %}
+{{ super() }}
+{% if not embedded and collapse_index %}
+ <script type="text/javascript">
+ DOCUMENTATION_OPTIONS.COLLAPSE_INDEX = true;
+ </script>
+{% endif %}
+{% endblock %}
+{% block body %}
+
+ {%- set groupid = idgen() %}
+
+ <h1>{{ indextitle }}</h1>
+
+ <table class="indextable modindextable" cellspacing="0" cellpadding="2">
+ {%- for letter, entries in content %}
+ <tr class="pcap"><td></td><td> </td><td></td></tr>
+ <tr class="cap" id="cap-{{ letter }}"><td></td><td>
+ <strong>{{ letter }}</strong></td><td></td></tr>
+ {%- for (name, grouptype, page, anchor, extra, qualifier, description)
+ in entries %}
+ <tr{% if grouptype == 2 %} class="cg-{{ groupid.current() }}"{% endif %}>
+ <td>{% if grouptype == 1 -%}
+ <img src="{{ pathto('_static/minus.png', 1) }}" class="toggler"
+ id="toggle-{{ groupid.next() }}" style="display: none" alt="-" />
+ {%- endif %}</td>
+ <td>{% if grouptype == 2 %} {% endif %}
+ {% if page %}<a href="{{ pathto(page) }}#{{ anchor }}">{% endif -%}
+ <tt class="xref">{{ name|e }}</tt>
+ {%- if page %}</a>{% endif %}
+ {%- if extra %} <em>({{ extra|e }})</em>{% endif -%}
+ </td><td>{% if qualifier %}<strong>{{ qualifier|e }}:</strong>{% endif %}
+ <em>{{ description|e }}</em></td></tr>
+ {%- endfor %}
+ {%- endfor %}
+ </table>
+
+{% endblock %}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/fe79a4dc/share/doc/templates/couchdb/theme.conf
----------------------------------------------------------------------
diff --git a/share/doc/templates/couchdb/theme.conf b/share/doc/templates/couchdb/theme.conf
new file mode 100644
index 0000000..546fca0
--- /dev/null
+++ b/share/doc/templates/couchdb/theme.conf
@@ -0,0 +1,13 @@
+; 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.
+
+[theme]
+inherit = default
[13/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Show more content from the main page.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/67de5f59
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/67de5f59
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/67de5f59
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 67de5f5959122abdaddabc3795c9ce585081a115
Parents: be3507b
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 20:58:05 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/67de5f59/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 1262375..047088e 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -24,7 +24,7 @@ Contents
========
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
:numbered:
intro
[22/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Respect copyright on content from external sources.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ee769ae0
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ee769ae0
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ee769ae0
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: ee769ae0cb0c2ead88811053265e7051d6df638e
Parents: ec2452b
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Aug 22 16:00:44 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:00:45 2013 +0400
----------------------------------------------------------------------
NOTICE | 4 ++++
share/doc/src/couchapp/views/joins.rst | 4 ++++
2 files changed, 8 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ee769ae0/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index 6c51a48..da1b6d4 100644
--- a/NOTICE
+++ b/NOTICE
@@ -182,3 +182,7 @@ This product also includes the following third-party components:
Copyright 2013, Creative Commons Attribution license
+ * share/doc/src/couchapp/views/joins.rst (Using View Collation)
+
+ Copyright 2007, Christopher Lenz <cm...@gmail.com>
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ee769ae0/share/doc/src/couchapp/views/joins.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/views/joins.rst b/share/doc/src/couchapp/views/joins.rst
index 3abae9d..3b95427 100644
--- a/share/doc/src/couchapp/views/joins.rst
+++ b/share/doc/src/couchapp/views/joins.rst
@@ -161,6 +161,10 @@ emit a ``"_rev"`` property as well as ``"_id"``.
Using View Collation
====================
+:Author: Christopher Lenz
+:Date: 2007-10-05
+:Source: http://www.cmlenz.net/archives/2007/10/couchdb-joins
+
Just today, there was a discussion on IRC how you'd go about modeling a simple
blogging system with “post” and “comment” entities, where any blog post might
have N comments. If you'd be using an SQL database, you'd obviously have two
[37/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Add download page.
Fixes COUCHDB-906
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/a16de046
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/a16de046
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/a16de046
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: a16de04618620e293f74992061ba29569ac3da2c
Parents: 1449a37
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Sep 2 03:25:15 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 1 +
share/doc/src/conf.py | 8 ++++-
share/doc/templates/help.html | 1 +
share/doc/templates/pages/download.html | 48 ++++++++++++++++++++++++++++
4 files changed, 57 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index dcc1150..16ed5d6 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -391,6 +391,7 @@ src_files = \
src_files_html = \
../static/rtd.css \
+ ../templates/pages/download.html \
../templates/help.html \
../templates/searchbox.html \
../templates/utilities.html
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 04b7079..7c49bbf 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -90,6 +90,12 @@ html_favicon = "../images/favicon.ico"
html_use_index = False
+html_additional_pages = {
+ 'download': 'pages/download.html'
+}
+
+html_context = {}
+
html_sidebars = {
"**": [
"searchbox.html",
@@ -133,7 +139,7 @@ extlinks = {
github_project = 'apache/couchdb'
-github_branch = 'master'
+html_context['git_branch'] = github_branch = 'master'
github_docs_path = 'share/doc/src'
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/templates/help.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/help.html b/share/doc/templates/help.html
index fcc75c5..be0cb91 100644
--- a/share/doc/templates/help.html
+++ b/share/doc/templates/help.html
@@ -21,6 +21,7 @@ specific language governing permissions and limitations under the License.
<li><a href="https://couchdb.apache.org/#mailing-list">Mailing Lists</a></li>
<li><a href="http://webchat.freenode.net/?channels=couchdb">IRC</a></li>
<li><a href="https://issues.apache.org/jira/browse/CouchDB">Issues</a></li>
+<li><a href="{{ pathto('download') }}">Download</a></li>
{%- if github_show_url %}
<li><a href="{{ github_show_url }}"
rel="nofollow">{{ _('Show on GitHub') }}</a></li>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/a16de046/share/doc/templates/pages/download.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/pages/download.html b/share/doc/templates/pages/download.html
new file mode 100644
index 0000000..76fe93d
--- /dev/null
+++ b/share/doc/templates/pages/download.html
@@ -0,0 +1,48 @@
+<!--
+
+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.
+
+-->
+
+{% extends "layout.html" %}
+{% set title = 'Download' %}
+{% set url = 'https://media.readthedocs.org/%s/couchdb/%s/couchdb.%s' %}
+{% if git_branch == 'master' %}
+ {% set rtd_ver = 'latest' %}
+{% else %}
+ {% set rtd_ver = git_branch %}
+{% endif %}
+
+{% block body %}
+<h1>Download Apache CouchDB™ {{ release }} Documentation</h1>
+
+<p>To download an archive containing all the documents for this version of
+CouchDB in one of various formats, follow one of links in this table</p>
+
+<table class="docutils">
+ <tr>
+ <td>PDF (A4 paper size)</td>
+ <td><a href="{{ url|format('pdf', rtd_ver, 'pdf') }}">Download</a> (~1 MB)</td>
+ </tr>
+ <tr>
+ <td>HTML</td>
+ <td><a href="{{ url|format('htmlzip', rtd_ver, 'zip') }}">Download</a> (~5 MB)</td>
+ </tr>
+ <tr>
+ <td>EPUB</td>
+ <td><a href="{{ url|format('epub', rtd_ver, 'epub') }}">Download</a> (~1 MB)</td>
+ </tr>
+</table>
+
+<p>These archives contain all the content of the documentation.</p>
+
+{% endblock %}
[03/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Handle ANY method as placeholder for any HTTP request method.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/d5d3c8af
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/d5d3c8af
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/d5d3c8af
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: d5d3c8af33d54f0d9c2ac62122ed3fa322911b75
Parents: 233cc4f
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 15:42:25 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/d5d3c8af/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index a873a8b..a36493f 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -82,7 +82,8 @@ METHOD_REFS = {
'delete': RFC2616Ref(9.7),
'trace': RFC2616Ref(9.8),
'connect': RFC2616Ref(9.9),
- 'copy': IETFRef(2518, 8.8)
+ 'copy': IETFRef(2518, 8.8),
+ 'any': ''
}
#: Mapping from HTTP header name to :class:`DocRef` object which
@@ -333,6 +334,11 @@ class HTTPCopy(HTTPResource):
method = 'copy'
+class HTTPAny(HTTPResource):
+
+ method = 'any'
+
+
def http_statuscode_role(name, rawtext, text, lineno, inliner,
options=None, content=None):
if options is None:
@@ -467,7 +473,8 @@ class HTTPDomain(Domain):
'patch': ObjType('patch', 'patch', 'obj'),
'delete': ObjType('delete', 'delete', 'obj'),
'trace': ObjType('trace', 'trace', 'obj'),
- 'copy': ObjType('copy', 'copy', 'obj')
+ 'copy': ObjType('copy', 'copy', 'obj'),
+ 'any': ObjType('any', 'any', 'obj')
}
directives = {
@@ -479,7 +486,8 @@ class HTTPDomain(Domain):
'patch': HTTPPatch,
'delete': HTTPDelete,
'trace': HTTPTrace,
- 'copy': HTTPCopy
+ 'copy': HTTPCopy,
+ 'any': HTTPAny
}
roles = {
@@ -492,6 +500,7 @@ class HTTPDomain(Domain):
'delete': HTTPXRefRole('delete'),
'trace': HTTPXRefRole('trace'),
'copy': HTTPXRefRole('copy'),
+ 'all': HTTPXRefRole('all'),
'statuscode': http_statuscode_role,
'method': http_method_role,
'header': http_header_role
@@ -506,7 +515,8 @@ class HTTPDomain(Domain):
'patch': {},
'delete': {},
'trace': {},
- 'copy': {}
+ 'copy': {},
+ 'any': {}
}
indices = [HTTPIndex]
[46/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
docs: use sphinx automatic version numbers for protocol responses
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/508b565d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/508b565d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/508b565d
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 508b565d2d425bd31fb155538e2be20647ae0846
Parents: cf4a09b
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 14:17:07 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/basics.rst | 4 +--
share/doc/src/api/database/bulk-api.rst | 4 +--
share/doc/src/api/database/changes.rst | 2 +-
share/doc/src/api/database/common.rst | 18 ++++++-------
share/doc/src/api/database/compact.rst | 8 +++---
share/doc/src/api/database/misc.rst | 10 ++++----
share/doc/src/api/database/security.rst | 4 +--
share/doc/src/api/database/temp-views.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/ddoc/render.rst | 12 ++++-----
share/doc/src/api/ddoc/views.rst | 12 ++++-----
share/doc/src/api/document/attachments.rst | 6 ++---
share/doc/src/api/document/common.rst | 34 ++++++++++++-------------
share/doc/src/api/server/authn.rst | 14 +++++-----
share/doc/src/api/server/common.rst | 16 ++++++------
share/doc/src/api/server/configuration.rst | 12 ++++-----
share/doc/src/config/auth.rst | 4 +--
share/doc/src/config/couchdb.rst | 2 +-
share/doc/src/config/http.rst | 2 +-
share/doc/src/config/misc.rst | 2 +-
share/doc/src/externals.rst | 4 +--
share/doc/src/intro/api.rst | 8 +++---
share/doc/src/maintenance/compaction.rst | 8 +++---
23 files changed, 95 insertions(+), 95 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/basics.rst b/share/doc/src/api/basics.rst
index 74465b6..d05ddb6 100644
--- a/share/doc/src/api/basics.rst
+++ b/share/doc/src/api/basics.rst
@@ -160,7 +160,7 @@ Request Headers
.. code-block:: http
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+ Server: CouchDB (Erlang/OTP)
Date: Thu, 13 Jan 2011 13:39:34 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 227
@@ -181,7 +181,7 @@ Request Headers
.. code-block:: http
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Date: Thu, 13 Jan 2013 13:40:11 GMT
Content-Type: application/json
Content-Length: 227
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index 148da3d..9017227 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -85,7 +85,7 @@
Content-Type: application/json
Date: Sat, 10 Aug 2013 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -258,7 +258,7 @@
Content-Length: 144
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:15:05 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
[
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 52a38a7..344a3bb 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -102,7 +102,7 @@
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:54:58 GMT
ETag: "6ASLEKEMSRABT0O5XY9UPO9Z"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 2fb525f..ecf31fe 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -40,7 +40,7 @@
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:27:41 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}
@@ -86,7 +86,7 @@
Content-Length: 258
Content-Type: application/json
Date: Mon, 12 Aug 2013 01:38:57 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"committed_update_seq": 292786,
@@ -152,7 +152,7 @@
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:45 GMT
Location: http://localhost:5984/db
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -178,7 +178,7 @@
Content-Length: 95
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:01:16 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "file_exists",
@@ -204,7 +204,7 @@
Content-Length: 194
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:02:10 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "illegal_database_name",
@@ -245,7 +245,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 08:54:00 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -311,7 +311,7 @@
Date: Tue, 13 Aug 2013 15:19:25 GMT
ETag: "1-9c65296036141e575d32ba9c034dd3ee"
Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "ab39fe0993049b84cfa81acd6ebad09d",
@@ -354,7 +354,7 @@ document with the ID ``FishStew``.
Date: Tue, 13 Aug 2013 15:19:25 GMT
ETag: "1-9c65296036141e575d32ba9c034dd3ee"
Location: http://localhost:5984/db/FishStew
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
@@ -411,7 +411,7 @@ respond with a HTTP :http:statuscode:`202` response code immediately.
Content-Type: application/json
Date: Tue, 13 Aug 2013 15:19:25 GMT
Location: http://localhost:5984/db/FishStew
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 51e9c3f..42d99eb 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -73,7 +73,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -124,7 +124,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:36:44 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -172,7 +172,7 @@
Content-Length: 53
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:22:19 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"instance_start_time": "1376269047459338",
@@ -219,7 +219,7 @@
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 09:27:43 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index b0c3706..d3507a5 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -82,7 +82,7 @@
Content-Length: 103
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"purge_seq":3,
@@ -162,7 +162,7 @@ database must be examined.
Content-Length: 64
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"missed_revs":{
@@ -237,7 +237,7 @@ database must be examined.
Content-Length: 88
Content-Type: application/json
Date: Mon, 12 Aug 2013 16:56:02 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"190f721ca3411be7aa9477db5f948bbb": {
@@ -281,7 +281,7 @@ database must be examined.
Content-Length: 5
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:27:30 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
1000
@@ -324,7 +324,7 @@ database must be examined.
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:47:52 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/security.rst b/share/doc/src/api/database/security.rst
index 1856579..551e5a8 100644
--- a/share/doc/src/api/database/security.rst
+++ b/share/doc/src/api/database/security.rst
@@ -92,7 +92,7 @@
Content-Length: 109
Content-Type: application/json
Date: Mon, 12 Aug 2013 19:05:29 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"admins": {
@@ -172,7 +172,7 @@
Content-Length: 12
Content-Type: application/json
Date: Tue, 13 Aug 2013 11:26:28 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/temp-views.rst b/share/doc/src/api/database/temp-views.rst
index 9bcecb5..0b576b8 100644
--- a/share/doc/src/api/database/temp-views.rst
+++ b/share/doc/src/api/database/temp-views.rst
@@ -53,7 +53,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 12:28:12 GMT
ETag: "AU33B3N7S9K4SAZSFA048HVB4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 0d6ec17..1e5b183 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -172,7 +172,7 @@
Content-Length: 263
Content-Type: application/json
Date: Sat, 17 Aug 2013 12:54:17 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"name": "recipe",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/render.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/render.rst b/share/doc/src/api/ddoc/render.rst
index c87824c..9c6b1c4 100644
--- a/share/doc/src/api/ddoc/render.rst
+++ b/share/doc/src/api/ddoc/render.rst
@@ -62,7 +62,7 @@
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:34:07 GMT
Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Vary: Accept
no doc
@@ -120,7 +120,7 @@
Content-Type: text/html; charset=utf-8
Date: Wed, 21 Aug 2013 12:38:08 GMT
Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Vary: Accept
An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.
@@ -181,7 +181,7 @@
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept
@@ -244,7 +244,7 @@
Content-Type: text/plain; charset=utf-8
Date: Wed, 21 Aug 2013 12:49:15 GMT
Etag: "5L0975X493R0FB5Z3043POZHD"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
Vary: Accept
@@ -306,7 +306,7 @@
Content-Length: 52
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:00:58 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "missed",
@@ -371,7 +371,7 @@
Content-Length: 16
Content-Type: application/json
Date: Wed, 21 Aug 2013 14:11:34 GMT
- Server: CouchDB/1.4.0+build.c843cef (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
X-Couch-Id: SpaghettiWithMeatballs
X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index bb45095..ade789c 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -97,7 +97,7 @@
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:12:06 GMT
ETag: "2FOLSBSW4O6WB798XU4AQYA9B"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -157,7 +157,7 @@
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "6R5NM8E872JIJF796VF7WI3FZ"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -339,7 +339,7 @@ content. The basic order of output is as follows:
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -467,7 +467,7 @@ You can reverse the order of the returned view information by using the
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "Z4N468R15JBT98OM0AMNSR8U"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -669,7 +669,7 @@ in view:
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -738,7 +738,7 @@ To omit some records you may use ``skip`` query parameter:
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index 3f3e8d4..34526fc 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -66,7 +66,7 @@
Content-Type: text/plain
Date: Thu, 15 Aug 2013 12:42:42 GMT
ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}/{docid}/{attname}
@@ -172,7 +172,7 @@
Date: Thu, 15 Aug 2013 12:38:04 GMT
ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -243,7 +243,7 @@
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:13 GMT
ETag: "7-05185cf5fcdf4b6da360af939431d466"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index adbf03e..03b1de1 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -59,7 +59,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
.. http:get:: /{db}/{docid}
@@ -150,7 +150,7 @@
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -227,7 +227,7 @@
Date: Wed, 14 Aug 2013 20:31:39 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -299,7 +299,7 @@
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:13 GMT
ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "FishStew",
@@ -365,7 +365,7 @@
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Italian",
@@ -429,7 +429,7 @@ Basic Attachments Info
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -491,7 +491,7 @@ It's possible to retrieve document with all attached files content by using
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:32:40 GMT
ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -533,7 +533,7 @@ query parameter:
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -594,7 +594,7 @@ about compressed attachments size and used codec.
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_attachments": {
@@ -660,7 +660,7 @@ the ``revs=true`` parameter to the request URL:
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:38:26 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -719,7 +719,7 @@ document by supplying the ``revs_info`` argument to the query:
Content-Length: 802
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -807,7 +807,7 @@ requested.
Content-Length: 271
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
@@ -847,7 +847,7 @@ response:
Content-Length: 41
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:27 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"error": "not_found",
@@ -875,7 +875,7 @@ with :http:get:`/{db}/{docid}` request:
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:30:22 GMT
ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"_deleted": true,
@@ -947,7 +947,7 @@ Alternatively, you can supply the current revision number in the
Date: Wed, 14 Aug 2013 20:33:56 GMT
ETag: "2-790895a73b63fb91dd863388398483dd"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
@@ -983,7 +983,7 @@ string or :http:header:`If-Match`:
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
@@ -1019,7 +1019,7 @@ string for the target document by appending the ``rev`` parameter to the
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "2-62e778c9ec09214dd685a981dcc24074""
Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index 0b44920..ce08277 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -51,7 +51,7 @@ CouchDB must compute password hash with every request):
Content-Length: 177
Content-Type: application/json
Date: Mon, 03 Dec 2012 00:44:47 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb":"Welcome",
@@ -143,7 +143,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 43
Content-Type: application/json
Date: Mon, 03 Dec 2012 01:23:14 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MEJCRkYwMjq0LO0ylOIwShrgt8y-UkhI-c6BGw; Version=1; Path=/; HttpOnly
{"ok":true,"name":"root","roles":["_admin"]}
@@ -172,7 +172,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Type: application/json
Date: Mon, 03 Dec 2012 01:32:46 GMT
Location: http://localhost:5984/blog/_design/sofa/_rewrite/recent-posts
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MEJDMDEzRTp7Vu5GKCkTxTVxwXbpXsBARQWnhQ; Version=1; Path=/; HttpOnly
{"ok":true,"name":null,"roles":["_admin"]}
@@ -207,7 +207,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 175
Content-Type: application/json
Date: Fri, 09 Aug 2013 20:27:45 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=cm9vdDo1MjA1NTBDMTqmX2qKt1KDR--GUC80DQ6-Ew_XIw; Version=1; Path=/; HttpOnly
{
@@ -255,7 +255,7 @@ To obtain the first token and thus authenticate a user for the first time, the
Content-Length: 12
Content-Type: application/json
Date: Fri, 09 Aug 2013 20:30:12 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
Set-Cookie: AuthSession=; Version=1; Path=/; HttpOnly
{
@@ -317,7 +317,7 @@ headers to CouchDB with related request:
Content-Length: 190
Content-Type: application/json
Date: Fri, 14 Jun 2013 10:16:03 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{
"info": {
@@ -430,7 +430,7 @@ Both snippets produces similar request and response pair:
Content-Length : 167
Content-Type : application/json
Date : Tue, 23 Jul 2013 06:51:15 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 22e312d..f58403f 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -46,7 +46,7 @@
Content-Length: 179
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:33:33 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb": "Welcome",
@@ -105,7 +105,7 @@
Content-Length: 1690
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:37:31 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
[
{
@@ -194,7 +194,7 @@
Content-Length: 52
Content-Type: application/json
Date: Sat, 10 Aug 2013 06:57:48 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
[
"_users",
@@ -253,7 +253,7 @@
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 10 Aug 2013 07:02:41 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked
{
@@ -415,7 +415,7 @@ jumping to ``offset`` bytes towards the beginning of the file first:
Content-Length: 692
Content-Type: application/json
Date: Sun, 11 Aug 2013 20:38:50 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"history": [
@@ -695,7 +695,7 @@ a 404 error.
Content-Length: 12
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:33:50 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"ok": true
@@ -738,7 +738,7 @@ a 404 error.
Content-Length: 187
Content-Type: application/json
Date: Sat, 10 Aug 2013 11:41:11 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"couchdb": {
@@ -939,7 +939,7 @@ structure is as follows:
ETag: "DGRWWQFLUDWN5MRKSLKQ425XV"
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Pragma: no-cache
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
{
"uuids": [
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
index 41270dd..e974328 100644
--- a/share/doc/src/api/server/configuration.rst
+++ b/share/doc/src/api/server/configuration.rst
@@ -53,7 +53,7 @@ CouchDB instance.
Content-Length: 4148
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:01:42 GMT
- Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"attachments": {
@@ -75,7 +75,7 @@ CouchDB instance.
"max_document_size": "4294967296",
"os_process_timeout": "5000",
"uri_file": "/var/lib/couchdb/couch.uri",
- "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
+ "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.5.0/priv/lib",
"view_index_dir": "/var/lib/couchdb"
},
"daemons": {
@@ -188,7 +188,7 @@ CouchDB instance.
Content-Length: 444
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:10:40 GMT
- Server: CouchDB/1.4.0+build.c843cef (Erlang OTP/R16B)
+ Server: CouchDB (Erlang/OTP)
{
"allow_jsonp": "false",
@@ -239,7 +239,7 @@ CouchDB instance.
Content-Length: 8
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"debug"
@@ -290,7 +290,7 @@ CouchDB instance.
Content-Length: 8
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"debug"
@@ -327,6 +327,6 @@ CouchDB instance.
Content-Length: 7
Content-Type: application/json
Date: Sat, 10 Aug 2013 12:29:03 GMT
- Server: CouchDB/1.3.1 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"info"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 279e124..85d0dbb 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -54,7 +54,7 @@ supports querying, deleting or creating new admin accounts:
Content-Length: 196
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:37:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
.. code-block:: json
@@ -85,7 +85,7 @@ encrypt it.
Content-Length: 89
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:39:18 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B02)
+ Server: CouchDB (Erlang/OTP)
"-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index c1bd182..d42e5b8 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -196,7 +196,7 @@ its contents should be readable for the user that runs the CouchDB service.
::
[couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
+ util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
.. _config/couchdb/uuid:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index f225092..68981bf 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -368,7 +368,7 @@ specify the ``-k`` option as the message reads:
.. code-block:: bash
shell> curl -k https://127.0.0.1:6984/
- {"couchdb":"Welcome","version":"1.3.0"}
+ {"couchdb":"Welcome","version":"1.5.0"}
All done.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index 235142d..079f2f4 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -218,4 +218,4 @@ message. This is returned when requesting ``GET /``.
[vendor]
name = The Apache Software Foundation
- version = 1.3.0
+ version = 1.5.0
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 9b4530f..9068e75 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -233,7 +233,7 @@ And then start CouchDB and try:
>
< HTTP/1.1 200
< Transfer-Encoding: chunked
- < Server: CouchDB/1.3.0 (Erlang OTP/R14B)
+ < Server: CouchDB (Erlang/OTP)
< Date: Mon, 27 Sep 2010 01:13:37 GMT
< Content-Type: text/plain
< Connection: keep-alive
@@ -244,7 +244,7 @@ And then start CouchDB and try:
The corresponding CouchDB logs look like::
- Apache CouchDB 1.3.0 (LogLevel=info) is starting.
+ Apache CouchDB 1.5.0 (LogLevel=info) is starting.
Apache CouchDB has started. Time to relax.
[info] [<0.31.0>] Apache CouchDB has started on http://127.0.0.1:5984/
[info] [<0.105.0>] 127.0.0.1 - - 'GET' /_hello 200
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/intro/api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/api.rst b/share/doc/src/intro/api.rst
index f617df0..9779ea9 100644
--- a/share/doc/src/intro/api.rst
+++ b/share/doc/src/intro/api.rst
@@ -62,9 +62,9 @@ CouchDB replies, all excited to get going:
"uuid": "85fb71bf700c17267fef77535820e371",
"vendor": {
"name": "The Apache Software Foundation",
- "version": "1.4.0"
+ "version": "1.5.0"
},
- "version": "1.4.0"
+ "version": "1.5.0"
}
You get back a JSON string, that, if parsed into a native object or data
@@ -136,7 +136,7 @@ curl elaborates::
> Accept: */*
>
< HTTP/1.1 201 Created
- < Server: CouchDB/0.9.0 (Erlang OTP/R12B)
+ < Server: CouchDB (Erlang/OTP)
< Date: Sun, 05 Jul 2009 22:48:28 GMT
< Content-Type: text/plain;charset=utf-8
< Content-Length: 12
@@ -242,7 +242,7 @@ code.
::
- < Server: CouchDB/0.10.1 (Erlang OTP/R13B)
+ < Server: CouchDB (Erlang/OTP)
The :header:`Server` header is good for diagnostics. It tells us which
CouchDB version and which underlying Erlang version we are talking to.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/508b565d/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
index c2859bf..a24e008 100644
--- a/share/doc/src/maintenance/compaction.rst
+++ b/share/doc/src/maintenance/compaction.rst
@@ -58,7 +58,7 @@ On success, HTTP status :http:statuscode:`202` is returned immediately:
Content-Length: 12
Content-Type: text/plain; charset=utf-8
Date: Wed, 19 Jun 2013 09:43:52 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
.. code-block:: javascript
@@ -76,7 +76,7 @@ for the request. If you don't, you will be aware about with HTTP status
Content-Length: 78
Content-Type: application/json
Date: Wed, 19 Jun 2013 09:43:44 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{"error":"bad_content_type","reason":"Content-Type must be application/json"}
@@ -92,7 +92,7 @@ information about it via :ref:`database information resource <api/db>`::
Content-Length: 246
Content-Type: application/json
Date: Wed, 19 Jun 2013 16:51:20 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
{
"committed_update_seq": 76215,
@@ -122,7 +122,7 @@ is actually running. To track the compaction progress you may query the
Content-Length: 175
Content-Type: application/json
Date: Wed, 19 Jun 2013 16:27:23 GMT
- Server: CouchDB/1.3.0 (Erlang OTP/R15B03)
+ Server: CouchDB (Erlang/OTP)
[
{
[07/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Be project-neutral.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1ec0b0b2
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1ec0b0b2
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1ec0b0b2
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 1ec0b0b215731de80031f6e4adea690cb8db2834
Parents: 5dbd905
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Aug 15 23:08:00 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1ec0b0b2/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index fb7cff0..a873a8b 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -434,7 +434,7 @@ class HTTPXRefRole(XRefRole):
class HTTPIndex(Index):
name = 'api'
- localname = 'CouchDB HTTP API Reference'
+ localname = 'HTTP API Reference'
shortname = 'API Reference'
def generate(self, docnames=None):
[32/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Wrong image for temporary views.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5562be1a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5562be1a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5562be1a
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5562be1ad33f525a0b7f91481ca720f6c35e0dd3
Parents: d1e3b5d
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:43:45 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/images/intro-tour-07.png | Bin 47487 -> 67121 bytes
1 file changed, 0 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5562be1a/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
index e75987d..229ce63 100644
Binary files a/share/doc/images/intro-tour-07.png and b/share/doc/images/intro-tour-07.png differ
[27/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update intro response.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/71ec7568
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/71ec7568
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/71ec7568
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 71ec7568627cae62b93e6785c8083a2e4f4cb4d7
Parents: b35bf75
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Aug 25 17:29:07 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/intro.rst | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/71ec7568/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
index 6f3603b..57eb235 100644
--- a/share/doc/src/intro.rst
+++ b/share/doc/src/intro.rst
@@ -227,10 +227,16 @@ clarity):
.. code-block:: json
- {
- "couchdb" : "Welcome",
- "version" : "|version|",
- }
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
.. note:: For some URLs, especially those that include special characters such
as ampersand, exclamation mark, or question mark, you should quote
[14/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Changed Mac OS X section
MacOS is now Mac OS X. Added "Installation using the Apache CouchDB native application" section (inspired by MySQL documentation), simplified MacPorts section. Who chose MacPorts in favor of the native app is because already using MacPorts, so he knows how to upgrade packages, make the selfupdate, etc.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/be3507b7
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/be3507b7
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/be3507b7
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: be3507b7c3c8d404c0dc486038e2428ff50e0354
Parents: 3017c9a
Author: Filippo Fadda <fi...@gmail.com>
Authored: Wed Aug 21 20:55:13 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/install/mac.rst | 66 +++++++++++++++++++++++++++++---------
1 file changed, 51 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/be3507b7/share/doc/src/install/mac.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/mac.rst b/share/doc/src/install/mac.rst
index 5cfeab0..2f7a12d 100644
--- a/share/doc/src/install/mac.rst
+++ b/share/doc/src/install/mac.rst
@@ -13,26 +13,63 @@
.. _install/mac:
-=====================
-Installation on MacOS
-=====================
+========================
+Installation on Mac OS X
+========================
+
.. _install/mac/binary:
-Install from binaries
-=====================
+Installation using the Apache CouchDB native application
+========================================================
+
+The easiest way to run CouchDB on Mac OS X is through his native Mac OS X
+application. Just follow the below instructions:
-#. Get `the latest MacOS binaries`_ from `CouchDB web site`_.
+#. `Download Apache CouchDB for Mac OS X`_.
Old releases are available at `archive`_.
-#. Unzip it and place CouchDB Server into the Applications directory
-#. Run CouchDB
-#. `Open up Futon`_
-#. It's time to Relax!
+#. Double click on the Zip file
+#. Drag and drop the Apache CouchDB.app into Applications folder
-.. _Open up Futon: http://localhost:5984/_utils
-.. _CouchDB web site: http://couchdb.org/
+.. _Download Apache CouchDB for Mac OS X: http://couchdb.org/#download
.. _archive: http://archive.apache.org/dist/couchdb/binary/mac/
-.. _the latest MacOS binaries: http://couchdb.org/#download
+
+That's all, now CouchDB is installed on your Mac:
+
+#. Run Apache CouchDB application
+#. `Open up Futon`_, the CouchDB admin interface
+#. Time to Relax!
+
+.. _Open up Futon: http://localhost:5984/_utils
+
+
+.. _install/mac/macports:
+
+Installation from MacPorts
+==========================
+
+To install CouchDB using MacPorts you have 2 package choices:
+
+- ``couchdb`` - the latest release version
+- ``couchdb-devel`` - updated every few weeks from the master branch
+
+::
+
+ $ sudo port install couchdb
+
+or, if you want the last development version:
+
+ $ sudo port install couchdb-devel
+
+MacPorts takes care of installing all necessary dependencies.
+It should now be up and accessible via Futon at http://127.0.0.1:5984/_utils.
+
+If you want to run CouchDB as a service, load the launchd configuration which
+comes with the project, with this command::
+
+ $ sudo port load couchdb
+
+Now CouchDB should be started automatically after every reboot.
.. _install/mac/homebrew:
@@ -67,7 +104,7 @@ The same is true for recent versions of Erlang::
Now it's time to brew CouchDB::
- brew install couchdb
+ brew install couchdb
The above Erlang install will use the bottled (pre-compiled) version if you are:
@@ -185,4 +222,3 @@ to reflect the latest versions of available packages. In order to do that run::
$ sudo port selfupdate
to update the port tree, and then install just as explained.
-
[16/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update Render functions API reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/4884898d
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/4884898d
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/4884898d
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 4884898da8e6038ad78b450c70eae48d6b849b9b
Parents: efb7655
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Aug 21 20:14:41 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:46 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/render.rst | 404 +++++++++++++++++++++++++++------
1 file changed, 329 insertions(+), 75 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/4884898d/share/doc/src/api/ddoc/render.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/render.rst b/share/doc/src/api/ddoc/render.rst
index f22f629..c87824c 100644
--- a/share/doc/src/api/ddoc/render.rst
+++ b/share/doc/src/api/ddoc/render.rst
@@ -12,115 +12,369 @@
.. _api/ddoc/show:
-.. _api/ddoc/show.get:
-``GET /db/_design/design-doc/_show/show-name``
-===============================================
+``/db/_design/design-doc/_show/show-name``
+==========================================
-.. todo:: GET /db/_design/design-doc/_show/show-name
+.. http:get:: /{db}/_design/{ddoc}/_show/{func}
+.. http:post:: /{db}/_design/{ddoc}/_show/{func}
-* **Method**: ``GET /db/_design/design-doc/_show/show-name``
-* **Request**: None
-* **Response**: Returns the result of the show
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+ Applies :ref:`show function <showfun>` for `null` document.
- * **Argument**: details
+ The request and response parameters are depended upon function implementation.
- * **Description**: Indicates whether details should be included
- * **Optional**: yes
- * **Type**: string
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Show function name
+ :>header ETag: Response signature
+ :query boolean details: Indicates whether details should be included
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
- * **Argument**: format
+ **Function**:
- * **Description**: Format of the returned information
- * **Optional**: yes
- * **Type**: string
+ .. code-block:: javascript
-.. _api/ddoc/show/doc.post:
+ function(doc, req) {
+ if (!doc) {
+ return {body: "no doc"}
+ } else {
+ return {body: doc.description}
+ }
+ }
-``POST /db/_design/design-doc/_show/show-name/doc``
-===================================================
+ **Request**:
-.. todo:: POST /db/_design/design-doc/_show/show-name/doc
+ .. code-block:: http
-* **Method**: ``POST /db/_design/design-doc/_show/show-name``
-* **Request**: Custom data
-* **Response**: Returns the result of the show
-* **Admin Privileges Required**: no
+ GET /recipes/_design/recipe/_show/description HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-.. _api/ddoc/list/ddoc:
-.. _api/ddoc/list/ddoc.get:
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Length: 6
+ Content-Type: text/html; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:34:07 GMT
+ Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Vary: Accept
+
+ no doc
+
+
+.. _api/ddoc/show/id:
+
+``/db/_design/design-doc/_show/show-name/doc-id``
+=================================================
+
+.. http:get:: /{db}/_design/{ddoc}/_show/{func}/{docid}
+.. http:post:: /{db}/_design/{ddoc}/_show/{func}/{docid}
+
+ Applies :ref:`show function <showfun>` for the specified document.
-``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-=========================================================================
+ The request and response parameters are depended upon function implementation.
-.. todo:: GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Show function name
+ :param docid: Document ID
+ :>header ETag: Response signature
+ :query boolean details: Indicates whether details should be included
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
+ **Function**:
-.. _api/ddoc/list/ddoc.post:
+ .. code-block:: javascript
-``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-==========================================================================
+ function(doc, req) {
+ if (!doc) {
+ return {body: "no doc"}
+ } else {
+ return {body: doc.description}
+ }
+ }
-.. todo:: POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/_design/recipe/_show/description/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Length: 88
+ Content-Type: text/html; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:38:08 GMT
+ Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Vary: Accept
+
+ An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
.. _api/ddoc/list:
-.. _api/ddoc/list.get:
-``GET /db/_design/design-doc/_list/list-name/view-name``
-========================================================
+``/db/_design/design-doc/_list/list-name/view-name``
+====================================================
-.. todo:: GET /db/_design/design-doc/_list/list-name/view-name
+.. http:get:: /{db}/_design/{ddoc}/_list/{func}/{view}
+.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{view}
-* **Method**: ``GET /db/_design/design-doc/_list/list-name/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
+ Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
+ from the same design document.
-.. _api/ddoc/list.post:
+ The request and response parameters are depended upon function implementation.
-``POST /db/_design/design-doc/_list/list-name/view-name``
-=========================================================
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: List function name
+ :param view: View function name
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
-.. todo:: POST /db/_design/design-doc/_list/list-name/view-name
+ **Function**:
-* **Method**: ``POST /db/_design/design-doc/_list/list-name/view-name``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
+ .. code-block:: javascript
-.. _api/ddoc/update/doc:
-.. _api/ddoc/update/doc.put:
+ function(head, req) {
+ var row = getRow();
+ if (!row){
+ return 'no ingredients'
+ }
+ send(row.key);
+ while(row=getRow()){
+ send(', ' + row.key);
+ }
+ }
-``PUT /db/_design/design-doc/_update/updatename/doc``
-=====================================================
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/_design/recipe/_list/ingredients/by_name HTTP/1.1
+ Accept: text/plain
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:49:15 GMT
+ Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+ Vary: Accept
+
+ meatballs, spaghetti, tomato sauce
+
+
+.. _api/ddoc/list/ddoc:
+
+``/db/_design/design-doc/_list/list-name/other-ddoc/view-name``
+===============================================================
+
+.. http:get:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
+.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
+
+ Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
+ from the other design document.
+
+ The request and response parameters are depended upon function implementation.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: List function name
+ :param other-ddoc: Other design document name that holds view function
+ :param view: View function name
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
+
+ **Function**:
+
+ .. code-block:: javascript
+
+ function(head, req) {
+ var row = getRow();
+ if (!row){
+ return 'no ingredients'
+ }
+ send(row.key);
+ while(row=getRow()){
+ send(', ' + row.key);
+ }
+ }
+
+ **Request**:
+
+ .. code-block:: http
-.. todo:: POST /db/_design/design-doc/_update/updatename/doc
+ GET /recipes/_design/ingredient/_list/ingredients/recipe/by_ingredient?key="spaghetti" HTTP/1.1
+ Accept: text/plain
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:49:15 GMT
+ Etag: "5L0975X493R0FB5Z3043POZHD"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+ Vary: Accept
+
+ spaghetti
-* **Method**: ``POST /db/_design/design-doc/_update/updatename/doc``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
.. _api/ddoc/update:
-.. _api/ddoc/update.post:
-``POST /db/_design/design-doc/_update/updatename``
-==================================================
+``/db/_design/design-doc/_update/update-name``
+==============================================
+
+.. http:post:: /{db}/_design/{ddoc}/_update/{func}
+
+ Executes :ref:`update function <updatefun>` on server side for ``null``
+ document.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Update function name
+ :>header X-Couch-Id: Created/updated document's ID
+ :>header X-Couch-Update-NewRev: Created/updated document's revision
+ :code 200: No document was created or updated
+ :code 201: Document was created or updated
+ :code 500: Query server error
+
+ **Function**:
+
+ .. code-block:: javascript
+
+ function(doc, req) {
+ if (!doc){
+ return [null, {'code': 400,
+ 'json': {'error': 'missed',
+ 'reason': 'no document to update'}}]
+ } else {
+ doc.ingredients.push(req.body);
+ return [doc, {'json': {'status': 'ok'}}];
+ }
+ }
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_design/recipe/_update/ingredients HTTP/1.1
+ Accept: application/json
+ Content-Length: 10
+ Content-Type: application/json
+ Host: localhost:5984
+
+ something
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 404 Object Not Found
+ Cache-Control: must-revalidate
+ Content-Length: 52
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 14:00:58 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "error": "missed",
+ "reason": "no document to update"
+ }
+
+
+.. _api/ddoc/update/id:
+
+``/db/_design/design-doc/_update/update-name/doc-id``
+=====================================================
+
+.. http:put:: /{db}/_design/{ddoc}/_update/{func}/{docid}
+
+
+ Executes :ref:`update function <updatefun>` on server side for the specified
+ document.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Update function name
+ :param docid: Document ID
+ :>header X-Couch-Id: Created/updated document's ID
+ :>header X-Couch-Update-NewRev: Created/updated document's revision
+ :code 200: No document was created or updated
+ :code 201: Document was created or updated
+ :code 500: Query server error
+
+ **Function**:
+
+ .. code-block:: javascript
+
+ function(doc, req) {
+ if (!doc){
+ return [null, {'code': 400,
+ 'json': {'error': 'missed',
+ 'reason': 'no document to update'}}]
+ } else {
+ doc.ingredients.push(req.body);
+ return [doc, {'json': {'status': 'ok'}}];
+ }
+ }
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 5
+ Content-Type: application/json
+ Host: localhost:5984
+
+ love
+
+ **Response**:
+
+ .. code-block:: http
-.. todo:: PUT /db/_design/design-doc/_update/updatename/doc
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 16
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 14:11:34 GMT
+ Server: CouchDB/1.4.0+build.c843cef (Erlang OTP/R16B)
+ X-Couch-Id: SpaghettiWithMeatballs
+ X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf
-* **Method**: ``PUT /db/_design/design-doc/_update/updatename/doc``
-* **Request**: TBC
-* **Response**: TBC
-* **Admin Privileges Required**: no
+ {
+ "status": "ok"
+ }
[39/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Update images to 1.4.0
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/c5e0cc59
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/c5e0cc59
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/c5e0cc59
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: c5e0cc5937c0a4e23b8ad841cc58e995f823f226
Parents: 7ef3ef6
Author: Alexander Shorin <kx...@apache.org>
Authored: Wed Sep 4 19:37:24 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/images/futon-editdoc.png | Bin 64369 -> 52733 bytes
share/doc/images/futon-editeddoc.png | Bin 69595 -> 56005 bytes
share/doc/images/futon-overview.png | Bin 63039 -> 50815 bytes
share/doc/images/futon-replform.png | Bin 68068 -> 52223 bytes
share/doc/images/intro-tour-01.png | Bin 56231 -> 50815 bytes
share/doc/images/intro-tour-02.png | Bin 125209 -> 83380 bytes
share/doc/images/intro-tour-03.png | Bin 62323 -> 53795 bytes
share/doc/images/intro-tour-04.png | Bin 72533 -> 56470 bytes
share/doc/images/intro-tour-05.png | Bin 73625 -> 53778 bytes
share/doc/images/intro-tour-06.png | Bin 78923 -> 61296 bytes
share/doc/images/intro-tour-07.png | Bin 121770 -> 47487 bytes
share/doc/images/intro-tour-08.png | Bin 130063 -> 83494 bytes
share/doc/images/intro-tour-09.png | Bin 131956 -> 84701 bytes
share/doc/images/intro-tour-10.png | Bin 88116 -> 61631 bytes
14 files changed, 0 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-editdoc.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-editdoc.png b/share/doc/images/futon-editdoc.png
index 6802c2c..f31dbbe 100644
Binary files a/share/doc/images/futon-editdoc.png and b/share/doc/images/futon-editdoc.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-editeddoc.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-editeddoc.png b/share/doc/images/futon-editeddoc.png
index 5c8b549..a5913bc 100644
Binary files a/share/doc/images/futon-editeddoc.png and b/share/doc/images/futon-editeddoc.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-overview.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-overview.png b/share/doc/images/futon-overview.png
index d1eac6e..e1daf5c 100644
Binary files a/share/doc/images/futon-overview.png and b/share/doc/images/futon-overview.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/futon-replform.png
----------------------------------------------------------------------
diff --git a/share/doc/images/futon-replform.png b/share/doc/images/futon-replform.png
index d904f0d..72b9ff5 100644
Binary files a/share/doc/images/futon-replform.png and b/share/doc/images/futon-replform.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-01.png b/share/doc/images/intro-tour-01.png
index 41b6420..e6fe9df 100644
Binary files a/share/doc/images/intro-tour-01.png and b/share/doc/images/intro-tour-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-02.png b/share/doc/images/intro-tour-02.png
index f263664..2c6f0cc 100644
Binary files a/share/doc/images/intro-tour-02.png and b/share/doc/images/intro-tour-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-03.png b/share/doc/images/intro-tour-03.png
index 47f013b..7137583 100644
Binary files a/share/doc/images/intro-tour-03.png and b/share/doc/images/intro-tour-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-04.png b/share/doc/images/intro-tour-04.png
index 33ceccc..7bc5678 100644
Binary files a/share/doc/images/intro-tour-04.png and b/share/doc/images/intro-tour-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-05.png b/share/doc/images/intro-tour-05.png
index 08042d7..972cb65 100644
Binary files a/share/doc/images/intro-tour-05.png and b/share/doc/images/intro-tour-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-06.png b/share/doc/images/intro-tour-06.png
index bb9c7c8..9f27df1 100644
Binary files a/share/doc/images/intro-tour-06.png and b/share/doc/images/intro-tour-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
index dc009a8..e75987d 100644
Binary files a/share/doc/images/intro-tour-07.png and b/share/doc/images/intro-tour-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-08.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-08.png b/share/doc/images/intro-tour-08.png
index 6976f57..4aa549b 100644
Binary files a/share/doc/images/intro-tour-08.png and b/share/doc/images/intro-tour-08.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-09.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-09.png b/share/doc/images/intro-tour-09.png
index f41b306..b850ade 100644
Binary files a/share/doc/images/intro-tour-09.png and b/share/doc/images/intro-tour-09.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c5e0cc59/share/doc/images/intro-tour-10.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-10.png b/share/doc/images/intro-tour-10.png
index e95bc66..68038bf 100644
Binary files a/share/doc/images/intro-tour-10.png and b/share/doc/images/intro-tour-10.png differ
[40/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Add missed theme's files.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/9454b50a
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/9454b50a
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/9454b50a
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 9454b50af5671cc10f28e6885c6aadce7f606637
Parents: 18735b6
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Sep 12 04:59:25 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 2 ++
1 file changed, 2 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/9454b50a/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 1030dcd..729313a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -403,6 +403,8 @@ src_files = \
src_files_html = \
../static/rtd.css \
+ ../templates/couchdb/domainindex.html \
+ ../templates/couchdb/theme.conf \
../templates/pages/download.html \
../templates/pages/index.html \
../templates/layout.html \
[34/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Preserve valid JSON output.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/28e1b1fc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/28e1b1fc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/28e1b1fc
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 28e1b1fcf63264782bddfa9b8d8208ac0fcd6c83
Parents: 360381a
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Sep 7 21:29:33 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:48 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/ddoc/views.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/28e1b1fc/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 00aa077..bb45095 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -397,7 +397,7 @@ content. The basic order of output is as follows:
},
{
"id": "dummy-doc",
- "key": "привет",
+ "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
"value": null
},
{
@@ -516,7 +516,7 @@ You can reverse the order of the returned view information by using the
},
{
"id": "dummy-doc",
- "key": "привет",
+ "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
"value": null
},
{
[49/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Make builtin reduce functions definition referenceable.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/47ff8636
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/47ff8636
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/47ff8636
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 47ff8636fd57cfd85b2ebe9f2f902cc99db0c4c7
Parents: 6f007f8
Author: Alexander Shorin <kx...@apache.org>
Authored: Sun Sep 8 22:17:58 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/couchapp/ddocs.rst | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/47ff8636/share/doc/src/couchapp/ddocs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/ddocs.rst b/share/doc/src/couchapp/ddocs.rst
index 01d3d69..1920a42 100644
--- a/share/doc/src/couchapp/ddocs.rst
+++ b/share/doc/src/couchapp/ddocs.rst
@@ -112,8 +112,14 @@ that main task of reduce functions is to *reduce* mapped result, not to make it
even bigger. Generally, your reduce function should converge rapidly to a single
value - which could be an array or similar object.
-Also CouchDB has three built-in reduce functions. These are implemented in
-Erlang and run right inside CouchDB, so they are much faster than the equivalent
+
+.. _reducefun/builtin:
+
+Builtin reduce functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additionally, CouchDB has three built-in reduce functions. These are implemented
+in Erlang and runs inside CouchDB, so they are much faster than the equivalent
JavaScript functions: ``_sum``, ``_count`` and ``_stats``. Their equivalents in
JavaScript below:
[21/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Ignore Python's bytecode files.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/1eb6047f
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/1eb6047f
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/1eb6047f
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 1eb6047fd6ac8ab0deeff28cfc4012f0d867a081
Parents: ee769ae
Author: Alexander Shorin <kx...@apache.org>
Authored: Fri Aug 23 02:43:32 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:00:45 2013 +0400
----------------------------------------------------------------------
.gitignore | 2 ++
share/doc/ext/github.pyc | Bin 1379 -> 0 bytes
2 files changed, 2 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1eb6047f/.gitignore
----------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
index 58f992e..0a60efe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
*.lo
*.o
*.orig
+*.pyc
*.rej
*.stamp
*.sw*
@@ -21,6 +22,7 @@ acinclude.m4
aclocal.m4
apache-couchdb-*
autom4te.cache
+__pycache__
bin/.deps/
bin/couch-config
bin/couch-config_dev
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1eb6047f/share/doc/ext/github.pyc
----------------------------------------------------------------------
diff --git a/share/doc/ext/github.pyc b/share/doc/ext/github.pyc
deleted file mode 100644
index a6f95a3..0000000
Binary files a/share/doc/ext/github.pyc and /dev/null differ
[29/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Add missed Replication-Git comparison authorship.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/627806e2
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/627806e2
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/627806e2
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 627806e25628861481f760acddfd6eb2ded0b13e
Parents: a103e74
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Aug 26 20:27:53 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/src/replication/conflicts.rst | 6 ++++++
1 file changed, 6 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/627806e2/share/doc/src/replication/conflicts.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/conflicts.rst b/share/doc/src/replication/conflicts.rst
index d0149b0..354c286 100644
--- a/share/doc/src/replication/conflicts.rst
+++ b/share/doc/src/replication/conflicts.rst
@@ -702,9 +702,15 @@ to use "history rewriting" to make git forget commits earlier than a particular
one.
+.. _replication/conflicts/git:
+
What is the CouchDB replication protocol? Is it like Git?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:Author: Jason Smith
+:Date: 2011-01-29
+:Source: http://stackoverflow.com/questions/4766391/what-is-the-couchdb-replication-protocol-is-it-like-git
+
**Key points**
**If you know Git, then you know how Couch replication works.** Replicating is
[31/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Better introduction into CouchDB.
Import articles from Guide to CouchDB:
- Why CouchDB?
- Eventual Consistency
- Getting Started
+ Technical Overview from Wiki
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/7c4a8c4e
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/7c4a8c4e
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/7c4a8c4e
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 7c4a8c4e3975a1410f21f338caf12926f75f1639
Parents: 627806e
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Sep 2 00:53:46 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:47 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 50 ++-
share/doc/images/intro-consistency-01.png | Bin 0 -> 35605 bytes
share/doc/images/intro-consistency-02.png | Bin 0 -> 48145 bytes
share/doc/images/intro-consistency-03.png | Bin 0 -> 17333 bytes
share/doc/images/intro-consistency-04.png | Bin 0 -> 13744 bytes
share/doc/images/intro-consistency-05.png | Bin 0 -> 25592 bytes
share/doc/images/intro-consistency-06.png | Bin 0 -> 56651 bytes
share/doc/images/intro-consistency-07.png | Bin 0 -> 53634 bytes
share/doc/images/intro-tour-01.png | Bin 0 -> 56231 bytes
share/doc/images/intro-tour-02.png | Bin 0 -> 125209 bytes
share/doc/images/intro-tour-03.png | Bin 0 -> 62323 bytes
share/doc/images/intro-tour-04.png | Bin 0 -> 72533 bytes
share/doc/images/intro-tour-05.png | Bin 0 -> 73625 bytes
share/doc/images/intro-tour-06.png | Bin 0 -> 78923 bytes
share/doc/images/intro-tour-07.png | Bin 0 -> 121770 bytes
share/doc/images/intro-tour-08.png | Bin 0 -> 130063 bytes
share/doc/images/intro-tour-09.png | Bin 0 -> 131956 bytes
share/doc/images/intro-tour-10.png | Bin 0 -> 88116 bytes
share/doc/images/intro-why-01.png | Bin 0 -> 25755 bytes
share/doc/images/intro-why-02.png | Bin 0 -> 5937 bytes
share/doc/images/intro-why-03.png | Bin 0 -> 5134 bytes
share/doc/src/couchapp/index.rst | 2 +
share/doc/src/index.rst | 15 +-
share/doc/src/intro.rst | 315 ---------------
share/doc/src/intro/consistency.rst | 465 +++++++++++++++++++++
share/doc/src/intro/curl.rst | 122 ++++++
share/doc/src/intro/futon.rst | 186 +++++++++
share/doc/src/intro/index.rst | 50 +++
share/doc/src/intro/overview.rst | 387 ++++++++++++++++++
share/doc/src/intro/tour.rst | 534 +++++++++++++++++++++++++
share/doc/src/intro/why.rst | 315 +++++++++++++++
31 files changed, 2110 insertions(+), 331 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 188714c..dcc1150 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -109,6 +109,13 @@ html_files = \
html/_sources/install/mac.txt \
html/_sources/install/unix.txt \
html/_sources/install/windows.txt \
+ html/_sources/intro/consistency.txt \
+ html/_sources/intro/curl.txt \
+ html/_sources/intro/futon.txt \
+ html/_sources/intro/index.txt \
+ html/_sources/intro/overview.txt \
+ html/_sources/intro/tour.txt \
+ html/_sources/intro/why.txt \
html/_sources/query-server/index.txt \
html/_sources/query-server/erlang.txt \
html/_sources/query-server/javascript.txt \
@@ -131,7 +138,6 @@ html_files = \
html/_sources/contributing.txt \
html/_sources/externals.txt \
html/_sources/index.txt \
- html/_sources/intro.txt \
html/_sources/json-structure.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
@@ -216,6 +222,13 @@ html_files = \
html/install/mac.html \
html/install/unix.html \
html/install/windows.html \
+ html/intro/consistency.html \
+ html/intro/curl.html \
+ html/intro/futon.html \
+ html/intro/index.html \
+ html/intro/overview.html \
+ html/intro/tour.html \
+ html/intro/why.html \
html/query-server/index.html \
html/query-server/erlang.html \
html/query-server/javascript.html \
@@ -237,7 +250,6 @@ html_files = \
html/whatsnew/index.html \
html/externals.html \
html/index.html \
- html/intro.html \
html/json-structure.html \
html/objects.inv \
html/genindex.html \
@@ -258,7 +270,31 @@ image_files = \
../images/futon-editeddoc.png \
../images/futon-overview.png \
../images/futon-replform.png \
- ../images/logo.png
+ ../images/intro-consistency-01.png \
+ ../images/intro-consistency-02.png \
+ ../images/intro-consistency-03.png \
+ ../images/intro-consistency-04.png \
+ ../images/intro-consistency-05.png \
+ ../images/intro-consistency-06.png \
+ ../images/intro-consistency-07.png \
+ ../images/intro-tour-01.png \
+ ../images/intro-tour-02.png \
+ ../images/intro-tour-03.png \
+ ../images/intro-tour-04.png \
+ ../images/intro-tour-05.png \
+ ../images/intro-tour-06.png \
+ ../images/intro-tour-07.png \
+ ../images/intro-tour-08.png \
+ ../images/intro-tour-09.png \
+ ../images/intro-tour-10.png \
+ ../images/intro-why-01.png \
+ ../images/intro-why-02.png \
+ ../images/intro-why-03.png \
+ ../images/logo.png \
+ ../images/views-intro-01.png \
+ ../images/views-intro-02.png \
+ ../images/views-intro-03.png \
+ ../images/views-intro-04.png
src_files = \
../src/api/basics.rst \
@@ -321,6 +357,13 @@ src_files = \
../src/install/mac.rst \
../src/install/unix.rst \
../src/install/windows.rst \
+ ../src/intro/consistency.rst \
+ ../src/intro/curl.rst \
+ ../src/intro/futon.rst \
+ ../src/intro/index.rst \
+ ../src/intro/overview.rst \
+ ../src/intro/tour.rst \
+ ../src/intro/why.rst \
../src/query-server/index.rst \
../src/query-server/erlang.rst \
../src/query-server/javascript.rst \
@@ -343,7 +386,6 @@ src_files = \
../src/contributing.rst \
../src/externals.rst \
../src/index.rst \
- ../src/intro.rst \
../src/json-structure.rst \
../src/conf.py
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-01.png b/share/doc/images/intro-consistency-01.png
new file mode 100644
index 0000000..9ae6912
Binary files /dev/null and b/share/doc/images/intro-consistency-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-02.png b/share/doc/images/intro-consistency-02.png
new file mode 100644
index 0000000..06c23ea
Binary files /dev/null and b/share/doc/images/intro-consistency-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-03.png b/share/doc/images/intro-consistency-03.png
new file mode 100644
index 0000000..2164c6c
Binary files /dev/null and b/share/doc/images/intro-consistency-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-04.png b/share/doc/images/intro-consistency-04.png
new file mode 100644
index 0000000..068fa77
Binary files /dev/null and b/share/doc/images/intro-consistency-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-05.png b/share/doc/images/intro-consistency-05.png
new file mode 100644
index 0000000..a94f9c3
Binary files /dev/null and b/share/doc/images/intro-consistency-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-06.png b/share/doc/images/intro-consistency-06.png
new file mode 100644
index 0000000..af316d4
Binary files /dev/null and b/share/doc/images/intro-consistency-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-consistency-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-consistency-07.png b/share/doc/images/intro-consistency-07.png
new file mode 100644
index 0000000..7fb5027
Binary files /dev/null and b/share/doc/images/intro-consistency-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-01.png b/share/doc/images/intro-tour-01.png
new file mode 100644
index 0000000..41b6420
Binary files /dev/null and b/share/doc/images/intro-tour-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-02.png b/share/doc/images/intro-tour-02.png
new file mode 100644
index 0000000..f263664
Binary files /dev/null and b/share/doc/images/intro-tour-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-03.png b/share/doc/images/intro-tour-03.png
new file mode 100644
index 0000000..47f013b
Binary files /dev/null and b/share/doc/images/intro-tour-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-04.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-04.png b/share/doc/images/intro-tour-04.png
new file mode 100644
index 0000000..33ceccc
Binary files /dev/null and b/share/doc/images/intro-tour-04.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-05.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-05.png b/share/doc/images/intro-tour-05.png
new file mode 100644
index 0000000..08042d7
Binary files /dev/null and b/share/doc/images/intro-tour-05.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-06.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-06.png b/share/doc/images/intro-tour-06.png
new file mode 100644
index 0000000..bb9c7c8
Binary files /dev/null and b/share/doc/images/intro-tour-06.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-07.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-07.png b/share/doc/images/intro-tour-07.png
new file mode 100644
index 0000000..dc009a8
Binary files /dev/null and b/share/doc/images/intro-tour-07.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-08.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-08.png b/share/doc/images/intro-tour-08.png
new file mode 100644
index 0000000..6976f57
Binary files /dev/null and b/share/doc/images/intro-tour-08.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-09.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-09.png b/share/doc/images/intro-tour-09.png
new file mode 100644
index 0000000..f41b306
Binary files /dev/null and b/share/doc/images/intro-tour-09.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-tour-10.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-tour-10.png b/share/doc/images/intro-tour-10.png
new file mode 100644
index 0000000..e95bc66
Binary files /dev/null and b/share/doc/images/intro-tour-10.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-01.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-01.png b/share/doc/images/intro-why-01.png
new file mode 100644
index 0000000..c927450
Binary files /dev/null and b/share/doc/images/intro-why-01.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-02.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-02.png b/share/doc/images/intro-why-02.png
new file mode 100644
index 0000000..a5bb4ce
Binary files /dev/null and b/share/doc/images/intro-why-02.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/images/intro-why-03.png
----------------------------------------------------------------------
diff --git a/share/doc/images/intro-why-03.png b/share/doc/images/intro-why-03.png
new file mode 100644
index 0000000..1f5e536
Binary files /dev/null and b/share/doc/images/intro-why-03.png differ
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/couchapp/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/couchapp/index.rst b/share/doc/src/couchapp/index.rst
index d01b91e..0985d49 100644
--- a/share/doc/src/couchapp/index.rst
+++ b/share/doc/src/couchapp/index.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. _couchapp:
+
========
CouchApp
========
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index 047088e..c41cc9f 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -10,24 +10,15 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-Introduction
-============
-|Apache CouchDB(TM)|_ is a document database built for the web.
+|Apache CouchDB(TM)|_ |release| Documentation
+=============================================
-If you would like to help document the project, please send a note to the
-`developer mailing list <http://couchdb.apache.org/#mailing-list>`_.
-
-This is a work in progress.
-
-Contents
-========
-
.. toctree::
:maxdepth: 3
:numbered:
- intro
+ intro/index
install/index
config/index
replication/index
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
deleted file mode 100644
index 57eb235..0000000
--- a/share/doc/src/intro.rst
+++ /dev/null
@@ -1,315 +0,0 @@
-.. 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.
-
-============
-Introduction
-============
-
-There are two interfaces to CouchDB, the built-in Futon web-based
-interface and the CouchDB API accessed through the HTTP REST interface.
-The former is the simplest way to view and monitor your CouchDB
-installation and perform a number of basic database and system
-operations. More information on using the Futon interface can be found
-in :ref:`using-futon`.
-
-The primary way to interact with the CouchDB API is to use a client
-library or other interface that provides access to the underlying
-functionality through your chosen language or platform. However, since
-the API is supported through HTTP REST, you can interact with your
-CouchDB with any solution that supports the HTTP protocol.
-
-There are a number of different tools that talk the HTTP protocol and
-allow you to set and configure the necessary information. One tool for
-this that allows for access from the command-line is ``curl``. See
-:ref:`using-curl`.
-
-.. _using-futon:
-
-Using Futon
-===========
-
-Futon is a native web-based interface built into CouchDB. It provides a
-basic interface to the majority of the functionality, including the
-ability to create, update, delete and view documents and views, provides
-access to the configuration parameters, and an interface for initiating
-replication.
-
-The default view is the Overview page which provides you with a list of
-the databases. The basic structure of the page is consistent regardless
-of the section you are in. The main panel on the left provides the main
-interface to the databases, configuration or replication systems. The
-side panel on the right provides navigation to the main areas of Futon
-interface:
-
-.. figure:: ../images/futon-overview.png
- :align: center
- :alt: Futon Overview
-
- Futon Overview
-
-The main sections are:
-
-- Overview
-
- The main overview page, which provides a list of the databases and
- provides the interface for querying the database and creating and
- updating documents. See :ref:`futon-management`.
-
-- Configuration
-
- An interface into the configuration of your CouchDB installation. The
- interface allows you to edit the different configurable parameters.
- For more details on configuration, see :ref:`config` section.
-
-- Replicator
-
- An interface to the replication system, enabling you to initiate
- replication between local and remote databases. See
- :ref:`futon-replication`.
-
-- Status
-
- Displays a list of the running background tasks on the server.
- Background tasks include view index building, compaction and
- replication. The Status page is an interface to the
- :ref:`Active Tasks <api/server/active_tasks>` API call.
-
-- Verify Installation
-
- The Verify Installation allows you to check whether all of the
- components of your CouchDB installation are correctly installed.
-
-- Test Suite
-
- The Test Suite section allows you to run the built-in test suite.
- This executes a number of test routines entirely within your browser
- to test the API and functionality of your CouchDB installation. If
- you select this page, you can run the tests by using the Run All
- button. This will execute all the tests, which may take some time.
-
-.. _futon-management:
-
-Managing Databases and Documents
---------------------------------
-
-You can manage databases and documents within Futon using the main
-Overview section of the Futon interface.
-
-To create a new database, click the Create Database ELLIPSIS button. You
-will be prompted for the database name, as shown in the figure below.
-
-.. figure:: ../images/futon-createdb.png
- :align: center
- :alt: Creating a Database
-
- Creating a Database
-
-Once you have created the database (or selected an existing one), you
-will be shown a list of the current documents. If you create a new
-document, or select an existing document, you will be presented with the
-edit document display.
-
-Editing documents within Futon requires selecting the document and then
-editing (and setting) the fields for the document individually before
-saving the document back into the database.
-
-For example, the figure below shows the editor for a single document, a
-newly created document with a single ID, the document ``_id`` field.
-
-.. figure:: ../images/futon-editdoc.png
- :align: center
- :alt: Editing a Document
-
- Editing a Document
-
-To add a field to the document:
-
-1. Click Add Field.
-
-2. In the fieldname box, enter the name of the field you want to create.
- For example, “company”.
-
-3. Click the green tick next to the field name to confirm the field name
- change.
-
-4. Double-click the corresponding Value cell.
-
-5. Enter a company name, for example “Example”.
-
-6. Click the green tick next to the field value to confirm the field
- value.
-
-7. The document is still not saved as this point. You must explicitly
- save the document by clicking the Save Document button at the top of
- the page. This will save the document, and then display the new
- document with the saved revision information (the ``_rev`` field).
-
- .. figure:: ../images/futon-editeddoc.png
- :align: center
- :alt: Edited Document
-
- Edited Document
-
-The same basic interface is used for all editing operations within Futon.
-You *must* remember to save the individual element (fieldname, value)
-using the green tick button, before then saving the document.
-
-.. _futon-replication:
-
-Configuring Replication
------------------------
-
-When you click the Replicator option within the Tools menu you are
-presented with the Replicator screen. This allows you to start
-replication between two databases by filling in or select the
-appropriate options within the form provided.
-
-.. figure:: ../images/futon-replform.png
- :align: center
- :alt: Replication Form
-
- Replication Form
-
-To start a replication process, either the select the local database or
-enter a remote database name into the corresponding areas of the form.
-Replication occurs from the database on the left to the database on the
-right.
-
-If you are specifying a remote database name, you must specify the full
-URL of the remote database (including the host, port number and database
-name). If the remote instance requires authentication, you can specify
-the username and password as part of the URL, for example
-``http://username:pass@remotehost:5984/demo``.
-
-To enable continuous replication, click the Continuous checkbox.
-
-To start the replication process, click the Replicate button. The
-replication process should start and will continue in the background. If
-the replication process will take a long time, you can monitor the
-status of the replication using the Status option under the Tools menu.
-
-Once replication has been completed, the page will show the information
-returned when the replication process completes by the API.
-
-The Replicator tool is an interface to the underlying replication API.
-For more information, see :ref:`api/server/replicate`. For more information on
-replication, see :ref:`replication`.
-
-.. _using-curl:
-
-Using ``curl``
-==============
-
-The ``curl`` utility is a command line tool available on Unix, Linux,
-Mac OS X and Windows and many other platforms. ``curl`` provides easy
-access to the HTTP protocol (among others) directly from the
-command-line and is therefore an ideal way of interacting with CouchDB
-over the HTTP REST API.
-
-For simple ``GET`` requests you can supply the URL of the request. For
-example, to get the database information:
-
-.. code-block:: bash
-
- shell> curl http://127.0.0.1:5984
-
-This returns the database information (formatted in the output below for
-clarity):
-
-.. code-block:: json
-
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.4.0"
- },
- "version": "1.4.0"
- }
-
-
-.. note:: For some URLs, especially those that include special characters such
- as ampersand, exclamation mark, or question mark, you should quote
- the URL you are specifying on the command line. For example:
-
- .. code-block:: bash
-
- shell> curl 'http://couchdb:5984/_uuids?count=5'
-
-You can explicitly set the HTTP command using the ``-X`` command line
-option. For example, when creating a database, you set the name of the
-database in the URL you send using a PUT request:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/demo
- {"ok":true}
-
-But to obtain the database information you use a ``GET`` request (with
-the return information formatted for clarity):
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo
- {
- "compact_running" : false,
- "doc_count" : 0,
- "db_name" : "demo",
- "purge_seq" : 0,
- "committed_update_seq" : 0,
- "doc_del_count" : 0,
- "disk_format_version" : 5,
- "update_seq" : 0,
- "instance_start_time" : "1306421773496000",
- "disk_size" : 79
- }
-
-For certain operations, you must specify the content type of request,
-which you do by specifying the ``Content-Type`` header using the ``-H``
-command-line option:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
-
-You can also submit 'payload' data, that is, data in the body of the
-HTTP request using the ``-d`` option. This is useful if you need to
-submit JSON structures, for example document data, as part of the
-request. For example, to submit a simple document to the ``demo``
-database:
-
-.. code-block:: bash
-
- shell> curl -H 'Content-Type: application/json' \
- -X POST http://127.0.0.1:5984/demo \
- -d '{"company": "Example, Inc."}'
- {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
- "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
-
-In the above example, the argument after the ``-d`` option is the JSON
-of the document we want to submit.
-
-The document can be accessed by using the automatically generated
-document ID that was returned:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
- {"_id":"8843faaf0b831d364278331bc3001bd8",
- "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
- "company":"Example, Inc."}
-
-The API samples in the :ref:`api/basics` show the HTTP command, URL and any
-payload information that needs to be submitted (and the expected return
-value). All of these examples can be reproduced using ``curl`` with the
-command-line examples shown above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/consistency.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/consistency.rst b/share/doc/src/intro/consistency.rst
new file mode 100644
index 0000000..d10040b
--- /dev/null
+++ b/share/doc/src/intro/consistency.rst
@@ -0,0 +1,465 @@
+.. 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.
+
+
+.. _intro/consistency:
+
+====================
+Eventual Consistency
+====================
+
+In the previous chapter, we saw that CouchDB's flexibility allows us to
+evolve our data as our applications grow and change. In this chapter,
+we'll explore how working "with the grain" of CouchDB promotes simplicity in
+our applications and helps us naturally build scalable, distributed systems.
+
+
+Working with the Grain
+======================
+
+A *distributed system* is a system that operates robustly over a wide network.
+A particular feature of network computing is that network links can
+potentially disappear, and there are plenty of strategies for managing this
+type of network segmentation. CouchDB differs from others by accepting
+eventual consistency, as opposed to putting absolute consistency ahead of raw
+availability, like `RDBMS`_ or `Paxos`_. What these systems have in common is
+an awareness that data acts differently when many people are accessing it
+simultaneously. Their approaches differ when it comes to which aspects of
+*consistency*, *availability*, or *partition* tolerance they prioritize.
+
+Engineering distributed systems is tricky. Many of the caveats and "gotchas"
+you will face over time aren't immediately obvious. We don't have all the
+solutions, and CouchDB isn't a panacea, but when you work with CouchDB's
+grain rather than against it, the path of least resistance leads you to
+naturally scalable applications.
+
+Of course, building a distributed system is only the beginning. A website
+with a database that is available only half the time is next to worthless.
+Unfortunately, the traditional relational database approach to consistency
+makes it very easy for application programmers to rely on global state,
+global clocks, and other high availability no-nos, without even realizing
+that they're doing so. Before examining how CouchDB promotes scalability,
+we'll look at the constraints faced by a distributed system. After we've seen
+the problems that arise when parts of your application can't rely on being
+in constant contact with each other, we'll see that CouchDB provides an
+intuitive and useful way for modeling applications around high availability.
+
+.. _RDBMS: http://en.wikipedia.org/wiki/Relational_database_management_system
+.. _Paxos: http://en.wikipedia.org/wiki/Paxos_%28computer_science%29
+
+
+.. _cap:
+
+The CAP Theorem
+===============
+
+The CAP theorem describes a few different strategies for distributing
+application logic across networks. CouchDB's solution uses replication to
+propagate application changes across participating nodes. This is a
+fundamentally different approach from consensus algorithms and relational
+databases, which operate at different intersections of consistency,
+availability, and partition tolerance.
+
+The CAP theorem, shown in :ref:`intro/consistency-01`,
+identifies three distinct concerns:
+
+- **Consistency**:
+ All database clients see the same data, even with concurrent updates.
+- **Availability**:
+ All database clients are able to access some version of the data.
+- **Partition tolerance**:
+ The database can be split over multiple servers.
+
+Pick two.
+
+.. _intro/consistency-01:
+
+.. figure:: ../../images/intro-consistency-01.png
+ :align: center
+ :alt: The CAP theorem
+
+ Figure 1. The CAP theorem
+
+When a system grows large enough that a single database node is unable to
+handle the load placed on it, a sensible solution is to add more servers.
+When we add nodes, we have to start thinking about how to partition data
+between them. Do we have a few databases that share exactly the same data?
+Do we put different sets of data on different database servers?
+Do we let only certain database servers write data and let others handle
+the reads?
+
+Regardless of which approach we take, the one problem we'll keep bumping into
+is that of keeping all these database servers in sync. If you write some
+information to one node, how are you going to make sure that a read request
+to another database server reflects this newest information? These events
+might be milliseconds apart. Even with a modest collection of database
+servers, this problem can become extremely complex.
+
+When it's absolutely critical that all clients see a consistent view of the
+database, the users of one node will have to wait for any other nodes to come
+into agreement before being able to read or write to the database.
+In this instance, we see that availability takes a backseat to consistency.
+However, there are situations where availability trumps consistency:
+
+ Each node in a system should be able to make decisions purely based on
+ local state. If you need to do something under high load with failures
+ occurring and you need to reach agreement, you're lost. If you're
+ concerned about scalability, any algorithm that forces you to run
+ agreement will eventually become your bottleneck. Take that as a given.
+
+ -- Werner Vogels, Amazon CTO and Vice President
+
+If availability is a priority, we can let clients write data to one node of
+the database without waiting for other nodes to come into agreement.
+If the database knows how to take care of reconciling these operations between
+nodes, we achieve a sort of "eventual consistency" in exchange for high
+availability. This is a surprisingly applicable trade-off for many applications.
+
+Unlike traditional relational databases, where each action performed is
+necessarily subject to database-wide consistency checks,
+CouchDB makes it really simple to build applications that sacrifice immediate
+consistency for the huge performance improvements that come with simple
+distribution.
+
+
+Local Consistency
+=================
+
+Before we attempt to understand how CouchDB operates in a cluster,
+it's important that we understand the inner workings of a single CouchDB node.
+The CouchDB API is designed to provide a convenient but thin wrapper around
+the database core. By taking a closer look at the structure of the database
+core, we'll have a better understanding of the API that surrounds it.
+
+
+The Key to Your Data
+--------------------
+
+At the heart of CouchDB is a powerful *B-tree* storage engine.
+A B-tree is a sorted data structure that allows for searches, insertions,
+and deletions in logarithmic time. As :ref:`intro/consistency-02`
+illustrates, CouchDB uses this B-tree storage engine for all internal data,
+documents, and views. If we understand one, we will understand them all.
+
+
+.. _intro/consistency-02:
+
+.. figure:: ../../images/intro-consistency-02.png
+ :align: center
+ :alt: Anatomy of a view request
+
+ Figure 2. Anatomy of a view request
+
+
+CouchDB uses MapReduce to compute the results of a view. MapReduce makes use
+of two functions, "map" and "reduce", which are applied to each document in
+isolation. Being able to isolate these operations means that view computation
+lends itself to parallel and incremental computation. More important,
+because these functions produce key/value pairs, CouchDB is able to insert
+them into the B-tree storage engine, sorted by key. Lookups by key,
+or key range, are extremely efficient operations with a B-tree,
+described in `big O` notation as ``O(log N)`` and ``O(log N + K)``,
+respectively.
+
+In CouchDB, we access documents and view results by key or key range.
+This is a direct mapping to the underlying operations performed on CouchDB's
+B-tree storage engine. Along with document inserts and updates,
+this direct mapping is the reason we describe CouchDB's API as being a thin
+wrapper around the database core.
+
+Being able to access results by key alone is a very important restriction
+because it allows us to make huge performance gains. As well as the massive
+speed improvements, we can partition our data over multiple nodes,
+without affecting our ability to query each node in isolation.
+`BigTable`_, `Hadoop`_, `SimpleDB`_, and `memcached`_ restrict object lookups
+by key for exactly these reasons.
+
+.. _BigTable: http://en.wikipedia.org/wiki/BigTable
+.. _Hadoop: http://hadoop.apache.org
+.. _SimpleDB: http://aws.amazon.com/simpledb/
+.. _memcached: http://memcached.org
+
+
+No Locking
+----------
+
+A table in a relational database is a single data structure. If you want to
+modify a table -- say, update a row -- the database system must ensure
+that nobody else is trying to update that row and that nobody can read from
+that row while it is being updated. The common way to handle this uses what's
+known as a lock. If multiple clients want to access a table, the first client
+gets the lock, making everybody else wait. When the first client's request is
+processed, the next client is given access while everybody else waits,
+and so on. This serial execution of requests, even when they arrived in
+parallel, wastes a significant amount of your server's processing power.
+Under high load, a relational database can spend more time figuring out who
+is allowed to do what, and in which order, than it does doing any actual work.
+
+.. note::
+ Modern relational databases avoid locks by implementing MVCC under
+ the hood, but hide it from the end user, requiring them to coordinate
+ concurrent changes of single rows or fields.
+
+Instead of locks, CouchDB uses `Multi-Version Concurrency Control` (MVCC) to
+manage concurrent access to the database. :ref:`intro/consistency-03`
+illustrates the differences between MVCC and traditional locking mechanisms.
+MVCC means that CouchDB can run at full speed, all the time,
+even under high load. Requests are run in parallel, making excellent use of
+every last drop of processing power your server has to offer.
+
+
+.. _intro/consistency-03:
+
+.. figure:: ../../images/intro-consistency-03.png
+ :align: center
+ :alt: MVCC means no locking
+
+ Figure 3. MVCC means no locking
+
+
+Documents in CouchDB are versioned, much like they would be in a regular
+version control system such as `Subversion`_. If you want to change
+a value in a document, you create an entire new version of that document
+and save it over the old one. After doing this, you end up with two versions
+of the same document, one old and one new.
+
+How does this offer an improvement over locks? Consider a set of requests
+wanting to access a document. The first request reads the document.
+While this is being processed, a second request changes the document.
+Since the second request includes a completely new version of the document,
+CouchDB can simply append it to the database without having to wait for the
+read request to finish.
+
+When a third request wants to read the same document, CouchDB will point it
+to the new version that has just been written. During this whole process,
+the first request could still be reading the original version.
+
+A read request will always see the most recent snapshot of your database at
+the time of the beginning of the request.
+
+.. _Subversion: http://subversion.apache.org/
+
+
+Validation
+==========
+
+As application developers, we have to think about what sort of input we
+should accept and what we should reject. The expressive power to do this type
+of validation over complex data within a traditional relational database
+leaves a lot to be desired. Fortunately, CouchDB provides a powerful way to
+perform per-document validation from within the database.
+
+CouchDB can validate documents using JavaScript functions similar to those
+used for MapReduce. Each time you try to modify a document,
+CouchDB will pass the validation function a copy of the existing document,
+a copy of the new document, and a collection of additional information,
+such as user authentication details. The validation function now has the
+opportunity to approve or deny the update.
+
+By working with the grain and letting CouchDB do this for us,
+we save ourselves a tremendous amount of CPU cycles that would otherwise have
+been spent serializing object graphs from SQL, converting them into domain
+objects, and using those objects to do application-level validation.
+
+
+Distributed Consistency
+=======================
+
+Maintaining consistency within a single database node is relatively easy for
+most databases. The real problems start to surface when you try to maintain
+consistency between multiple database servers. If a client makes a write
+operation on server `A`, how do we make sure that this is consistent with
+server `B`, or `C`, or `D`? For relational databases, this is a very complex
+problem with entire books devoted to its solution. You could use
+multi-master, master/slave, partitioning, sharding, write-through caches,
+and all sorts of other complex techniques.
+
+
+Incremental Replication
+=======================
+
+CouchDB's operations take place within the context of a single document.
+As CouchDB achieves eventual consistency between multiple databases by using
+incremental replication you no longer have to worry about your database
+servers being able to stay in constant communication. Incremental replication
+is a process where document changes are periodically copied between servers.
+We are able to build what's known as a *shared nothing* cluster of databases
+where each node is independent and self-sufficient, leaving no single point
+of contention across the system.
+
+Need to scale out your CouchDB database cluster? Just throw in another server.
+
+As illustrated in :ref:`intro/consistency-04`, with CouchDB's incremental
+replication, you can synchronize your data between any two databases however
+you like and whenever you like. After replication, each database is able
+to work independently.
+
+You could use this feature to synchronize database servers within a cluster
+or between data centers using a job scheduler such as cron,
+or you could use it to synchronize data with your laptop for offline work as
+you travel. Each database can be used in the usual fashion,
+and changes between databases can be synchronized later in both directions.
+
+
+.. _intro/consistency-04:
+
+.. figure:: ../../images/intro-consistency-04.png
+ :align: center
+ :alt: Incremental replication between CouchDB nodes
+
+ Figure 4. Incremental replication between CouchDB nodes
+
+
+What happens when you change the same document in two different databases and
+want to synchronize these with each other? CouchDB's replication system
+comes with automatic conflict detection and resolution. When CouchDB detects
+that a document has been changed in both databases, it flags this document
+as being in conflict, much like they would be in a regular version control
+system.
+
+This isn't as troublesome as it might first sound. When two versions of a
+document conflict during replication, the winning version is saved as the
+most recent version in the document's history. Instead of throwing the losing
+version away, as you might expect, CouchDB saves this as a previous version
+in the document's history, so that you can access it if you need to. This
+happens automatically and consistently, so both databases will make exactly
+the same choice.
+
+It is up to you to handle conflicts in a way that makes sense for your
+application. You can leave the chosen document versions in place,
+revert to the older version, or try to merge the two versions and save the
+result.
+
+
+Case Study
+==========
+
+Greg Borenstein, a friend and coworker, built a small library for converting
+Songbird playlists to JSON objects and decided to store these in CouchDB as
+part of a backup application. The completed software uses CouchDB's MVCC and
+document revisions to ensure that Songbird playlists are backed up robustly
+between nodes.
+
+.. note::
+ `Songbird`_ is a free software media player with an integrated web browser,
+ based on the Mozilla XULRunner platform. Songbird is available for Microsoft
+ Windows, Apple Mac OS X, Solaris, and Linux.
+
+ .. _Songbird: http://en.wikipedia.org/wiki/Songbird_%28software%29
+
+Let's examine the workflow of the Songbird backup application,
+first as a user backing up from a single computer, and then using Songbird to
+synchronize playlists between multiple computers. We'll see how document
+revisions turn what could have been a hairy problem into something that *just
+works*.
+
+The first time we use this backup application, we feed our playlists to the
+application and initiate a backup. Each playlist is converted to a JSON
+object and handed to a CouchDB database. As illustrated in
+:ref:`intro/consistency-05`, CouchDB hands back the document ID and
+revision of each playlist as it's saved to the database.
+
+
+.. _intro/consistency-05:
+
+.. figure:: ../../images/intro-consistency-05.png
+ :align: center
+ :alt: Backing up to a single database
+
+ Figure 5. Backing up to a single database
+
+
+After a few days, we find that our playlists have been updated and we want to
+back up our changes. After we have fed our playlists to the backup
+application, it fetches the latest versions from CouchDB,
+along with the corresponding document revisions. When the application hands
+back the new playlist document, CouchDB requires that the document revision
+is included in the request.
+
+CouchDB then makes sure that the document revision handed to it in the
+request matches the current revision held in the database. Because CouchDB
+updates the revision with every modification, if these two are out of sync it
+suggests that someone else has made changes to the document between the time
+we requested it from the database and the time we sent our updates. Making
+changes to a document after someone else has modified it without first
+inspecting those changes is usually a bad idea.
+
+Forcing clients to hand back the correct document revision is the heart of
+CouchDB's optimistic concurrency.
+
+We have a laptop we want to keep synchronized with our desktop computer.
+With all our playlists on our desktop, the first step is to
+"restore from backup" onto our laptop. This is the first time we've done this,
+so afterward our laptop should hold an exact replica of our desktop playlist
+collection.
+
+After editing our Argentine Tango playlist on our laptop to add a few new
+songs we've purchased, we want to save our changes. The backup application
+replaces the playlist document in our laptop CouchDB database and a new
+document revision is generated. A few days later, we remember our new songs
+and want to copy the playlist across to our desktop computer. As illustrated
+in :ref:`intro/consistency-06`, the backup application copies the new document
+and the new revision to the desktop CouchDB database. Both CouchDB databases
+now have the same document revision.
+
+
+.. _intro/consistency-06:
+
+.. figure:: ../../images/intro-consistency-06.png
+ :align: center
+ :alt: Synchronizing between two databases
+
+ Figure 6. Synchronizing between two databases
+
+
+Because CouchDB tracks document revisions, it ensures that updates like these
+will work only if they are based on current information. If we had made
+modifications to the playlist backups between synchronization,
+things wouldn't go as smoothly.
+
+We back up some changes on our laptop and forget to synchronize. A few days
+later, we're editing playlists on our desktop computer, make a backup,
+and want to synchronize this to our laptop. As illustrated in
+:ref:`intro/consistency-07`, when our backup application tries to replicate
+between the two databases, CouchDB sees that the changes being sent from our
+desktop computer are modifications of out-of-date documents and helpfully
+informs us that there has been a conflict.
+
+Recovering from this error is easy to accomplish from an application
+perspective. Just download CouchDB's version of the playlist and provide an
+opportunity to merge the changes or save local modifications into a new
+playlist.
+
+
+.. _intro/consistency-07:
+
+.. figure:: ../../images/intro-consistency-07.png
+ :align: center
+ :alt: Synchronization conflicts between two databases
+
+ Figure 7. Synchronization conflicts between two databases
+
+
+Wrapping Up
+===========
+
+CouchDB's design borrows heavily from web architecture and the lessons
+learned deploying massively distributed systems on that architecture.
+By understanding why this architecture works the way it does,
+and by learning to spot which parts of your application can be easily
+distributed and which parts cannot, you'll enhance your ability to design
+distributed and scalable applications, with CouchDB or without it.
+
+We've covered the main issues surrounding CouchDB's consistency model and
+hinted at some of the benefits to be had when you work *with* CouchDB and not
+against it. But enough theory -- let's get up and running and see what all the
+fuss is about!
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/curl.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/curl.rst b/share/doc/src/intro/curl.rst
new file mode 100644
index 0000000..06b62b5
--- /dev/null
+++ b/share/doc/src/intro/curl.rst
@@ -0,0 +1,122 @@
+.. 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.
+
+.. _intro/curl:
+
+==============================
+cURL: Your Command Line Friend
+==============================
+
+The ``curl`` utility is a command line tool available on Unix, Linux,
+Mac OS X and Windows and many other platforms. ``curl`` provides easy
+access to the HTTP protocol (among others) directly from the
+command-line and is therefore an ideal way of interacting with CouchDB
+over the HTTP REST API.
+
+For simple ``GET`` requests you can supply the URL of the request. For
+example, to get the database information:
+
+.. code-block:: bash
+
+ shell> curl http://127.0.0.1:5984
+
+This returns the database information (formatted in the output below for
+clarity):
+
+.. code-block:: json
+
+ {
+ "couchdb": "Welcome",
+ "uuid": "85fb71bf700c17267fef77535820e371",
+ "vendor": {
+ "name": "The Apache Software Foundation",
+ "version": "1.4.0"
+ },
+ "version": "1.4.0"
+ }
+
+
+.. note:: For some URLs, especially those that include special characters such
+ as ampersand, exclamation mark, or question mark, you should quote
+ the URL you are specifying on the command line. For example:
+
+ .. code-block:: bash
+
+ shell> curl 'http://couchdb:5984/_uuids?count=5'
+
+You can explicitly set the HTTP command using the ``-X`` command line
+option. For example, when creating a database, you set the name of the
+database in the URL you send using a PUT request:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/demo
+ {"ok":true}
+
+But to obtain the database information you use a ``GET`` request (with
+the return information formatted for clarity):
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo
+ {
+ "compact_running" : false,
+ "doc_count" : 0,
+ "db_name" : "demo",
+ "purge_seq" : 0,
+ "committed_update_seq" : 0,
+ "doc_del_count" : 0,
+ "disk_format_version" : 5,
+ "update_seq" : 0,
+ "instance_start_time" : "1306421773496000",
+ "disk_size" : 79
+ }
+
+For certain operations, you must specify the content type of request,
+which you do by specifying the ``Content-Type`` header using the ``-H``
+command-line option:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
+
+You can also submit 'payload' data, that is, data in the body of the
+HTTP request using the ``-d`` option. This is useful if you need to
+submit JSON structures, for example document data, as part of the
+request. For example, to submit a simple document to the ``demo``
+database:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' \
+ -X POST http://127.0.0.1:5984/demo \
+ -d '{"company": "Example, Inc."}'
+ {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+ "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
+
+In the above example, the argument after the ``-d`` option is the JSON
+of the document we want to submit.
+
+The document can be accessed by using the automatically generated
+document ID that was returned:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
+ {"_id":"8843faaf0b831d364278331bc3001bd8",
+ "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+ "company":"Example, Inc."}
+
+The API samples in the :ref:`api/basics` show the HTTP command, URL and any
+payload information that needs to be submitted (and the expected return
+value). All of these examples can be reproduced using ``curl`` with the
+command-line examples shown above.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/futon.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/futon.rst b/share/doc/src/intro/futon.rst
new file mode 100644
index 0000000..3f93f5e
--- /dev/null
+++ b/share/doc/src/intro/futon.rst
@@ -0,0 +1,186 @@
+.. 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.
+
+.. _intro/futon:
+
+===================================
+Futon: Web GUI Administration Panel
+===================================
+
+Futon is a native web-based interface built into CouchDB. It provides a
+basic interface to the majority of the functionality, including the
+ability to create, update, delete and view documents and views, provides
+access to the configuration parameters, and an interface for initiating
+replication.
+
+The default view is the Overview page which provides you with a list of
+the databases. The basic structure of the page is consistent regardless
+of the section you are in. The main panel on the left provides the main
+interface to the databases, configuration or replication systems. The
+side panel on the right provides navigation to the main areas of Futon
+interface:
+
+.. figure:: ../../images/futon-overview.png
+ :align: center
+ :alt: Futon Overview
+
+ Futon Overview
+
+The main sections are:
+
+- Overview
+
+ The main overview page, which provides a list of the databases and
+ provides the interface for querying the database and creating and
+ updating documents. See :ref:`futon-management`.
+
+- Configuration
+
+ An interface into the configuration of your CouchDB installation. The
+ interface allows you to edit the different configurable parameters.
+ For more details on configuration, see :ref:`config` section.
+
+- Replicator
+
+ An interface to the replication system, enabling you to initiate
+ replication between local and remote databases. See
+ :ref:`futon-replication`.
+
+- Status
+
+ Displays a list of the running background tasks on the server.
+ Background tasks include view index building, compaction and
+ replication. The Status page is an interface to the
+ :ref:`Active Tasks <api/server/active_tasks>` API call.
+
+- Verify Installation
+
+ The Verify Installation allows you to check whether all of the
+ components of your CouchDB installation are correctly installed.
+
+- Test Suite
+
+ The Test Suite section allows you to run the built-in test suite.
+ This executes a number of test routines entirely within your browser
+ to test the API and functionality of your CouchDB installation. If
+ you select this page, you can run the tests by using the Run All
+ button. This will execute all the tests, which may take some time.
+
+
+.. _futon-management:
+
+Managing Databases and Documents
+================================
+
+You can manage databases and documents within Futon using the main
+Overview section of the Futon interface.
+
+To create a new database, click the Create Database ELLIPSIS button. You
+will be prompted for the database name, as shown in the figure below.
+
+.. figure:: ../../images/futon-createdb.png
+ :align: center
+ :alt: Creating a Database
+
+ Creating a Database
+
+Once you have created the database (or selected an existing one), you
+will be shown a list of the current documents. If you create a new
+document, or select an existing document, you will be presented with the
+edit document display.
+
+Editing documents within Futon requires selecting the document and then
+editing (and setting) the fields for the document individually before
+saving the document back into the database.
+
+For example, the figure below shows the editor for a single document, a
+newly created document with a single ID, the document ``_id`` field.
+
+.. figure:: ../../images/futon-editdoc.png
+ :align: center
+ :alt: Editing a Document
+
+ Editing a Document
+
+To add a field to the document:
+
+1. Click Add Field.
+
+2. In the fieldname box, enter the name of the field you want to create.
+ For example, “company”.
+
+3. Click the green tick next to the field name to confirm the field name
+ change.
+
+4. Double-click the corresponding Value cell.
+
+5. Enter a company name, for example “Example”.
+
+6. Click the green tick next to the field value to confirm the field
+ value.
+
+7. The document is still not saved as this point. You must explicitly
+ save the document by clicking the Save Document button at the top of
+ the page. This will save the document, and then display the new
+ document with the saved revision information (the ``_rev`` field).
+
+ .. figure:: ../../images/futon-editeddoc.png
+ :align: center
+ :alt: Edited Document
+
+ Edited Document
+
+The same basic interface is used for all editing operations within Futon.
+You *must* remember to save the individual element (fieldname, value)
+using the green tick button, before then saving the document.
+
+
+.. _futon-replication:
+
+Configuring Replication
+=======================
+
+When you click the Replicator option within the Tools menu you are
+presented with the Replicator screen. This allows you to start
+replication between two databases by filling in or select the
+appropriate options within the form provided.
+
+.. figure:: ../../images/futon-replform.png
+ :align: center
+ :alt: Replication Form
+
+ Replication Form
+
+To start a replication process, either the select the local database or
+enter a remote database name into the corresponding areas of the form.
+Replication occurs from the database on the left to the database on the
+right.
+
+If you are specifying a remote database name, you must specify the full
+URL of the remote database (including the host, port number and database
+name). If the remote instance requires authentication, you can specify
+the username and password as part of the URL, for example
+``http://username:pass@remotehost:5984/demo``.
+
+To enable continuous replication, click the Continuous checkbox.
+
+To start the replication process, click the Replicate button. The
+replication process should start and will continue in the background. If
+the replication process will take a long time, you can monitor the
+status of the replication using the Status option under the Tools menu.
+
+Once replication has been completed, the page will show the information
+returned when the replication process completes by the API.
+
+The Replicator tool is an interface to the underlying replication API.
+For more information, see :ref:`api/server/replicate`. For more information on
+replication, see :ref:`replication`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/index.rst b/share/doc/src/intro/index.rst
new file mode 100644
index 0000000..900dca2
--- /dev/null
+++ b/share/doc/src/intro/index.rst
@@ -0,0 +1,50 @@
+.. 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.
+
+
+.. _intro:
+
+============
+Introduction
+============
+
+CouchDB is a database that completely embraces the web. Store your data with
+JSON documents. Access your documents with your web browser, :ref:`via HTTP
+<api/basics>`. :ref:`Query <api/doc>`, :ref:`combine <views>`,
+and :ref:`transform <listfun>` your documents with :ref:`JavaScript
+<query-server/js>`. CouchDB works well with modern web and mobile apps. You can
+even serve web apps directly out of CouchDB. And you can distribute your data,
+or your apps, efficiently using CouchDB’s :ref:`incremental replication
+<replication/intro>`. CouchDB supports master-master setups with
+:ref:`automatic conflict <replication/conflicts>` detection.
+
+CouchDB comes with a suite of features, such as on-the-fly document
+transformation and real-time :ref:`change notifications <changes>`, that makes
+:ref:`web app <couchapp>` development a breeze. It even comes with an easy
+to use :ref:`web administration console <intro/futon>`. You guessed it,
+served up directly out of CouchDB! We care a lot about `distributed scaling`_.
+CouchDB is highly available and partition tolerant, but is also :ref:`eventually
+consistent <intro/consistency>`. And we care *a lot* about your data.
+CouchDB has a fault-tolerant storage engine that puts the safety of your data
+first.
+
+.. _distributed scaling: http://en.wikipedia.org/wiki/CAP_theorem
+
+.. toctree::
+ :maxdepth: 2
+
+ overview
+ why
+ consistency
+ tour
+ futon
+ curl
http://git-wip-us.apache.org/repos/asf/couchdb/blob/7c4a8c4e/share/doc/src/intro/overview.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/overview.rst b/share/doc/src/intro/overview.rst
new file mode 100644
index 0000000..b36f8f1
--- /dev/null
+++ b/share/doc/src/intro/overview.rst
@@ -0,0 +1,387 @@
+.. 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.
+
+
+.. _intro/overview:
+
+==================
+Technical Overview
+==================
+
+Document Storage
+================
+
+A CouchDB server hosts named databases, which store **documents**.
+Each document is uniquely named in the database, and CouchDB provides
+a `RESTful`_ :ref:`HTTP API <api/basics>` for reading and updating (add, edit,
+delete) database documents.
+
+Documents are the primary unit of data in CouchDB and consist of any number
+of fields and attachments. Documents also include metadata that’s maintained
+by the database system. Document fields are uniquely named and contain values
+of :ref:`varying types <json>` (text, number, boolean, lists, etc),
+and there is no set limit to text size or element count.
+
+The CouchDB document update model is lockless and optimistic.
+Document edits are made by client applications loading documents,
+applying changes, and saving them back to the database. If another client
+editing the same document saves their changes first, the client gets an edit
+conflict error on save. To resolve the update conflict, the latest document
+version can be opened, the edits reapplied and the update tried again.
+
+Document updates (add, edit, delete) are all or nothing, either succeeding
+entirely or failing completely. The database never contains partially saved
+or edited documents.
+
+.. _RESTful: http://en.wikipedia.org/wiki/REST
+
+
+ACID Properties
+===============
+
+The CouchDB file layout and commitment system features all `Atomic Consistent
+Isolated Durable` (`ACID`_) properties. On-disk, CouchDB never overwrites
+committed data or associated structures, ensuring the database file is always
+in a consistent state. This is a "crash-only" design where the CouchDB
+server does not go through a shut down process, it's simply terminated.
+
+Document updates (add, edit, delete) are serialized, except for binary blobs
+which are written concurrently. Database readers are never locked out and
+never have to wait on writers or other readers. Any number of clients can be
+reading documents without being locked out or interrupted by concurrent
+updates, even on the same document. CouchDB read operations use a
+`Multi-Version Concurrency Control` (`MVCC`_) model where each client sees a
+consistent snapshot of the database from the beginning to the end of the read
+operation.
+
+Documents are indexed in `B-trees`_ by their name (DocID) and a Sequence ID.
+Each update to a database instance generates a new sequential number.
+Sequence IDs are used later for incrementally finding changes in a database.
+TheseBb-tree indexes are updated simultaneously when documents are saved or
+deleted. The index updates always occur at the end of the file (append-only
+updates).
+
+Documents have the advantage of data being already conveniently packaged for
+storage rather than split out across numerous tables and rows in most
+databases systems. When documents are committed to disk, the document fields
+and metadata are packed into buffers, sequentially one document after another
+(helpful later for efficient building of views).
+
+When CouchDB documents are updated, all data and associated indexes are
+flushed to disk and the transactional commit always leaves the database
+in a completely consistent state. Commits occur in two steps:
+
+#. All document data and associated index updates are synchronously flushed
+ to disk.
+
+#. The updated database header is written in two consecutive, identical chunks
+ to make up the first 4k of the file, and then synchronously flushed to disk.
+
+In the event of an OS crash or power failure during step 1,
+the partially flushed updates are simply forgotten on restart. If such a
+crash happens during step 2 (committing the header), a surviving copy of the
+previous identical headers will remain, ensuring coherency of all previously
+committed data. Excepting the header area, consistency checks or fix-ups
+after a crash or a power failure are never necessary.
+
+.. _ACID: http://en.wikipedia.org/wiki/ACID
+.. _MVCC: http://en.wikipedia.org/wiki/Multiversion_concurrency_control
+.. _B-trees: http://en.wikipedia.org/wiki/B-tree
+
+
+Compaction
+==========
+
+Wasted space is recovered by occasional compaction. On schedule, or when the
+database file exceeds a certain amount of wasted space, the compaction process
+clones all the active data to a new file and then discards the old file.
+The database remains completely online the entire time and all updates and
+reads are allowed to complete successfully. The old file is deleted only when
+all the data has been copied and all users transitioned to the new file.
+
+
+Views
+=====
+
+ACID properties only deal with storage and updates, we also need the ability
+to show our data in interesting and useful ways. Unlike SQL databases where
+data must be carefully decomposed into tables, data in CouchDB is stored in
+semi-structured documents. CouchDB documents are flexible and each has its
+own implicit structure, which alleviates the most difficult problems and
+pitfalls of bi-directionally replicating table schemas and their contained data.
+
+But beyond acting as a fancy file server, a simple document model for data
+storage and sharing is too simple to build real applications on -- it simply
+doesn't do enough of the things we want and expect. We want to slice and dice
+and see our data in many different ways. What is needed is a way to filter,
+organize and report on data that hasn't been decomposed into tables.
+
+.. seealso::
+
+ :ref:`views`
+
+
+View Model
+----------
+
+To address this problem of adding structure back to unstructured and
+semi-structured data, CouchDB integrates a view model. Views are the method
+of aggregating and reporting on the documents in a database, and are built
+on-demand to aggregate, join and report on database documents. Views are built
+dynamically and don’t affect the underlying document, you can have as many
+different view representations of the same data as you like.
+
+View definitions are strictly virtual and only display the documents from the
+current database instance, making them separate from the data they display
+and compatible with replication. CouchDB views are defined inside special
+**design documents** and can replicate across database instances like
+regular documents, so that not only data replicates in CouchDB,
+but entire application designs replicate too.
+
+
+Javascript View Functions
+-------------------------
+
+Views are defined using Javascript functions acting as the map part in a
+`map-reduce system`_. A :ref:`view function <viewfun>` takes a CouchDB document
+as an argument and then does whatever computation it needs to do to determine
+the data that is to be made available through the view, if any.
+It can add multiple rows to the view based on a single document,
+or it can add no rows at all.
+
+.. _map-reduce system: http://en.wikipedia.org/wiki/MapReduce
+
+.. seealso::
+
+ :ref:`viewfun`
+
+
+View Indexes
+------------
+
+Views are a dynamic representation of the actual document contents of a
+database, and CouchDB makes it easy to create useful views of data.
+But generating a view of a database with hundreds of thousands or millions of
+documents is time and resource consuming, it's not something the system
+should do from scratch each time.
+
+To keep view querying fast, the view engine maintains indexes of its views,
+and incrementally updates them to reflect changes in the database.
+CouchDB’s core design is largely optimized around the need for efficient,
+incremental creation of views and their indexes.
+
+Views and their functions are defined inside special "design" documents,
+and a design document may contain any number of uniquely named view functions.
+When a user opens a view and its index is automatically updated, all the views
+in the same design document are indexed as a single group.
+
+The view builder uses the database sequence ID to determine if the view group
+is fully up-to-date with the database. If not, the view engine examines the
+all database documents (in packed sequential order) changed since the last
+refresh. Documents are read in the order they occur in the disk file,
+reducing the frequency and cost of disk head seeks.
+
+The views can be read and queried simultaneously while also being refreshed.
+If a client is slowly streaming out the contents of a large view,
+the same view can be concurrently opened and refreshed for another client
+without blocking the first client. This is true for any number of
+simultaneous client readers, who can read and query the view while the index
+is concurrently being refreshed for other clients without causing problems
+for the readers.
+
+As documents are examined, their previous row values are removed from the
+view indexes, if they exist. If the document is selected by a view function,
+the function results are inserted into the view as a new row.
+
+When view index changes are written to disk, the updates are always appended
+at the end of the file, serving to both reduce disk head seek times during
+disk commits and to ensure crashes and power failures can not cause
+corruption of indexes. If a crash occurs while updating a view index,
+the incomplete index updates are simply lost and rebuilt incrementally from
+its previously committed state.
+
+
+Security and Validation
+=======================
+
+To protect who can read and update documents, CouchDB has a simple reader
+access and update validation model that can be extended to implement custom
+security models.
+
+.. seealso::
+
+ :ref:`api/db/security`
+
+
+Administrator Access
+--------------------
+
+CouchDB database instances have administrator accounts. Administrator
+accounts can create other administrator accounts and update design documents.
+Design documents are special documents containing view definitions and other
+special formulas, as well as regular fields and blobs.
+
+
+Update Validation
+-----------------
+
+As documents written to disk, they can be validated dynamically by javascript
+functions for both security and data validation. When the document passes
+all the formula validation criteria, the update is allowed to continue.
+If the validation fails, the update is aborted and the user client gets an
+error response.
+
+Both the user's credentials and the updated document are given as inputs to
+the validation formula, and can be used to implement custom security models
+by validating a user's permissions to update a document.
+
+A basic "author only" update document model is trivial to implement,
+where document updates are validated to check if the user is listed in an
+"author" field in the existing document. More dynamic models are also possible,
+like checking a separate user account profile for permission settings.
+
+The update validations are enforced for both live usage and replicated
+updates, ensuring security and data validation in a shared, distributed system.
+
+.. seealso::
+
+ :ref:`vdufun`
+
+
+Distributed Updates and Replication
+===================================
+
+CouchDB is a peer-based distributed database system, it allows for users and
+servers to access and update the same shared data while disconnected and then
+bi-directionally replicate those changes later.
+
+The CouchDB document storage, view and security models are designed to work
+together to make true bi-directional replication efficient and reliable.
+Both documents and designs can replicate, allowing full database applications
+(including application design, logic and data) to be replicated to laptops
+for offline use, or replicated to servers in remote offices where slow or
+unreliable connections make sharing data difficult.
+
+The replication process is incremental. At the database level,
+replication only examines documents updated since the last replication.
+Then for each updated document, only fields and blobs that have changed are
+replicated across the network. If replication fails at any step, due to network
+problems or crash for example, the next replication restarts at the same
+document where it left off.
+
+Partial replicas can be created and maintained. Replication can be filtered
+by a javascript function, so that only particular documents or those meeting
+specific criteria are replicated. This can allow users to take subsets of a
+large shared database application offline for their own use, while maintaining
+normal interaction with the application and that subset of data.
+
+
+Conflicts
+---------
+
+Conflict detection and management are key issues for any distributed edit
+system. The CouchDB storage system treats edit conflicts as a common state,
+not an exceptional one. The conflict handling model is simple and
+"non-destructive" while preserving single document semantics and allowing for
+decentralized conflict resolution.
+
+CouchDB allows for any number of conflicting documents to exist
+simultaneously in the database, with each database instance deterministically
+deciding which document is the "winner" and which are conflicts. Only the
+winning document can appear in views, while "losing" conflicts are still
+accessible and remain in the database until deleted or purged during
+database compaction. Because conflict documents are still regular documents,
+they replicate just like regular documents and are subject to the same
+security and validation rules.
+
+When distributed edit conflicts occur, every database replica sees the same
+winning revision and each has the opportunity to resolve the conflict.
+Resolving conflicts can be done manually or, depending on the nature of the
+data and the conflict, by automated agents. The system makes decentralized
+conflict resolution possible while maintaining single document database
+semantics.
+
+Conflict management continues to work even if multiple disconnected users or
+agents attempt to resolve the same conflicts. If resolved conflicts result in
+more conflicts, the system accommodates them in the same manner, determining
+the same winner on each machine and maintaining single document semantics.
+
+.. seealso::
+
+ :ref:`replication/conflicts`
+
+
+Applications
+------------
+
+Using just the basic replication model, many traditionally single server
+database applications can be made distributed with almost no extra work.
+CouchDB replication is designed to be immediately useful for basic database
+applications, while also being extendable for more elaborate and full-featured
+uses.
+
+With very little database work, it is possible to build a distributed
+document management application with granular security and full revision
+histories. Updates to documents can be implemented to exploit incremental
+field and blob replication, where replicated updates are nearly as efficient
+and incremental as the actual edit differences ("diffs").
+
+The CouchDB replication model can be modified for other distributed update
+models. If the storage engine is enhanced to allow multi-document update
+transactions, it is possible to perform Subversion-like "all or nothing"
+atomic commits when replicating with an upstream server, such that any single
+document conflict or validation failure will cause the entire update to fail.
+Like Subversion, conflicts would be resolved by doing a "pull" replication to
+force the conflicts locally, then merging and re-replicating to the upstream
+server.
+
+
+Implementation
+==============
+
+CouchDB is built on the `Erlang OTP platform`_, a functional,
+concurrent programming language and development platform. Erlang was
+developed for real-time telecom applications with an extreme emphasis on
+reliability and availability.
+
+Both in syntax and semantics, Erlang is very different from conventional
+programming languages like C or Java. Erlang uses lightweight "processes" and
+message passing for concurrency, it has no shared state threading and all
+data is immutable. The robust, concurrent nature of Erlang is ideal for a
+database server.
+
+CouchDB is designed for lock-free concurrency, in the conceptual model and
+the actual Erlang implementation. Reducing bottlenecks and avoiding locks
+keeps the entire system working predictably under heavy loads. CouchDB can
+accommodate many clients replicating changes, opening and updating documents,
+and querying views whose indexes are simultaneously being refreshed for
+other clients, without needing locks.
+
+For higher availability and more concurrent users, CouchDB is designed for
+"shared nothing" clustering. In a "shared nothing" cluster, each machine
+is independent and replicates data with its cluster mates, allowing individual
+server failures with zero downtime. And because consistency scans
+and fix-ups aren’t needed on restart,
+if the entire cluster fails -- due to a power outage in a datacenter,
+for example -- the entire CouchDB distributed system becomes immediately
+available after a restart.
+
+CouchDB is built from the start with a consistent vision of a distributed
+document database system. Unlike cumbersome attempts to bolt distributed
+features on top of the same legacy models and databases,
+it is the result of careful ground-up design, engineering and integration.
+The document, view, security and replication models, the special purpose query
+language, the efficient and robust disk layout and the concurrent and reliable
+nature of the Erlang platform are all carefully integrated for a reliable
+and efficient system.
+
+.. _Erlang OTP platform: http://www.erlang.org/
[06/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Fix typos and namings.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/8a69a113
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/8a69a113
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/8a69a113
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 8a69a113314889caa3f7f17ec56d94a44457b129
Parents: 5cf9306
Author: Alexander Shorin <kx...@apache.org>
Authored: Sat Aug 17 16:17:34 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 21:59:45 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/common.rst | 2 +-
share/doc/src/api/document/common.rst | 10 +++++-----
3 files changed, 7 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/8a69a113/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index d703ecb..faf04c3 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -260,7 +260,7 @@
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 144
- Content-Type: appliaction/json
+ Content-Type: application/json
Date: Mon, 12 Aug 2013 00:15:05 GMT
Server: CouchDB/1.4.0 (Erlang OTP/R16B)
http://git-wip-us.apache.org/repos/asf/couchdb/blob/8a69a113/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index dc17465..4880e61 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -275,7 +275,7 @@
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Quoted new document's revision
:>header Location: Document's URI
- :>json string id: Created document ID
+ :>json string id: Document ID
:>json boolean ok: Operation status
:>json string rev: Revision info
:code 201: Document created and stored on disk
http://git-wip-us.apache.org/repos/asf/couchdb/blob/8a69a113/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index e9ca7dc..adbf03e 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -185,7 +185,7 @@
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Quoted document's new revision
:>header Location: Document URI
- :>json string id: Created document ID
+ :>json string id: Document ID
:>json boolean ok: Operation status
:>json string rev: Revision MVCC token
:code 201: Document created and stored on disk
@@ -261,7 +261,7 @@
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Double quoted document's new revision
- :>json string id: Created document ID
+ :>json string id: Document ID
:>json boolean ok: Operation status
:>json string rev: Revision MVCC token
:code 200: Document successfully removed
@@ -269,7 +269,7 @@
:code 400: Invalid request body or parameters
:code 401: Write privileges required
:code 404: Specified database or document ID doesn't exists
- :code 409: Specified revision is not latest for target document
+ :code 409: Specified revision is not the latest for target document
**Request**:
@@ -333,8 +333,8 @@
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Double quoted document's new revision
- :>header Location: Document's URI
- :>json string id: Created document ID
+ :>header Location: Document URI
+ :>json string id: Document document ID
:>json boolean ok: Operation status
:>json string rev: Revision MVCC token
:code 201: Document successfully created
[48/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 2375d00
Posted by kx...@apache.org.
Improve grammar, text flow in new configuration docs.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/cf4a09bc
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/cf4a09bc
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/cf4a09bc
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: cf4a09bce2848f3cb0fe98bfe4e32d4a930da674
Parents: 738095b
Author: Dirkjan Ochtman <dj...@apache.org>
Authored: Fri Sep 20 14:37:59 2013 +0200
Committer: Alexander Shorin <kx...@apache.org>
Committed: Fri Sep 27 22:01:49 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/server/common.rst | 8 +--
share/doc/src/config/auth.rst | 110 +++++++++++++++++++------------
share/doc/src/config/couchdb.rst | 88 +++++++++++++++----------
share/doc/src/config/http.rst | 6 +-
share/doc/src/config/misc.rst | 55 ++++++++--------
5 files changed, 160 insertions(+), 107 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index 690c55d..22e312d 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -959,9 +959,9 @@ structure is as follows:
The UUID type is determined by the :ref:`UUID algorithm <config/uuids/algorithm>`
setting in the CouchDB configuration.
-The UUID type could be changed in anytime through
-:ref:`Config API <api/config/section/key>`. For example, changing the UUID
-type to ``random`` use next HTTP request:
+The UUID type may be changed at any time through the
+:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
+could be changed to ``random`` by sending this HTTP request:
.. code-block:: http
@@ -971,7 +971,7 @@ type to ``random`` use next HTTP request:
"random"
-When obtaining a list of UUIDs you'll see the changes:
+You can verify the change by obtaining a list of UUIDs:
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 410ae46..279e124 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -108,7 +108,9 @@ work factor for ``PBKDF2``, and the algorithm itself at
``allow_persistent_cookies`` :: Persistent cookies
--------------------------------------------------
-Makes cookies persistent if ``true``::
+Makes cookies persistent if ``true``.
+
+::
[couch_httpd_auth]
allow_persistent_cookies = false
@@ -119,7 +121,9 @@ Makes cookies persistent if ``true``::
``auth_cache_size`` :: Authentication cache
-------------------------------------------
-Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
+Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+
+::
[couch_httpd_auth]
auth_cache_size = 50
@@ -130,14 +134,15 @@ Number of :ref:`userctx_object` to cache in memory to reduce disk lookups::
``authentication_db`` :: Users database
---------------------------------------
-Specifies the name of the system database for storing CouchDB users::
+Specifies the name of the system database for storing CouchDB users.
+
+::
[couch_httpd_auth]
authentication_db = _users
-.. warning:: If there was any reasons to change this name for you, don't forget
- to remove/cleanup old database since it wouldn't be protected by CouchDB
- anymore.
+.. warning:: If you change the database name, do not forget to remove or clean
+ up the old database, since it will no longer be protected by CouchDB.
.. _config/couch_httpd_auth/authentication_redirect:
@@ -146,7 +151,9 @@ Specifies the name of the system database for storing CouchDB users::
---------------------------------------------------------------------------
Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via ``Accept`` header)::
+``text/html`` response is accepted by the client (via an ``Accept`` header).
+
+::
[couch_httpd_auth]
authentication_redirect = /_utils/session.html
@@ -159,8 +166,11 @@ Specifies the location for redirection on successful authentication if a
.. versionadded:: 1.3
-The umbenr of iterations for password hashing by the PBKDF2 algorithm. A higher
-number provides better hash durability, but with cost of performance on each request that requires authentication::
+The number of iterations for password hashing by the PBKDF2 algorithm. A higher
+number provides better hash durability, but comes at a cost in performance for
+each request that requires authentication.
+
+::
[couch_httpd_auth]
iterations = 10000
@@ -171,8 +181,11 @@ number provides better hash durability, but with cost of performance on each req
``proxy_use_secret`` :: Force proxy auth use secret token
---------------------------------------------------------
-When this option is ``true`` the :ref:`secret <config/couch_httpd_auth/secret>`
-is required for :ref:`api/auth/proxy`::
+When this option is set to ``true``, the
+:ref:`secret <config/couch_httpd_auth/secret>` option is required for
+:ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
proxy_use_secret = false
@@ -185,9 +198,10 @@ is required for :ref:`api/auth/proxy`::
.. versionadded:: 1.4
-Comma-separated list of field names that will be available to view for any user
-document in :ref:`authentication_db <config/couch_httpd_auth/authentication_db>`
-If unset or not specified, authenticated users may retrieve only their own docs.
+A comma-separated list of field names in user documents (in
+:ref:`authentication_db <config/couch_httpd_auth/authentication_db>`) that can
+be read by any user. If unset or not specified, authenticated users can only
+retrieve their own document.
::
@@ -204,11 +218,13 @@ If unset or not specified, authenticated users may retrieve only their own docs.
.. _config/couch_httpd_auth/require_valid_user:
-``require_valid_user`` :: Force users authentication
-----------------------------------------------------
+``require_valid_user`` :: Force user authentication
+---------------------------------------------------
+
+When this option is set to ``true``, no requests are allowed from anonymous
+users. Everyone must be authenticated.
-When this option ``true`` no requests allowed from anonymous users. Everyone
-must be authenticated::
+::
[couch_httpd_auth]
require_valid_user = false
@@ -219,7 +235,9 @@ must be authenticated::
``secret`` :: Proxy Auth secret token
-------------------------------------
-The secret token used for :ref:`api/auth/proxy` method::
+The secret token used for :ref:`api/auth/proxy` method.
+
+::
[couch_httpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91
@@ -230,7 +248,9 @@ The secret token used for :ref:`api/auth/proxy` method::
``timeout`` :: Session timeout
------------------------------
-Number of seconds since the last request before session will be expired::
+Number of seconds since the last request before sessions will be expired.
+
+::
[couch_httpd_auth]
timeout = 600
@@ -239,13 +259,15 @@ Number of seconds since the last request before session will be expired::
.. _config/couch_httpd_auth/users_db_public:
-``users_db_public`` :: Publish users info
------------------------------------------
+``users_db_public`` :: Publish user documents
+---------------------------------------------
.. versionadded:: 1.4
Allow all users to view user documents. By default, only admins may browse
-all users documents while users may browse only their own document::
+all users documents, while users may browse only their own document.
+
+::
[couch_httpd_auth]
users_db_public = false
@@ -256,8 +278,10 @@ all users documents while users may browse only their own document::
``x_auth_roles`` :: Proxy Auth roles header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the list of
-user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
+list of a user's roles, separated by a comma. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Roles
@@ -268,13 +292,16 @@ user's roles separated by a comma. Used for :ref:`api/auth/proxy`::
``x_auth_token`` :: Proxy Auth token header
-------------------------------------------
-HTTP header name (``X-Auth-CouchDB-Token`` by default) with token to
-authenticate the authorization. This token is an `HMAC-SHA1` created from
-:ref:`secret key <config/couch_httpd_auth/secret>` and
+The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
+token used to authenticate the authorization. This token is an `HMAC-SHA1`
+created from :ref:`secret key <config/couch_httpd_auth/secret>` and
:ref:`username <config/couch_httpd_auth/x_auth_username>`. The secret key
-should be the same in the client and CouchDB node. This token is optional
-if value of :ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option isn't ``true``. Used for :ref:`api/auth/proxy`::
+should be the same on the client and the CouchDB node. This token is optional
+if the value of the
+:ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
+option is not ``true``. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Token
@@ -285,8 +312,10 @@ option isn't ``true``. Used for :ref:`api/auth/proxy`::
``x_auth_username`` :: Proxy Auth username header
-------------------------------------------------
-HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`::
+The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
+username. Used for :ref:`api/auth/proxy`.
+
+::
[couch_httpd_auth]
x_auth_username = X-Auth-CouchDB-UserName
@@ -305,11 +334,10 @@ username. Used for :ref:`api/auth/proxy`::
Store credentials within config
-------------------------------
-To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`) method
-there is need to setup three special sections in :ref:`configuration <config>`
-file:
+To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
+special sections must be set up in the :ref:`configuration <config>` file:
-1. Consumer secret:
+1. The Consumer secret:
::
@@ -323,7 +351,7 @@ file:
[oauth_token_secrets]
token1 = tokensekr1t
-3. Tokens to users mapping:
+3. A mapping from tokens to users:
::
@@ -339,8 +367,8 @@ Store OAuth credentials within auth database
.. versionadded:: 1.2
-CouchDB is able to store OAuth credentials within users documents instead of
-config file by using next option::
+CouchDB is able to store OAuth credentials within user documents instead of
+config file by using this option::
[couch_httpd_oauth]
use_users_db = true
@@ -348,7 +376,7 @@ config file by using next option::
If set to ``true``, OAuth token and consumer secrets will be looked up in the
:ref:`authentication database <config/couch_httpd_auth/authentication_db>`.
These secrets are stored in a top level field named ``"oauth"`` in user
-documents. Example:
+documents, as below.
.. code-block:: javascript
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index 053f7e9..c1bd182 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -26,9 +26,12 @@ Base Configuration
``attachment_stream_buffer_size`` :: Attachment streaming buffer
----------------------------------------------------------------
-Higher values may give better read performance due to less read operations
-and/or more OS page cache hits, but they can also increase overall response
-time for writes when there are many attachment write requests in parallel::
+Higher values may result in better read performance due to fewer read
+operations and/or more OS page cache hits. However, they can also increase
+overall response time for writes when there are many attachment write
+requests in parallel.
+
+::
[couchdb]
attachment_stream_buffer_size = 4096
@@ -39,9 +42,11 @@ time for writes when there are many attachment write requests in parallel::
``database_dir`` :: Databases location directory
------------------------------------------------
-Specifies location of CouchDB databases files (``*.couch`` named). This location
-should be writable and readable for user that runs CouchDB service (``couchdb``
-by default)::
+Specifies location of CouchDB database files (``*.couch`` named). This location
+should be writable and readable for the user the CouchDB service runs as
+(``couchdb`` by default).
+
+::
[couchdb]
database_dir = /var/lib/couchdb
@@ -74,15 +79,15 @@ losing durability - it's strongly not recommended to do such in production::
``file_compression`` :: Compression method for documents
-----------------------------------------------------------
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm
+.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
Method used to compress everything that is appended to database and view index
files, except for attachments (see the :ref:`[attachments] <config/attachments>`
section). Available methods are:
* ``none``: no compression
-* ``snappy``: use Google Snappy, a very fast compressor/decompressor.
-* ``deflate_N``: use zlib's deflate, ``N`` is the compression level which ranges
+* ``snappy``: use Google Snappy, a very fast compressor/decompressor
+* ``deflate_N``: use zlib's deflate; ``N`` is the compression level which ranges
from 1 (fastest, lowest compression ratio) to 9 (slowest, highest compression
ratio)
@@ -99,9 +104,11 @@ section). Available methods are:
``fsync_options`` :: Fsync options
----------------------------------
-Specifies when to make `fsync` calls. `fsync` makes sure that any file system
-buffers kept by the operating system are written to disk. Normally, you have no
-need to edit this parameter::
+Specifies when to make `fsync` calls. `fsync` makes sure that the contents of
+any file system buffers kept by the operating system are flushed to disk.
+There is generally no need to modify this parameter.
+
+::
[couchdb]
fsync_options = [before_header, after_header, on_file_open]
@@ -112,11 +119,13 @@ need to edit this parameter::
``max_dbs_open`` :: Limit of simultaneously opened databases
------------------------------------------------------------
-This option places an upper bound on the number of databases that can be open at
-one time. CouchDB reference counts database accesses internally and will close
-idle databases when it must. Sometimes it is necessary to keep more than the
+This option places an upper bound on the number of databases that can be open
+at once. CouchDB reference counts database accesses internally and will close
+idle databases as needed. Sometimes it is necessary to keep more than the
default open at once, such as in deployments where many databases will be
-continuously replicating::
+replicating continuously.
+
+::
[couchdb]
max_dbs_open = 100
@@ -129,11 +138,13 @@ continuously replicating::
.. versionchanged:: 1.3 This option now actually works.
-Defines limit of size in bytes that document may has in JSON form. Doesn't
-applies for attachments since they are been transferred as stream of chunks.
-Do not set this value too small since you want be able to modify config options,
-database security and other options until you restore this value by edit config
-file::
+Defines a maximum size for JSON documents, in bytes. This limit does not
+apply to attachments, since they are transferred as a stream of chunks. If you
+set this to a small value, you might be unable to modify configuration options,
+database security and other larger documents until a larger value is restored
+by editing the configuration file.
+
+::
[couchdb]
max_document_size = 4294967296 ; 4 GB
@@ -144,10 +155,12 @@ file::
``os_process_timeout`` :: External processes time limit
-------------------------------------------------------
-Number of microseconds that external processes such as `query server` and
-`externals` may process CouchDB commands before return any result. Keeping
-this value smaller you'll be ensured that your services works fast, but you may
-tweak it depending on your needs::
+If an external process, such as a query server or external process, runs for
+this amount of microseconds without returning any results, it will be
+terminated. Keeping this value smaller ensures you get expedient errors, but
+you may want to tweak it for your specific needs.
+
+::
[couchdb]
os_process_timeout = 5000 ; 5 sec
@@ -158,10 +171,13 @@ tweak it depending on your needs::
``uri_file`` :: Discovery CouchDB help file
-------------------------------------------
-This file contains full `URI`_ that runs CouchDB. It's used to help discover
-CouchDB served port if it was set to ``0`` (e.g. automatically assigned any
-free one). This file should be writable and readable for user that runs CouchDB
-service (``couchdb`` by default)::
+This file contains the full `URI`_ that can be used to access this instance of
+CouchDB. It is used to help discover the port CouchDB is running on (if it was
+set to ``0`` (e.g. automatically assigned any free one). This file should be
+writable and readable for the user that runs the CouchDB service (``couchdb``
+by default).
+
+::
[couchdb]
uri_file = /var/run/couchdb/couchdb.uri
@@ -174,8 +190,10 @@ service (``couchdb`` by default)::
``util_driver_dir`` :: CouchDB binary utility drivers
-----------------------------------------------------
-Specified location of binary drivers (`icu`, `ejson`, etc.). This location and
-his content should be readable for user that runs CouchDB service::
+Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
+its contents should be readable for the user that runs the CouchDB service.
+
+::
[couchdb]
util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.3.0/priv/lib
@@ -188,7 +206,9 @@ his content should be readable for user that runs CouchDB service::
.. versionadded:: 1.3
-Unique identifier of CouchDB server instance::
+Unique identifier for this CouchDB server instance.
+
+::
[couchdb]
uuid = 0a959b9b8227188afc2ac26ccdf345a6
@@ -200,7 +220,9 @@ Unique identifier of CouchDB server instance::
-----------------------------------------------------
Specifies location of CouchDB view index files. This location should be writable
-and readable for user that runs CouchDB service (``couchdb`` by default)::
+and readable for the user that runs the CouchDB service (``couchdb`` by default).
+
+::
[couchdb]
view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 3c86585..f225092 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -653,9 +653,9 @@ behind a proxy, then you don't need to specify a port number in the `vhost` key.
The first line will rewrite the request to display the content of the `example`
database. This rule works only if the ``Host`` header is ``couchdb.local`` and
-won't work for `CNAMEs`. The second rule on the other hand matches all
-`CNAMEs` to `example` db. So `www.couchdb.local` or `db.couchdb.local` will
-work.
+won't work for `CNAMEs`. The second rule, on the other hand, matches all
+`CNAMEs` to `example` db, so that both `www.couchdb.local` and `db.couchdb.local`
+will work.
.. _config/vhosts/rewriting:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cf4a09bc/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index ffd9041..235142d 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -27,7 +27,7 @@ Miscellaneous Parameters
---------------------
Defines zlib compression level for the attachments from ``1`` (lowest, fastest)
-to ``9`` (highest, slowest). ``0`` value disables compression::
+to ``9`` (highest, slowest). A value of ``0`` disables compression::
[attachments]
compression_level = 8
@@ -38,8 +38,8 @@ to ``9`` (highest, slowest). ``0`` value disables compression::
``compressible_types``
----------------------
-While not all attached files could be compressed well, it is possible to let
-CouchDB compress only specific attachments identified by their MIME type::
+Since compression is ineffective for some types of files, it is possible to let
+CouchDB compress only some types of attachments, specified by their MIME type::
[attachments]
compressible_types = text/*, application/javascript, application/json, application/xml
@@ -81,8 +81,8 @@ intervals (in seconds)::
.. versionchanged:: 1.3 ``utc_id`` algorithm.
-CouchDB provides various algorithms to generate UUID value that will be used
-for document `_id` by default::
+CouchDB provides various algorithms to generate the UUID values that are used
+for document `_id`'s by default::
[uuids]
algorithm = sequential
@@ -109,9 +109,9 @@ Available algorithms:
}
- ``sequential``: Monotonically increasing ids with random increments.
- First 26 hex characters are random. Last 6 increment in random amounts until
- an overflow occurs. On overflow, the random prefix is regenerated and the
- process starts over:
+ The first 26 hex characters are random, the last 6 increment in random
+ amounts until an overflow occurs. On overflow, the random prefix is
+ regenerated and the process starts over.
.. code-block:: javascript
@@ -130,8 +130,8 @@ Available algorithms:
]
}
-- ``utc_random``: Time since Jan 1, 1970 UTC with microseconds. First 14
- characters are the time in hex. Last 18 are random:
+- ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
+ 14 characters are the time in hex. The last 18 are random.
.. code-block:: javascript
@@ -150,9 +150,9 @@ Available algorithms:
]
}
-- ``utc_id``: Time since Jan 1, 1970 UTC with microseconds,
- plus ``utc_id_suffix`` string. First 14 characters are the time in hex.
- :ref:`config/uuids/utc_id_suffix` string value is appended to these:
+- ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
+ the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
+ The :ref:`config/uuids/utc_id_suffix` string value is appended to these.
.. code-block:: javascript
@@ -171,14 +171,15 @@ Available algorithms:
]
}
-.. note:: **Impact of UUID choices:**
- The choice of UUID has a significant impact on the layout of the B-tree,
- prior to compaction.
+.. note::
- For example, a sequential UUID algorithm during uploading thousands of
- documents, will avoid the need to rewrite many intermediate B-tree nodes.
+ **Impact of UUID choices:** the choice of UUID has a significant impact on
+ the layout of the B-tree, prior to compaction.
+
+ For example, using a sequential UUID algorithm while uploading a large batch
+ of documents will avoid the need to rewrite many intermediate B-tree nodes.
A random UUID algorithm may require rewriting intermediate nodes on a regular
- basis, with a corresponding decrease of throughput, and significant wasted
+ basis, resulting in significantly decreased throughput and wasted disk space
space due to the append-only B-tree design.
It is generally recommended to set your own UUIDs, or use the sequential
@@ -193,9 +194,11 @@ UTC ID Suffix
.. versionadded:: 1.3
-The utc_id_suffix value will be appended to UUIDs generated by the ``utc_id``
-algorithm. Replicating instances should have unique utc_id_suffix values to
-ensure uniqueness of ``utc_id`` ids::
+The ``utc_id_suffix`` value will be appended to UUIDs generated by the
+``utc_id`` algorithm. Replicating instances should have unique
+``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
+
+::
[uuid]
utc_id_suffix = my-awesome-suffix
@@ -208,11 +211,11 @@ ensure uniqueness of ``utc_id`` ids::
.. versionadded:: 1.3
-For CouchDB distributors there is an option to customise CouchDB's welcome
-message which is returned when requesting ``GET /``.
+CouchDB distributors have the option of customizing CouchDB's welcome
+message. This is returned when requesting ``GET /``.
+
+::
[vendor]
name = The Apache Software Foundation
version = 1.3.0
-
-