carto-import-export-data

carto-import-export-data

Move data into the warehouse from local files / URLs, pull data out, transfer tables between connections, and prepare tilesets for performant rendering of large geospatial datasets.

Access-path routing. With the CARTO MCP server attached (OAuth session), route interactive moves through import_data, export_data, and transfer_data (each method: submit|status), and materialize tilesets with execute_async_query. Fall back to the carto import / carto sql job CLI for scripted/bulk loads, headless pipelines, or when the server isn't attached — and note that over a token-authenticated MCP session the import/export/transfer tools are hidden (read/discovery subset only), so authoring moves there go via the CLI too. carto activity export (usage data → local disk) is CLI-only, no MCP equivalent. Format, size-limit, and destination-syntax guidance below applies on every path. Detection signals: `carto-basics/references/access-paths.md`.

When to use this skill

• The user has a CSV / GeoJSON / Shapefile / GeoParquet file and wants it queryable in the warehouse.
• The user wants to refresh an existing table from a remote URL, or copy a table between connections.
• The user wants to render a 10M+-row spatial dataset on a map (needs tileset preparation).
• The user is bulk-exporting CARTO activity data to disk for offline analysis.

To query a file already in the warehouse, jump to `carto-query-datawarehouse`. To discover what's already there, `carto-explore-datawarehouse`.

Quick reference

MCP (OAuth session) — submit then poll:

import_data   { method: "submit", source: {url|file}, connection, destination, overwrite? }
export_data   { method: "submit", ... }   → status with the returned job id
transfer_data { method: "submit", source_connection, destination_connection, ... }

CLI fallback (scripted / headless / no server / token session):

# Import a local file (or --url for a remote source; --async to poll separately; --overwrite to replace)
carto import --file ./data.csv --connection carto_dw --destination project.dataset.table

What's in this skill

Always-on guidance

• `--connection` / `connection` is the connection name*** (discover it with explore_data method: list_connections, or carto connections list --json), not the warehouse project ID.
• `destination` is the fully-qualified target name in the warehouse's syntax: project.dataset.table (BigQuery), DATABASE.SCHEMA.TABLE (Snowflake), schema.table (Postgres/Redshift), catalog.schema.table (Databricks), SCHEMA.TABLE (Oracle).
• 1 GB hard limit per file (CARTO-side, not a warehouse limit). For larger files, pre-stage to cloud storage and import from a presigned URL.
• Disable autoguessing (--no-autoguessing on the CLI) when you've prepared a precise schema and don't want CARTO to second-guess types — especially numeric-looking columns that should stay string, like ZIP codes.
• Imports/exports are async at the API level. MCP import_data/export_data return a job id — poll with method: "status". The CLI polls to completion by default; pass --async to return immediately with a job id.
• Tilesets follow import → materialize tileset table (`execute_async_query` or `carto sql job`) → reference the tileset in a map. The tileset is created in the warehouse, not by the mover itself.