EVOLUTION-MANAGER

Edit File: drv_couchdb.html

<html>
<head>
<title>CouchDB - CouchDB/GeoCouch</title>
</head>

<h1>CouchDB - CouchDB/GeoCouch</h1>

(GDAL/OGR >= 1.9.0)<p>

This driver can connect to the a CouchDB service, potentially enabled with the GeoCouch spatial extension.<p>
GDAL/OGR must be built with Curl support in order to the CouchDB driver to be compiled.<p>
The driver supports read and write operations.<p>

<h2>CouchDB vs OGR concepts</h2>

A CouchDB database is considered as a OGR layer. A CouchDB document is considered as a OGR feature.<p>

OGR handles preferably CouchDB documents following the GeoJSON specification.<p>

<h2>Dataset name syntax</h2>

The syntax to open a CouchDB datasource is : <pre>couchdb:http://example.com[/layername]</pre> where
http://example.com points to the root of a CouchDB repository and, optionally, layername is the name of a CouchDB database.<p>

It is also possible to directly open a view : <pre>couchdb:http://example.com/layername/_design/adesigndoc/_view/aview[?include_docs=true]</pre>
The include_docs=true might be needed depending on the value returned by the emit() call in the map() function.<p>

<h2>Authentication</h2>

Some operations, in particular write operations, require authentication. The authentication can
be passed with the <i>COUCHDB_USERPWD</i> environment variable set to user:password or directly in the URL.<p>

<h2>Filtering</h2>

The driver will forward any spatial filter set with SetSpatialFilter() to the server when GeoCouch extension
is available. It also makes the same for (very simple) attribute filters set with SetAttributeFilter(). When
server-side filtering fails, it will default back to client-side filtering.<p>

By default, the driver will try the following spatial filter function "_design/ogr_spatial/_spatial/spatial",
which is the valid spatial filter function for layers created by OGR. If that filter function does not exist,
but another one exists, you can specify it with the COUCHDB_SPATIAL_FILTER configuration option.<p>

Note that the first time an attribute request is issued, it might require write permissions in the database
to create a new index view.<p>

<h2>Paging</h2>

Features are retrieved from the server by chunks of 500 by default. This number can be altered with the COUCHDB_PAGE_SIZE
configuration option.<p>

<h2>Write support</h2>

Table creation and deletion is possible.<p>

Write support is only enabled when the datasource is opened in update mode.<p>

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the
returned _id and _rev and use them.<p>

<h2>Write support and OGR transactions</h2>

The CreateFeature()/SetFeature() operations are by default issued to the server synchronously with the OGR API call. This however
can cause performance penalties when issuing a lot of commands due to many client/server exchanges.<p>

It is possible to surround the CreateFeature()/SetFeature() operations between OGRLayer::StartTransaction() and OGRLayer::CommitTransaction().
The operations will be stored into memory and only executed at the time CommitTransaction() is called.<p>

<h2>Layer creation options</h2>

The following layer creation options are supported:
<ul>
<li><b>UPDATE_PERMISSIONS</b> = LOGGED_USER|ALL|ADMIN|function(...)|DEFAULT : Update permissions for the new layer.
<ul>
<li>If set to LOGGED_USER (the default), only logged users will be able to make changes in the layer.</li>
<li>If set to ALL, all users will be able to make changes in the layer.</li>
<li>If set to ADMIN, only administrators will be able to make changes in the layer.</li>
<li>If beginning with "function(", the value of the creation option will be used as the content of the <a href="http://guide.couchdb.org/draft/validation.html">validate_doc_update function</a>.</li>
<li>Otherwise, all users will be allowed to make changes in non-design documents.</li>
</ul>
</li>
<li><b>GEOJSON</b> = YES|NO : Set to NO to avoid writing documents as GeoJSON documents. Default to YES.</li>
<li><b>COORDINATE_PRECISION</b> = int_number : Maximum number of figures after decimal separator to write in coordinates.
Default to 15. "Smart" truncation will occur to remove trailing zeros.
Note: when opening a dataset in update mode, the OGR_COUCHDB_COORDINATE_PRECISION configuration option can be set to have a similar role.</li>
</ul>

<h2>Examples</h2>

<li>
Listing the tables of a CouchDB repository:
<pre>
ogrinfo -ro "couchdb:http://some_account.some_couchdb_server.com"
</pre>
<p>

<li>
Creating and populating a table from a shapefile:
<pre>
ogr2ogr -f couchdb "couchdb:http://some_account.some_couchdb_server.com" shapefile.shp
</pre>
<p>

<ul>
<li> <a href="http://wiki.apache.org/couchdb/Reference">CouchDB reference</a><p>
<li> <a href="http://github.com/couchbase/geocouch">GeoCouch source code repository</a><p>
<li> <a href="http://guide.couchdb.org/draft/validation.html">Documentation for 'validate_doc_update' function</a><p>
</ul>

</body>
</html>