Carto
Driver short name
CARTO
Build dependencies
libcurl
This driver can connect to the services implementing the Carto API. GDAL/OGR must be built with Curl support in order for the Carto driver to be compiled.
The driver supports read and write operations.
Driver capabilities
Supports Create()
This driver supports the GDALDriver::Create()
operation
Supports Georeferencing
This driver supports georeferencing
Dataset name syntax
The minimal syntax to open a Carto datasource is :
Carto:[connection_name]
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. Additional 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.
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 Carto service. It is specified with the CARTO_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
OGRLayer::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 CARTO_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 Carto service and the OGR concepts is the following :
OGRFeature::CreateFeature()
<==>INSERT
operationOGRFeature::SetFeature()
<==>UPDATE
operationOGRFeature::DeleteFeature()
<==>DELETE
operationOGRDataSource::CreateLayer()
<==>CREATE TABLE
operationOGRDataSource::DeleteLayer()
<==>DROP TABLE
operation
When inserting a new feature with OGRFeature::CreateFeature()
,
and if the command is successful, OGR will fetch the returned rowid and use it
as the OGR FID.
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
OGRFeature::CreateFeature()
operations are grouped together in chunks
until they reach 15 MB (can be changed with the CARTO_MAX_CHUNK_SIZE
configuration option, with a value in MB), at which point they are transferred
to the server. By setting CARTO_MAX_CHUNK_SIZE
to 0, immediate transfer occurs.
Warning
Don't use OGRDataSource::DeleteLayer()
and
OGRDataSource::CreateLayer()
to overwrite a table. Instead only
call OGRDataSource::CreateLayer()
with OVERWRITE=YES. This will
avoid CARTO deleting maps that depend on this table
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.
Open options
The following open options are available:
Open options can be specified in command-line tools using the syntax -oo <NAME>=<VALUE>
or by providing the appropriate arguments to GDALOpenEx()
(C) or gdal.OpenEx
(Python).
BATCH_INSERT=[YES/NO]: Defaults to
YES
. Whether to group feature insertions in a batch. Only apply in creation or update mode.COPY_MODE=[YES/NO]: Defaults to
YES
. Using COPY for insertions and reads can result in a performance improvement.
Layer creation options
Layer creation options can be specified in command-line tools using the syntax -lco <NAME>=<VALUE>
or by providing the appropriate arguments to GDALDatasetCreateLayer()
(C) or Dataset.CreateLayer
(Python).
The following layer creation options are supported:
OVERWRITE=[YES/NO]: Defaults to
NO
. Whether to overwrite an existing table with the layer name to be created.GEOMETRY_NULLABLE=[YES/NO]: Defaults to
YES
. Whether the values of the geometry column can be NULL.CARTODBFY=[YES/NO]: Defaults to
YES
. Whether the created layer should be "Cartodbifi'ed" (i.e. registered in dashboard). Requires:SRS: Output SRS must be EPSG:4326. You can use
-a_srs
or-t_srs
to assign or transform to 4326 before importing.Geometry type: Must be different than NONE. You can set to something generic with
-nlt GEOMETRY
.
LAUNDER=[YES/NO]: Defaults to
YES
. 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. If enabled the table (layer) name will also be laundered.
Configuration options
Configuration options can be specified in command-line tools using the syntax --config <NAME>=<VALUE>
or using functions such as CPLSetConfigOption()
(C) or gdal.config_options
(Python).
The following configuration options are available:
CARTO_API_URL=value: Defaults to
https://[account_name].carto.com/api/v2/sql
. Can be used to point to another server.CARTO_HTTPS=[YES/NO]: can be set to NO to use http:// protocol instead of https:// (only if
CARTO_API_URL
is not defined).CARTO_MAX_CHUNK_SIZE=value:
CARTO_API_KEY=value: see following paragraph.
CARTO_PAGE_SIZE=value: Defaults to
500
. features are retrieved from the server by chunks of 500 by default. This number can be altered with the configuration option.
Examples
Accessing data from a public table:
ogrinfo -ro "Carto:gdalautotest2 tables=tm_world_borders_simpl_0_3"
Creating and populating a table from a shapefile:
ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" myshapefile.shp
Creating and populating a table from a CSV containing geometries on EPSG:4326:
ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" file.csv -a_srs 4326 -nlt GEOMETRY
Note
The -a_srs
and -nlt
must be provided to CARTODBFY
since the information isn't extracted from the CSV.