1.. _vector.carto:
2
3================================================================================
4Carto
5================================================================================
6
7.. shortname:: CARTO
8
9.. build_dependencies:: libcurl
10
11This driver can connect to the services implementing the Carto API. GDAL/OGR
12must be built with Curl support in order for the Carto driver to be compiled.
13
14The driver supports read and write operations.
15
16Driver capabilities
17-------------------
18
19.. supports_create::
20
21.. supports_georeferencing::
22
23Dataset name syntax
24-------------------
25
26The minimal syntax to open a Carto datasource is :
27
28.. code-block::
29
30   Carto:[connection_name]
31
32For single-user accounts, connection name is the account name. For multi-user
33accounts, connection_name must be the user name, not the account name.
34Additional optional parameters can be specified after the ':' sign.
35Currently the following one is supported:
36
37-  **tables=table_name1[,table_name2]\***: A list of table names. This
38   is necessary when you need to access to public tables for example.
39
40If several parameters are specified, they must be separated by a space.
41
42Configuration options
43---------------------
44
45The following configuration options are available :
46
47-  CARTO_API_URL: defaults to https://[account_name].carto.com/api/v2/sql.
48   Can be used to point to another server.
49-  CARTO_HTTPS: can be set to NO to use http:// protocol instead of
50   https:// (only if CARTO_API_URL is not defined).
51-  CARTO_API_KEY: see following paragraph.
52
53Authentication
54--------------
55
56Most operations, in particular write operations, require an authenticated
57access. The only exception is read-only access to public tables.
58
59Authenticated access is obtained by specifying the API key given in the
60management interface of the Carto service. It is specified with the
61CARTO_API_KEY configuration option.
62
63Geometry
64--------
65
66The OGR driver will report as many geometry fields as available in the layer
67(except the 'the_geom_webmercator' field), following RFC 41.
68
69Filtering
70---------
71
72The driver will forward any spatial filter set with
73:cpp:func:`OGRLayer::SetSpatialFilter` to the server.
74It also makes the same for attribute filters set with
75:cpp:func:`SetAttributeFilter`.
76
77Paging
78------
79
80Features are retrieved from the server by chunks of 500 by default. This
81number can be altered with the CARTO_PAGE_SIZE configuration option.
82
83Write support
84-------------
85
86Table creation and deletion is possible.
87
88Write support is only enabled when the datasource is opened in update
89mode.
90
91The mapping between the operations of the Carto service and the OGR
92concepts is the following :
93
94- :cpp:func:`OGRFeature::CreateFeature` <==> ``INSERT`` operation
95- :cpp:func:`OGRFeature::SetFeature` <==> ``UPDATE`` operation
96- :cpp:func:`OGRFeature::DeleteFeature` <==> ``DELETE`` operation
97- :cpp:func:`OGRDataSource::CreateLayer` <==> ``CREATE TABLE`` operation
98- :cpp:func:`OGRDataSource::DeleteLayer` <==> ``DROP TABLE`` operation
99
100When inserting a new feature with :cpp:func:`OGRFeature::CreateFeature`,
101and if the command is successful, OGR will fetch the returned rowid and use it
102as the OGR FID.
103
104The above operations are by default issued to the server synchronously with the
105OGR API call. This however can cause performance penalties when issuing a lot
106of commands due to many client/server exchanges.
107
108So, on a newly created layer, the ``INSERT`` of
109:cpp:func:`OGRFeature::CreateFeature` operations are grouped together in chunks
110until they reach 15 MB (can be changed with the CARTO_MAX_CHUNK_SIZE
111configuration option, with a value in MB), at which point they are transferred
112to the server. By setting CARTO_MAX_CHUNK_SIZE to 0, immediate transfer occurs.
113
114.. warning::
115
116    Don't use :cpp:func:`OGRDataSource::DeleteLayer` and
117    :cpp:func:`OGRDataSource::CreateLayer` to overwrite a table. Instead only
118    call :cpp:func:`OGRDataSource::CreateLayer` with OVERWRITE=YES. This will
119    avoid CARTO deleting maps that depend on this table
120
121SQL
122---
123
124SQL commands provided to the :cpp:func:`OGRDataSource::ExecuteSQL` call
125are executed on the server side, unless the OGRSQL dialect is specified.
126You can use the full power of PostgreSQL + PostGIS SQL capabilities.
127
128Open options
129------------
130
131The following open options are available:
132
133-  **BATCH_INSERT**\ =YES/NO: Whether to group feature insertions in a
134   batch. Defaults to YES. Only apply in creation or update mode.
135-  **COPY_MODE**\ =YES/NO: Using COPY for insertions and reads can
136   result in a performance improvement. Defaults to YES.
137
138Layer creation options
139----------------------
140
141The following layer creation options are available:
142
143-  **OVERWRITE**\ =YES/NO: Whether to overwrite an existing table with
144   the layer name to be created. Defaults to NO.
145-  **GEOMETRY_NULLABLE**\ =YES/NO: Whether the values of the geometry
146   column can be NULL. Defaults to YES.
147-  **CARTODBFY**\ =YES/NO: Whether the created layer should be
148   "Cartodbifi'ed" (i.e. registered in dashboard). Defaults to YES.
149   Requires:
150
151   -  **SRS**: Output SRS must be EPSG:4326. You can use ``-a_srs`` or
152      ``-t_srs`` to assign or transform to 4326 before importing.
153   -  **Geometry type**: Must be different than NONE. You can set to
154      something generic with ``-nlt GEOMETRY``.
155
156-  **LAUNDER**\ =YES/NO: This may be "YES" to force new fields created
157   on this layer to have their field names "laundered" into a form more
158   compatible with PostgreSQL. This converts to lower case and converts
159   some special characters like "-" and "#" to "_". If "NO" exact names
160   are preserved. The default value is "YES". If enabled the table
161   (layer) name will also be laundered.
162
163Examples
164--------
165
166Accessing data from a public table:
167
168.. code-block::
169
170    ogrinfo -ro "Carto:gdalautotest2 tables=tm_world_borders_simpl_0_3"
171
172Creating and populating a table from a shapefile:
173
174.. code-block::
175
176    ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" myshapefile.shp
177
178Creating and populating a table from a CSV containing geometries on EPSG:4326:
179
180.. code-block::
181
182    ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" file.csv -a_srs 4326 -nlt GEOMETRY
183
184.. note::
185
186    The ``-a_srs`` and ``-nlt`` must be provided to CARTODBFY
187    since the information isn't extracted from the CSV.
188
189See Also
190--------
191
192-  `Carto API overview <https://carto.com/docs/>`__
193