CartoDB

(GDAL/OGR >= 1.11)

This driver can connect to the services implementing the CartoDB API. GDAL/OGR must be built with Curl support in order to the CartoDB driver to be compiled.

The driver supports read and write operations.

Dataset name syntax

The minimal syntax to open a CartoDB datasource is :

CartoDB:[account_name]

Additionnal optional parameters can be specified after the ':' sign. Currently the following one is supported :

tables=table_name1[,table_name2]*: A list of table names. This is necessary when you need to access to public tables for example.

If several parameters are specified, they must be separated by a space.

Configuration options

The following configuration options are available :

CARTODB_API_URL: defaults to https://[account_name].cartodb.com/api/v2/sql. Can be used to point to another server.
CARTODB_HTTPS: can be set to NO to use http:// protocol instead of https:// (only if CARTODB_API_URL is not defined).
CARTODB_API_KEY: see following paragraph.

Authentication

Most operations, in particular write operations, require an authenticated access. The only exception is read-only access to public tables.

Authenticated access is obtained by specifying the API key given in the management interface of the CartoDB service. It is specified with the CARTODB_API_KEY configuration option.

Geometry

The OGR driver will report as many geometry fields as available in the layer (except the 'the_geom_webmercator' field), following RFC 41.

Filtering

The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for attribute filters set with SetAttributeFilter().

Paging

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

Write support

Table creation and deletion is possible.

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

The mapping between the operations of the CartoDB service and the OGR concepts is the following :

OGRFeature::CreateFeature() <==> INSERT operation
OGRFeature::SetFeature() <==> UPDATE operation
OGRFeature::DeleteFeature() <==> DELETE operation
OGRDataSource::CreateLayer() <==> CREATE TABLE operation
OGRDataSource::DeleteLayer() <==> DROP TABLE operation

When inserting a new feature with CreateFeature(), and if the command is successfull, OGR will fetch the returned rowid and use it as the OGR FID.

Write support and OGR transactions

The above 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() operation between OGRLayer::StartTransaction() and OGRLayer::CommitTransaction(). The operations will be stored into memory and only executed at the time CommitTransaction() is called.

SQL

SQL commands provided to the OGRDataSource::ExecuteSQL() call are executed on the server side, unless the OGRSQL dialect is specified. You can use the full power of PostgreSQL + PostGIS SQL capabilities.

Examples

Acceccing data from a public table:

ogrinfo -ro "CartoDB:gdalautotest2 tables=tm_world_borders_simpl_0_3"

Creating and populating a table from a shapefile:

ogr2ogr --config CARTODB_API_KEY abcdefghijklmnopqrstuvw -f CartoDB "CartoDB:myaccount" myshapefile.shp