EVOLUTION-MANAGER
Edit File: drv_carto.html
<html> <head> <title>Carto</title> </head> <body bgcolor="#ffffff"> <h1>Carto</h1> (GDAL/OGR >= 1.11)<p> 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.<p> The driver supports read and write operations.<p> <h2>Dataset name syntax</h2> The minimal syntax to open a Carto datasource is : <pre>Carto:[connection_name]</pre><p> 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 :<p> <ul> <li> <b>tables=table_name1[,table_name2]*</b>: A list of table names. This is necessary when you need to access to public tables for example. </ul> If several parameters are specified, they must be separated by a space.<p> <h2>Configuration options</h2> The following configuration options are available : <ul> <li>CARTO_API_URL: defaults to https://[account_name].carto.com/api/v2/sql. Can be used to point to another server.</li> <li>CARTO_HTTPS: can be set to NO to use http:// protocol instead of https:// (only if CARTO_API_URL is not defined).</li> <li>CARTO_API_KEY: see following paragraph.</li> </ul> <h2>Authentication</h2> Most operations, in particular write operations, require an authenticated access. The only exception is read-only access to public tables.<p> 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.<p> <h2>Geometry</h2> The OGR driver will report as many geometry fields as available in the layer (except the 'the_geom_webmercator' field), following RFC 41. <h2>Filtering</h2> The driver will forward any spatial filter set with SetSpatialFilter() to the server. It also makes the same for attribute filters set with SetAttributeFilter().<p> <h2>Paging</h2> Features are retrieved from the server by chunks of 500 by default. This number can be altered with the CARTO_PAGE_SIZE configuration option.<p> <h2>Write support</h2> Table creation and deletion is possible.<p> Write support is only enabled when the datasource is opened in update mode.<p> The mapping between the operations of the Carto service and the OGR concepts is the following : <ul> <li>OGRFeature::CreateFeature() <==> INSERT operation</li> <li>OGRFeature::SetFeature() <==> UPDATE operation</li> <li>OGRFeature::DeleteFeature() <==> DELETE operation</li> <li>OGRDataSource::CreateLayer() <==> CREATE TABLE operation</li> <li>OGRDataSource::DeleteLayer() <==> DROP TABLE operation</li> </ul> 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.<p> 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.<p> 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 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.<p> <h2>SQL</h2> 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.<p> <h2>Open options</h2> <p>Starting with GDAL 2.0, the following open options are available:</p> <ul> <li><b>BATCH_INSERT</b>=YES/NO: Whether to group feature insertions in a batch. Defaults to YES. Only apply in creation or update mode.</li> </ul> <h2>Layer creation options</h2> <p>The following layer creation options are available:</p> <ul> <li><b>OVERWRITE</b>=YES/NO: Whether to overwrite an existing table with the layer name to be created. Defaults to NO.</li> <li><b>GEOMETRY_NULLABLE</b>=YES/NO: Whether the values of the geometry column can be NULL. Defaults to YES.</li> <li><b>CARTODBFY</b>=YES/NO: Whether the created layer should be "Cartodbifi'ed" (i.e. registered in dashboard). Defaults to YES.</li> <li> <b>LAUNDER</b>=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.</li> </ul> <h2>Examples</h2> <li> Acceccing data from a public table: <pre> ogrinfo -ro "Carto:gdalautotest2 tables=tm_world_borders_simpl_0_3" </pre> <p> <li> Creating and populating a table from a shapefile: <pre> ogr2ogr --config CARTO_API_KEY abcdefghijklmnopqrstuvw -f Carto "Carto:myaccount" myshapefile.shp </pre> <p> <h2>See Also</h2> <ul> <li> <a href="https://carto.com/docs/">Carto API overview</a><p> </ul> </body> </html>