(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 for 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 :
For single-user accounts, connection name is the account name.
For multi-user accounts, connection_name must be the user name, not the account name.
Additionnal optional parameters can be specified after the ':' sign.
Currently the following one is supported :
If several parameters are specified, they must be separated by a space.
- tables=table_name1[,table_name2]*: A list of table names.
This is necessary when you need to access to public tables for example.
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.
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.
The OGR driver will report as many geometry fields as available in the
layer (except the 'the_geom_webmercator' field), following RFC 41.
The driver will forward any spatial filter set with SetSpatialFilter() to
the server. It also makes the same for attribute
filters set with SetAttributeFilter().
Features are retrieved from the server by chunks of 500 by default.
This number can be altered with the CARTODB_PAGE_SIZE
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 :
When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the
returned rowid and use it as the OGR FID.
- OGRFeature::CreateFeature() <==> INSERT operation
- OGRFeature::SetFeature() <==> UPDATE operation
- OGRFeature::DeleteFeature() <==> DELETE operation
- OGRDataSource::CreateLayer() <==> CREATE TABLE operation
- OGRDataSource::DeleteLayer() <==> DROP TABLE operation
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.
So, on a newly created layer, the INSERT of CreateFeature() operations are grouped together
in chunks until they reach 15 MB (can be changed with the CARTODB_MAX_CHUNK_SIZE
configuration option, with a value in MB), at which point they are transfered
to the server. By setting CARTODB_MAX_CHUNK_SIZE to 0, immediate transfer occurs.
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
Starting with GDAL 2.0, the following open options are available:
- BATCH_INSERT=YES/NO: Whether to group feature insertions in a batch.
Defaults to YES. Only apply in creation or update mode.
Layer creation options
The following layer creation options are available:
- OVERWRITE=YES/NO: Whether to overwrite an existing table with the
layer name to be created. Defaults to NO.
- GEOMETRY_NULLABLE=YES/NO: Whether the values of the geometry column
can be NULL. Defaults to YES.
- CARTODBFY=YES/NO: Whether the created layer should be "CartoDBifi'ed"
(i.e. registered in dashboard). Defaults to YES.
- LAUNDER=YES/NO: This may be "YES" to force new fields created on this
layer to have their field names "laundered" into a form more compatible with
PostgreSQL. This converts to lower case and converts some special characters
like "-" and "#" to "_". If "NO" exact names are preserved.
The default value is "YES". If enabled the table (layer) name will also be laundered.
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