carto-import-export-data

carto-import-export-data

从本地文件／URL 将数据导入数据仓库、导出数据、在连接之间传输表，并为大型地理空间数据集准备瓦片集，以实现高性能渲染。

访问路径路由。 连接 CARTO MCP 服务（OAuth 会话）后，交互式数据移动应通过 import_data、export_data 和 transfer_data 进行（每个工具都支持 method: submit|status），并通过 execute_async_query 实例化瓦片集。对于脚本化／批量加载、无头流水线，或未连接服务时，改用 carto import／carto sql job CLI。请注意，在令牌认证的 MCP 会话中，导入／导出／传输工具会被隐藏（仅提供读取／发现功能），因此这类会话中的数据写入也应通过 CLI 进行。carto activity export（将用量数据导出到本地磁盘）仅支持 CLI，没有对应的 MCP 功能。以下格式、大小限制和目标语法说明适用于所有路径。检测信号：carto-basics/references/access-paths.md。

何时使用此技能

• 用户有 CSV／GeoJSON／Shapefile／GeoParquet 文件，并希望能在数据仓库中查询。
• 用户希望通过远程 URL 刷新现有表，或在连接之间复制表。
• 用户希望在地图上渲染一个包含 1,000 万行以上的空间数据集（需要准备瓦片集）。
• 用户要将 CARTO 活动数据批量导出到磁盘，以便离线分析。

要查询数据仓库中已有的文件，请跳转到 carto-query-datawarehouse。要发现其中已有的数据，请参阅 carto-explore-datawarehouse。

快速参考

MCP（OAuth 会话）——提交后轮询：

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 回退方案（脚本化／无头／未连接服务／令牌会话）：

# 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

此技能包含的内容

主题	参考
导入——import_data／carto import 标志、格式、大小限制、异步操作	references/imports.md
为大型地图准备瓦片集	references/tilesets.md
导出与传输：数据仓库原生卸载、export_data／transfer_data、activity export	references/exports.md

始终适用的指南

• --connection／connection 指连接的名称（通过 explore_data method: list_connections 或 carto connections list --json 发现），不是数据仓库的项目 ID。
• destination 是符合数据仓库语法的完整目标名称：project.dataset.table（BigQuery）、DATABASE.SCHEMA.TABLE（Snowflake）、schema.table（Postgres/Redshift）、catalog.schema.table（Databricks）、SCHEMA.TABLE（Oracle）。
• 每个文件的硬性上限为 1 GB（由 CARTO 端限制，并非数据仓库的限制）。对于更大的文件，请先将文件暂存到云存储，再从预签名 URL 导入。
• 如果已准备好精确的架构且不希望 CARTO 再次猜测类型，请禁用自动猜测（CLI 使用 --no-autoguessing）——尤其是对于外观像数字、实际应保留为字符串的列，例如 ZIP 代码。
• 导入／导出在 API 层面是异步的。 MCP 的 import_data／export_data 会返回任务 ID——使用 method: "status" 轮询。CLI 默认会轮询直至完成；传入 --async 可立即返回任务 ID。
• 瓦片集的流程为导入 → 实例化瓦片集表（execute_async_query 或 carto sql job）→ 在地图中引用瓦片集。瓦片集是在数据仓库中创建的，并非由数据移动工具本身创建。