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）。特に、郵便番号のように文字列のままにする必要がある、数値に見える列で重要です。
• インポート／エクスポートは API レベルで非同期です。 MCP の import_data／export_data はジョブ ID を返します。method: "status" でポーリングしてください。CLI はデフォルトで完了までポーリングします。ジョブ ID をすぐに返すには --async を渡してください。
• タイルセットは、インポート → タイルセットテーブルを実体化（execute_async_query または carto sql job）→ マップでタイルセットを参照、という順序で作成します。タイルセットはウェアハウスに作成され、データ移動ツール自体が作成するものではありません。