CouchDB - Cloudant

(GDAL/OGR >= 2.0.0)

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.

GDAL/OGR must be built with Curl support in order to the Cloudant driver to be compiled.

The driver supports read and write operations.

Cloudant vs OGR concepts

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

OGR preferably handles Cloudant documents following the GeoJSON specification.

Dataset name syntax

The syntax to open a Cloudant datasource is :

cloudant:http://example.com[/layername]

where http://example.com points to the root of a CouchDB repository and, optionally, layername is the name of a CouchDB database.

It is also possible to directly open a view :

cloudant:http://example.com/layername/_design/adesigndoc/_view/aview[?include_docs=true]

The include_docs=true might be needed depending on the value returned by the emit() call in the map() function.

Authentication

Some operations, in particular write operations, require authentication. The authentication can be passed with the CLOUDANT_USERPWD environment variable set to user:password or directly in the URL.

Filtering

The driver will forward any spatial filter set with SetSpatialFilter() to the server when the Cloudant extension is available.

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.

Paging

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

Write support

Table creation and deletion is possible.

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

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

Write support and OGR transactions

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.

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.

Layer creation options

The following layer creation options are supported:

UPDATE_PERMISSIONS = LOGGED_USER|ALL|ADMIN|function(...)|DEFAULT : Update permissions for the new layer.
- If set to LOGGED_USER (the default), only logged users will be able to make changes in the layer.
- If set to ALL, all users will be able to make changes in the layer.
- If set to ADMIN, only administrators will be able to make changes in the layer.
- If beginning with "function(", the value of the creation option will be used as the content of the validate_doc_update function.
- Otherwise, all users will be allowed to make changes in non-design documents.
GEOJSON = YES|NO : Set to NO to avoid writing documents as GeoJSON documents. Default to YES.
COORDINATE_PRECISION = 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.

Examples

Listing the tables of a Cloudant repository:

ogrinfo -ro "cloudant:http://some_account.some_cloudant_server.com"

Creating and populating a table from a shapefile:

ogr2ogr -f cloudant "cloudant:http://some_account.some_cloudant_server.com" shapefile.shp