EVOLUTION-MANAGER

Edit File: drv_cloudant.html

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

<h1>CouchDB - Cloudant</h1>

(GDAL/OGR >= 2.0.0)<p>

Cloudant and CouchDB are API compatible and based on the same core technology. The geospatial extension for Cloudant
is separate to GeoCouch.

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

<h2>Cloudant vs OGR concepts</h2>

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

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

<h2>Dataset name syntax</h2>

The syntax to open a Cloudant datasource is : <pre>cloudant: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>cloudant: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>CLOUDANT_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 the Cloudant extension
is available.<p>

By default, the driver will try the following spatial filter function "_design/SpatialView/_geo/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 CLOUDANT_SPATIAL_FILTER configuration option.<p>
<p>

<h2>Paging</h2>

Features are retrieved from the server by chunks of 200 by default. Cloudant uses bookmarks to page through the data.

<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_CLOUDANT_COORDINATE_PRECISION configuration option can be set to have a similar role.</li>
</ul>

<h2>Examples</h2>

<li>
Listing the tables of a Cloudant repository:
<pre>
ogrinfo -ro "cloudant:http://some_account.some_cloudant_server.com"
</pre>
<p>

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

<ul>
<li> <a href="http://wiki.apache.org/couchdb/Reference">CouchDB reference</a><p>
<li> <a href="https://cloudant.com/product/cloudant-features/geospatial/">Cloudant Geospatial</a><p>
<li> <a href="http://guide.couchdb.org/draft/validation.html">Documentation for 'validate_doc_update' function</a><p>
</ul>

</body>
</html>