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 :
where 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 :

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


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.


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.


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:


  • Listing the tables of a Cloudant repository:
    ogrinfo -ro "cloudant:"

  • Creating and populating a table from a shapefile:
    ogr2ogr -f cloudant "cloudant:" shapefile.shp

    See Also