carto-create-builder-maps

carto-create-builder-maps

CARTO Builder は、JSON マップ設定からインタラクティブなマップをレンダリングするマッピングツールです。このスキルでは、自然言語からの作成、データセット／レイヤー／ウィジェット／ポップアップ／プライバシーの編集、共有ビューアー向けのスナップショットの公開、オフラインでの検証、マップ群の運用まで、作成の全ライフサイクルを扱います。また、プロファイルをまたいだコピー（dev → prod の昇格、carto maps copy による顧客ごとに分離された組織への配信）も扱います。詳しくは、以下の 組織間で昇格／コピーする のリファレンスを参照してください。

アクセス経路の振り分け。 以下のフェーズ、カートグラフィックのルール、設定ガイダンスはアクセス経路に依存しません。どちらの経路でも、作成する JSON は同じです。異なるのはトランスポートだけです。

操作	MCP（接続済みの場合はこちらを優先、OAuth）	CLI
マップの一覧表示／取得／検索	read_maps (list | get)	carto maps list / get
作成／編集／公開	create_map, update_map (update | update_dataset | publish)	carto maps create / update / publish / datasets update
オフライン検証	validate_map	carto maps validate
削除	delete (kind=map)	carto maps delete
インラインプレビュー（MCP-Apps ホストのみ）	view_map (mapId) — carto-preview-builder-map を参照	—（CLI ではインライン表示できません。PNG には screenshot を使用してください）
データセットの調査	explore_data (describe)	carto connections describe
SQL プローブ	execute_query	carto sql query
ファイルの事前インポート	import_data (submit | status)	carto import

CLI 専用 — MCP に相当する機能はありません： carto maps schema（フィールド／列挙値／パレットのカタログ）、carto maps agents *（AI サーフェス）、carto maps screenshot（PNG レンダリング）、carto maps copy（プロファイルをまたいだ昇格、および同一組織内での複製）。これらの操作や、スクリプト／一括作成を行う場合、またサーバーが接続されていない場合は CLI を使用してください。

トークンと OAuth。 API トークン経由では、MCP セッションで公開されるのは読み取り／検出機能の一部のみです（validate_map、view_map、explore_data、execute_query は引き続き利用できますが、create_map / update_map / delete は非表示になります）。CLI で作成するか、OAuth で再接続してください。サンドボックス化されたチャットホスト（Claude.ai、ChatGPT）では CLI を実行できないため、MCP のみがライブアクセス経路となります。判別の手がかりについては、carto-basics/references/access-paths.md を参照してください。

アドホックな空間 SQL の調査には、carto-query-datawarehouse を使用してください。

フィールドの形式、列挙値、パレットのカタログ、AI ツールのカタログは、carto maps schema [section]（Tier-1 検証で使用されるものと同じ Zod 定義から生成された JSON Schema）、carto maps agents models / mcp-tools / core-tools（AI サーフェス）、および explore_data describe / carto connections describe <conn> <table>（データセットのメタデータ）で提供されます。値をハードコードしたり、推測したりしないでください。 このドキュメントと CLI／スキーマの内容が異なる場合は、スキーマを優先してください。

参考資料

判断・方針 — 最初にお読みください

• references/cartography.md — スタイリングより先に行う地図表現の判断：配色ファミリー、尺度の種類、ベースマップの組み合わせ、複数レイヤー間の色相の分離、アンチパターン。スタイリングの判断が必要な場合は、JSON の作成前に必ずお読みください。
• references/configuration-shape.md — 注釈付きの JSON スケルトン。keplerMapConfig のトップレベル構造、datasets[] エントリー（table／query／tileset／raster）、mapSettings のルールを説明します。
• references/examples.md — 実際の組織環境で検証済みのテンプレート：最小構成の地図、H3 集計、SQL パラメーター、ウィジェットギャラリー。JSON テンプレートをベースに作成する場合に読み込んでください。

コンポーネント別 — 作成中に必要に応じて参照

• references/layers.md — レイヤータイプ別の作成方法：tileset（point／line／polygon／3D）、h3、quadbin、heatmapTile、clusterTile、raster。色の範囲（パレット／尺度／/stats）、線のスタイル（lineStyle の solid／dashed／dotted）、ポリゴンの塗りつぶしパターン（fillPatternEnabled + fillPattern）、ベースマップを考慮したコントラストも扱います。
• references/widgets.md — 分析画面：formula、category、pie、histogram、range、timeseries、table。並び順、折りたたみ可能かどうかのデフォルト、データセット間のクロスフィルタリングについて説明します。
• references/popups.md — popupSettings が扱う 2 つの操作画面：ツールチップポップアップ（ホバー／クリック）と情報パネル（ドッキングされたサイドパネル、クリックのみ）。ホバー時のフィールド上限は 5 つ、インライン CSS を使ったカスタム HTML テンプレート、レンダラーがサニタイズする内容を説明します。
• references/sql-parameters.md — Category、DateRange、Numeric、NumericRange。{{paramName}} プレースホルダーの記述方法と、プロバイダー固有の方言への変換について説明します。
• references/basemap.md — basemapConfig.styleId と mapStyle.styleType の両方に同じ値を設定してください（スクリーンショットエンジンとビューアーの SSR は現在も mapStyle を読み取ります）。CARTO ベースマップ／Google Maps／カスタムベースマップカタログについて説明します。
• references/agent-config.md — 地図上のエージェント（オプトイン）。組織のステータス確認、モデル選択、MCP／コアツールカタログ、機能に応じた有効化について説明します。

運用・問題解決

• references/updates.md — CRUD のライフサイクル：レシピ、keplerMapConfig の部分更新と全置換のルール（最も多い破壊的なミス）、--datasets-mode、公開処理の連鎖、検証手段。
• references/troubleshooting.md — 症状 → 対処法の表、出力を避けるべきアンチパターン、行き詰まった場合の回避策、carto maps screenshot による視覚的な検証。

組織間で昇格・コピー — プロファイル間で地図を移行する場合にお読みください

• references/cross-profile-copy.md — maps copy の仕組み、接続のマッピング（--connection-mapping／--connection）、--skip-source-validation、移行されるものとされないもの。
• references/agent-migration-caveats.md — AI エージェントを含む地図のコピー後に発生する UNAVAILABLE_MODEL／UNAVAILABLE_TOOL の問題、CLI で自動修正できない理由、Builder での手動手順。
• references/post-copy-validation.md — 移行先の地図が正しく表示されることの確認：データセット、接続、エージェントの問題、移行先 URL の構築。

---

作成プロセス

すべての「地図を作成する」リクエストで、以下のフェーズを順番に実行してください。フェーズを省略することは、「地図が Builder で正しく表示されない」 最も一般的な原因です。具体的には carto … コマンドを示しています。MCP サーバーが接続されている場合は、上記のルーティングテーブルにある同等のツール（create_map／update_map／validate_map／read_maps、explore_data、execute_query、import_data）を使用してください。JSON ペイロードは同じです。

フェーズ 1 — コンテキストの収集（インテークゲート）

このフェーズは提案ではなく、必須のゲートです。ただし、順序が重要です。何を質問できるかを制約する唯一の事実は、データです。テーブルの内容を把握する前に、抽象的な希望（対象者、モード、ウィジェット、共有）をユーザーに尋ねると、当てはまらないことの多い一般的な質問になり、希望を列に対応付けるというエージェントの仕事をユーザーに押し付けてしまいます。

順序

1. 目的 — 1 行で。 「このマップは何についてのもので、何を伝えるものですか？」 回答を得るまで先に進まないでください。X が具体的なら、*「X のマップを作って」*で構いません。

2. データの手掛かり — 1 行で。 「データはどこにありますか。すでにあるテーブル、デモデータセット、インポートするファイルのいずれですか？」 次に進む前に、具体的なテーブル FQN を特定してください。デモデータの場合は、トピックに基づいて carto-demo-data.demo_tables を検索します。ファイルの場合は、まず import_data（MCP）／carto import（CLI）を実行します。

3. データを静かに調査します。 ほかの質問をする前に、次を実行します。

   • explore_data describe／carto connections describe <conn> <table> → スキーマ、行数、ジオメトリタイプ（point／line／polygon／h3／quadbin／raster）。
   • colorField の候補列の NULL 比率、目的に関連する数値列の min/max/p50/p95/p99、カーディナリティの落とし穴を検出するためのカテゴリ列候補の COUNT(DISTINCT ...)、時間列の日付範囲を調べるため、execute_query／carto sql query を実行します。
   • 調査はクエリ 1〜2 件までに制限します。 すべての列を監査しないでください。ユーザーの目的に関連する項目を調査します。

4. 質問は、ここで初めてデータに基づいて行います。 データから答えられることだけを尋ねます。データに基づく良い質問と、抽象的すぎる悪い質問の例は次のとおりです。

   悪い例（抽象的で、早すぎる質問）	良い例（調査後の、データに基づく質問）
   「ウィジェットは必要ですか？」	「capacity_repd_mwp（合計約 13 GW）と repd_status（5 カテゴリ）があるようです。容量の合計とステータスの内訳を表示するウィジェットを作りますか？」
   「分析用ですか、それとも地図表現用ですか？」	「このテーブルには運用開始日、面積、容量など 23 列があります。分析向けのマップが適していそうです。容量のヒストグラムを提案しますが、シンプルなままにしますか？」
   「公開しますか、それとも非公開にしますか？」	（共有はデータとは別の話題です。必要なときに簡潔に尋ねてください。最初のやり取りでは決して尋ねないでください）
   「どのパレットにしますか？」	「設備が 26.5 万件あるため、ポイントが大きく重なります。透明度を低くして単色にするか、容量で色分けする（ロングテール分布なので対数スケール）か、どちらを提案しましょうか？」

   データから質問への答えが自明なら、尋ねずに判断します。

   • ジオメトリタイプ → レイヤータイプを非表示で決定します。polygon／line／point → tileset、インデックス済みの h3／quadbin → それぞれ h3／quadbin を直接使用、raster → raster。
   • ビューポート → データのバウンディングボックスを使用します。
   • colorField の候補列の NULL 比率が 25% を超える場合 → 列を切り替えるか、WHERE col IS NOT NULL でフィルターします。これは非表示で行います。cartography.md §4.5a を参照してください。

5. 共有／対象者／エージェント — 該当する場合のみ尋ねます。 最初のマップのレンダリングをこれらの確認で止めないでください。デフォルトは private です。ユーザーが*「チームと共有して」、「CEO に送って」、「AI エージェントを追加して」*と言ったときに確認します。

技術的な前提条件（非表示 — 問題がある場合を除き、ユーザーには伝えないでください）

• アクセスの準備ができていること。 MCP では、マップツールがツール一覧にあることを確認します（validate_map／view_map しか表示されない場合、セッションはトークン認証済みです。CLI で作成するか、OAuth で再接続してください）。CLI では carto auth status を実行し、未認証の場合は carto auth login --no-launch-browser を使用して停止します。carto-basics/references/access-paths.md を参照してください。
• 組織の AI ステータス（ユーザーがマップ上の Agent に言及した場合のみ）。carto maps agents status（CLI のみ）を実行します。enabled: false の場合はエージェントの計画を取り下げ、その旨をユーザーに伝えます。

時間の目安

初版の目標：約30秒の実時間で、ユーザーの「開始」から動作する URL を作成します。入力が目標とデータのヒントだけで、エージェントが黙って調査する場合に実現できます。最初のマップも見栄えよく仕上げる必要があります。最初の出力から、cartography.md のカートグラフィーのデフォルト（パレットファミリー、スケール、ベースマップの組み合わせ、複数レイヤーの色相の分離）を適用します。調整（カスタムドメイン、パレットの入れ替え、ウィジェットの調整）は、ユーザーが結果を見ている状態で、後続のターンに行います。

フェーズ 2 — カートグラフィー上の判断を行う

スタイル設定が対象となる場合は、JSON を書く前に references/cartography.md を読みます。出力する前に、次の項目を明確に選択します。

• レイヤータイプ：データの特性に応じて選択します（point / line / polygon / h3 / quadbin / heatmap / cluster / raster）。
• パレットファミリー（qualitative / sequential / diverging）：反射的に選ぶのではなく、伝えたい内容とベースマップに基づいて選びます。
• スケールタイプ：データの形状と意味の両方に基づいて選びます。デフォルトの選択基準：意味上の基準点がある有界データ（0～100 のスコア、%、比率）→ 自然な範囲に合わせた明示的な colorDomain を指定して quantize、桁をまたぐヘビーテールデータ → custom と uiCustomScaleType: "logarithmic"、値に上限がなく偏りがあり、閲覧者が大きさではなく順位を重視するデータ → quantile（これが本来の用途であり、安全策としてデフォルトで使うものではありません）、カテゴリのように見える整数 → STRING にキャストして ordinal。references/cartography.md §3.2 を参照してください。quantile はあらゆる場合に使える安全なデフォルトではありません。ENERGY STAR、年齢、% などの有界スケールに反射的に選ぶのが、スケール選択で最もよくある誤りです。
• ベースマップ（デフォルトの明るい positron / dark-matter / voyager / Google の各バリアント / カスタム）。
• 複数レイヤーの色相の分離：レイヤーが複数ある場合は、1つのグラデーションの濃淡ではなく、レイヤーごとにパレットファミリーを選びます。

構造上の作業のみ（名前の変更、データセットの差し替え、プライバシーの変更、エージェント設定の編集、mapSettings の調整）の場合に限り、事前のカートグラフィー検討を省略します。

フェーズ 3 — 設定を構成する

基本構造は references/configuration-shape.md を参照してください。以下を設定します。

• datasets[] — 接続、ソース、geoColumn、type、format。h3 / quadbin レイヤーについては、ソース選択の判断基準（動的ビニングと事前構築済みタイルセット）を参照してください。
• keplerMapConfig.config.visState.layers[] — type + visualChannels + visConfig（layers.md を参照してください）。
• 分析を行う場合は keplerMapConfig.config.widgets[]（widgets.md を参照してください）。
• 地物を識別するデータセットでは、デフォルトで keplerMapConfig.config.popupSettings.layers を出力します（popups.md を参照してください）。
• フィルタリング可能な場合は keplerMapConfig.config.sqlParameters[]（sql-parameters.md を参照してください）。
• keplerMapConfig.config.basemapConfig + mapStyle — 同じ値を両方に設定します（basemap.md を参照してください）。
• agent ブロックは、ユーザーが明示的に要求し、かつ組織の AI が有効な場合に限ります（agent-config.md を参照してください）。

フェーズ 4 — オフラインで検証する

validate_map（MCP）/ carto maps validate map.json（CLI）。Tier 1 では、構造、型、列挙値、相互参照、エージェントのフィールド、aggregationExp の整合性、プライバシーの強制変換、さらに十数個のフィールド間ルール（正規の visualChannels パス、カスタムマーカーの組み合わせ、ポップアップのホバー上限など）を、バックエンドを一切呼び出さずに検出します。エラーがなくなるまで繰り返します。

フェーズ 5 — 作成と検証

create_map（MCP）／carto maps create < map.json（CLI）。どちらも POST /maps の前に、Tier-1 と、データセットごとの SELECT … WHERE 1=0 によるソースのアクセス可能性プローブを実行するため、ソースに問題があっても孤立したマップは作成されません。このプローブでは、合成された _carto_* 列と、aggregationExp から解析した集計後のエイリアスを自動的に除外するため、正当な h3 ／ quadbin ／ heatmapTile ／ clusterTile の作成が誤って失敗することはありません。作成後は視覚的に検証します。MCP-Apps ホストでは view_map <id> でインラインプレビューを表示し、シェルでは carto maps screenshot <id> で PNG をレンダリングします。判断基準については、常時適用されるルール「"Visual verification"」を参照してください。

フェーズ 6 — 公開（閲覧者に公開する準備ができたら）

作成すると、非公開の下書きが作成されます。マップをユーザーの想定する対象者に表示するには、次の操作を行います。

• privacy を設定します（shared と、任意の sharingScope: "organization"、または sharingScope: "specific" + userIds ／ groupIds、あるいは public）。
• 共有／公開の閲覧者向けにスナップショットを固定するには、公開します。update_map（method=publish）／carto maps publish <id>、または編集と公開を連続して行う carto maps update <id> --publish を使用します。

公開が成功したら、ユーザーに 「閲覧者に公開されました」 と伝えます。そうでない場合は、編集内容がユーザー本人にしか表示されないことを明確に伝えてください。

---

常時適用されるルール

これらのルールは、作成フローだけでなく、すべてのタスクに適用されます。

目的から始める — 裏側の処理は見せない

フェーズ 1 の聞き取り質問（および以降のすべてのやり取り）では、平易な言葉を使ってください。最初のやり取りで dataId、geoColumn、tilejson、keplerMapConfig、connectionId、FQN の構文、レイヤータイプの分類を持ち出さないでください。仕様を並べ立てているように見え、ユーザーにあなたの仕事をさせることになります。質問はすべて、ユーザーにとってなじみのある表現にしてください。「どんなマップにしたいですか」、「誰が見る予定ですか」、「閲覧者が絞り込みできるようにしますか」、「どのように共有しますか」。JSON への変換は内部で行い、ユーザーに頼まないでください。

内部で処理し、質問しない

• アクセス — 最初に API にアクセスするコマンドを実行する前に、MCP map ツールが存在することを確認します（または CLI で carto auth status を実行します）。
• 接続 UUID + FQN の構文 — ユーザーがテーブル名を指定したら、explore_data（list_connections / describe）または carto connections list / describe を使って解決します。ユーザーに project.dataset.table を手入力するよう求めないでください。
• インポート — ユーザーがテーブルではなくファイルを持っている場合 — ユーザーが地理空間ファイル（CSV / GeoJSON / GeoPackage / GeoParquet / KML / KMZ / Shapefile-zip、≤ 1GB）のパス / URL を提示した場合、まず import_data（MCP）/ carto import --file <path>（または --url <url>）--connection <name> --destination <fqn>（CLI）を使ってデータウェアハウスのテーブルとして取り込み、その後、取り込んだテーブルを使ってマップを作成します。デフォルトでは、接続を選び（ユーザーのプライマリ CARTO Data Warehouse があれば優先します）、ファイルのベース名を反映した適切な宛先 FQN を選びます。デフォルトでは完了まで待機し、複数 GB の読み込みに限りバックグラウンドで実行します（--async / import_data のステータスポーリング）。ユーザーにフォーマット変換を求めないでください。インポーターは 7 種類すべてに対応しています。
• レイヤータイプ — データセットの形状から推測します。
  • ライン / ポリゴンのソース → tileset。
  • ポイントソースで、疎なデータ / フィーチャーレベル（この店舗を見つける、クリックしてズーム） → tileset。
  • ポイントソースで密度が高い / 大規模な場合（一般的な集計ケース）→ h3 または quadbin に集計（h3 = 六角形の見た目、quadbin = 正方形 + ズームに応じて変化するセルサイズ）。大規模なポイントテーブルに対する「X はどこに集中しているか」/「Y の密度」の質問では、これを適切なデフォルトとします。定量的な読み取りができ、ビューポート間で比較可能で、行ごとの描画予算を圧迫しません。
  • 事前にインデックス化された h3 / quadbin ソース → そのまま h3 / quadbin。データセットには引き続き aggregationExp を設定します。免除されるのは dataset.type: "tileset" のみであり、事前にインデックス化された table / query は対象外です。configuration-shape.md の 「Spatial indexes (H3, quadbin)」 を参照してください。
  • バンド格納されたラスター → raster。
  • heatmapTile と clusterTile は暗黙のデフォルトではありません — ユーザーが明示的に 「ヒートマップ」 / 「クラスタリングされたポイント」 を求めた場合、または数値なしのパターン表示（heatmapTile）、もしくは個々のポイントにズームできる数値付きバブル（clusterTile）を特に意図している場合にのみ選択します。データが密なポイントである場合、それ以外はすべて h3 / quadbin への集計をデフォルトとします。ヒートマップは定量的な読み取りをぼかし、クラスタはバブルの件数に変えてしまう一方、これらは定量的な読み取りを保ちます。 フィーチャーレベル（tileset）と集約（h3 / quadbin）のどちらを選ぶかが本当に曖昧な場合に限り、ユーザーに確認してください。たとえば、「個々の店舗の所在地ですか、それとも市内全体の密度ですか？」のような場合です。
• ビューポート — データのバウンディングボックスを中心にします（CLI は作成時にこれを計算します）。緯度・経度・ズームを尋ねないでください。
• 凡例とカテゴリドメイン — CLI が /stats を取得し、凡例を自動的に設定します。
• colorField のデータ形状の確認 — 数値列を colorField（または sizeField / radiusField / heightField）にバインドする前に、1 行の execute_query / carto sql query によるプローブで NULL の割合を確認してください（SELECT COUNT(*), COUNT(col) FROM source）。行の 25% を超える値が NULL の場合、描画時にマップの大部分がグレーになります。これはカテゴリカーディナリティの落とし穴と同種の問題です。対処方法は 2 つあります（ユーザーに確認する必要はありません）。ソース SQL に WHERE col IS NOT NULL を追加してフィルタリングするか、より多くの値が入っている列を選びます。具体例は references/cartography.md §4.5a を参照してください。既存マップの再編集時（ユーザーがすでに列を選択しています）や、小規模なデータセット（1k 行未満。問題が目に見える形では現れません）では、プローブを省略してください。
• ポップアップ — データセットにフィーチャーを識別する列（name / id / address / owner / timestamp）がある場合は、デフォルトで出力します。 エンドユーザーはソーステーブルを参照できません。ポップアップ（または次善策としての table ウィジェット）が、フィーチャーごとの属性を確認できる唯一の方法です。ポップアップもテーブルウィジェットもないマップでは、ユーザーに色と位置しか表示されず、フィーチャーに関するそれ以外の情報はすべて見えません。識別用の列を 2～4 個使ってホバーを追加し、残りの列をクリック時に表示します。純粋なパターンマップ（ヒートマップ、密度を示す h3/quadbin。参照対象がフィーチャーごとではなく集約データ）の場合に限り、省略してください。
• ウィジェット — 分析用マップではデフォルトで提案します。数は固定ではなく、ユースケースに応じて決めます。
  • 純粋な地図表現のマップ：ウィジェット 0 個。
  • 業務用／「このフィーチャーを見つける」マップ：1～2 個（主に table）。
  • 探索的な分析用マップ：3～6 個（数式 + カテゴリ／円グラフ + ヒストグラム + 時系列 + 範囲 + テーブル）。
  • ダッシュボードマップ：6～8 個。約 8 個を超えるとパネルが混み合います。
• SQL パラメーター — ソースに自然なフィルター軸（日付範囲、地域、カテゴリ）がある場合は提案します。 {{paramName}} プレースホルダーと sqlParameters[] エントリーを設定し、mapSettings.sqlParameterControls: true を指定します。ソースが静的な場合は省略してください。
• 説明 — 閲覧者向けの Markdown です（任意）。 説明が空、または省略されている場合、閲覧者には表示されません（説明が空だと右側の情報ボタンも非表示になります）。参照用マップや、伝えるべき内容がないマップでは、空のままでかまいません。説明を出力する場合は、内容を充実させてください。右側のレールには十分な縦方向のスペースがあり、よく作り込まれた説明はマップの小さなランディングページのようになります。完全なテンプレート（任意のヒーロー画像 → ## Title → リード段落 → 任意の ### Context、### What you are looking at、### Things to try）、テーブルを使わないルール／### Source を使わないルール、および具体例としての NYC PLUTO の例については、references/cartography.md §6.4 を参照してください。作成者向けのメモ、エージェントの推論、変更履歴には使わないでください。説明を出力しない場合は description: ""（空文字列。決して null にしないでください。null だとプレースホルダーが表示されます）を設定します。maps create は "" を自動設定しますが、maps update ではクリアするために明示的な "" が必要です。

オプトインブロック — ユーザーから明示的に依頼された場合にのみ出力

先回りして提案しないでください。また、ユーザーが明らかに選択肢を検討している場合を除き、「ほかにできることは？」の選択肢にも含めないでください。

ブロック	出力する場合…
agent	ユーザーがマップに Agent を追加するよう依頼した場合。まず carto maps agents status を実行し、無効なら省略します。
privacy（非プライベート）	ユーザーが共有を依頼した場合。デフォルトでは非公開のままにします。
tags / description	ユーザーが指定した場合、またはマップを外部に公開する場合。
collaborative	閲覧だけでなく、ほかの組織メンバーによる編集をユーザーが依頼した場合。
カスタムパレット / 3D / カスタムマーカー	ユーザーが特定のスタイルを指定した場合、またはデフォルトの表示が適切でない場合。

レイヤースタックの順序は逆 — layerGrouping が存在する場合はそちらが優先されます

visState.layers[0] が最前面に描画され、これは通常の deck.gl とは逆です。最前面にしたいジオメトリを先に記述してください。ポイントとラインをポリゴンより上に、ポリゴンを h3 / quadbin / heatmapTile / clusterTile のセルより上に、セルをラスターレイヤーより上に配置します。よくある失敗は、背景のポリゴンがその下のフィーチャーを覆い隠し、すべてのデータセットが正常に読み込まれているのに、地図が空に見えることです。

スタックを決める方法は、地図によって異なります。

• config.layerGrouping がある場合（Builder から保存したすべての地図にあります）：ツリーの順序が描画順序で、最初の項目が最前面です。visState.layers だけを並べ替えても、画面上では何も変わりません。ツリーにないレイヤーは最下部に追加されます。ツリーを並べ替え、新しいレイヤーの項目を適切な位置に挿入してください。
• layerGrouping がない場合（新しいバンドル）：visState.layers の順序が描画順序です。

ツリーと同じ順序で visState.layers を保持し、両方が同じ順序になるようにしてください。visState.layerOrder は出力しないでください。 Builder はこれをレイヤーの ID ではなくインデックスとして読み取り、ツリーがない場合に限って使用します。また、これが存在すると CLI の事前スタッキング警告が無効になります。この警告は特定のジオメトリの組み合わせしか認識せず、layerGrouping も確認しません。修正されるのを待つのではなく、適切な順序を記述してください。詳細なルールは references/layers.md（レイヤースタックの順序、最初のセクション）と references/cartography.md §1.8 を参照してください。

書き込む前に検証する

地図の設定を組み立てた後、API 呼び出しを行う前にオフラインで簡易チェックするには、carto maps validate <map.json> を実行してください。バックエンドを呼び出さずに、create と同じ Tier-1 チェックを実行します。繰り返し試行する場合や、JSON をユーザーに渡す場合に便利です。

書き込み後に Builder を再読み込みする

書き込みは、サーバーが変更を受け付けるとすぐに完了します。Builder は地図を一度だけインメモリーのクライアント状態に読み込み、サーバーイベントを購読しないため、開いたままの https://<org>/builder/<id> タブには、タブを再読み込みするまで古い状態が表示され続けます。リモート／外部エージェント（claude.ai の Claude、ChatGPT、MCP クライアントなど、ローカルのブラウザーにアクセスできないもの）の場合は、ユーザーに伝えてください。「地図を更新しました。変更を確認するには Builder のタブを再読み込みしてください（Cmd/Ctrl+R）。」

目視での検証 — 地図の形状に応じて判断します（質問する必要はありません）

実際に描画される内容を検証してください。Tier-1 チェックとソース／描画チェックでは、パレットのコントラスト、レイヤーによる隠れ、ラベルの衝突を検出できません。方法は2つあります。

• MCP-Apps ホスト（Claude.ai、Claude Desktop、ChatGPT）：view_map <id> を使うと、会話内で地図をインラインプレビューできます。シェルは不要です。ここではこちらを推奨します。
• シェル（コーディングハーネス）：carto maps screenshot <id> で PNG をレンダリングします。ユーザーが表示できるよう、インラインに埋め込んでください。light エンジン（デフォルト、約8秒、デッキレイヤーとベースマップのみ）と、full（--render-engine full、約20秒、ウィジェットと凡例を追加）があります。full フラグの詳細は references/troubleshooting.md を参照してください。

「スクリーンショットが必要ですか？」とは尋ねないでください。 — ユーザーは所要時間を判断できません。地図の形状に応じて判断し、実行してください。

検証する場合： エージェントが複雑な地図を作成したとき（レイヤーが3つ以上、カスタムパレット／マーカー、複雑なウィジェット、3D、カスタムベースマップ）、ユーザーから地図が空白または誤っていると報告されたとき、公開する前。省略する場合： メタデータのみの編集、検証済みの地図への限定的な調整、Builder のタブを開いた状態でユーザーが素早く反復作業をしているとき。

エンジンの選択（スクリーンショット）： 高速な確認には light を使用します。ウィジェットや凡例を検証する場合は full を使用してください（これらは light では描画されません）。ポップアップ（ホバー／クリック／情報パネル／カスタム HTML）はどちらのエンジンでも描画されません。スクリーンショットではなく、Builder で検証してください。

keplerMapConfig は部分マージではなく、全体置換です

更新時、最上位フィールドの多くは部分パッチを受け付けます。title、description、tags、collaborative、privacy、agent、datasets が該当します。keplerMapConfig は異なります。「部分更新」として {keplerMapConfig: {config: {basemapConfig: {...}}}} を送信すると、レイヤー、ウィジェット、sqlParameters、ビューポートが消去されます。keplerMapConfig 内の項目を変更するには、読み取り・変更・書き込みの手順を使います。設定全体を読み取り（read_maps get / carto maps get <id> --json）、編集してから、更新します（update_map / carto maps update <id>）。どちらの方法でも、消去を招く部分更新は事前チェックで拒否されます。マージの全パターンについては、updates.md を参照してください。

タイトルからマップ ID を作らないでください

ユーザーが UUID ではなく名前やタイトルでマップを指定した場合：

1. read_maps（ヒントで絞り込んで一覧表示）/ carto maps list --mine --search "<hint>" — ヒントに一致するユーザー自身のマップに絞り込みます。
2. 一致が 1 件 → その id を使い、書き込み前に確認します。
3. 一致が複数件 → ID とタイトルを一覧表示し、どれかを尋ねます。
4. 一致が 0 件 → 新しいマップを作成するつもりだったか尋ねます。

ユーザーの確認なしに一致したマップを選んで書き込んではいけません。また、タイトルだけから UUID を推測してはいけません。

ユーザーから求められた場合にのみ仕様を提示します

ユーザーが 「JSON を見せて」 / 「自分で書きます」 / 「スキーマは何ですか」 と言った場合は、carto maps schema と configuration-shape.md を開きます。それ以外の場合は、こちらの仕様ではなく、ユーザーのマップについて会話を続けます。

---

チートシート

作業はほとんどの場合、次の 3 つのパターンのいずれかです（MCP ツール / CLI コマンド）：

やりたいこと	実行する内容
自然言語のリクエストからマップを作成する（一般的な方法）	必要な入力を確認し（フェーズ 1）、それらだけを含む設定を出力する → create_map / carto maps create < map.json
既存のマップを編集する — データセットの追加、レイヤーのスタイル更新、プライバシーの変更、名前の変更、ベースマップの入れ替え	update_map / carto maps update <id> < partial.json（部分 PATCH。指定されていないフィールドは保持されます。ただし、keplerMapConfig は全体置換です）
既存のマップを複製する	設定を読み取り（read_maps get / carto maps get <id> --json）、編集して、新規作成します

レンダリング、ソース、エージェントのチェックは、作成・更新のたびに自動実行され、警告として表示されます。「レンダリングされるか検証する」手順を別途実行する必要はありません。

よく使うコマンド（CLI。MCP の同等コマンドは冒頭のルーティング表を参照）

carto maps list --mine                            # browse (MCP: read_maps list)
carto maps get <id> --json                         # read a config (MCP: read_maps get)
carto maps validate [map.json]                     # Tier-1 sanity check (MCP: validate_map)
carto maps create [map.json]                       # new map (MCP: create_map)
carto maps update <id> [patch.json] [--publish]    # partial update / publish (MCP: update_map)
carto maps publish <id>                            # freeze a snapshot (MCP: update_map method=publish)
carto maps schema [section]                        # JSON Schema reference (CLI-only)
carto maps agents status                           # is CARTO AI enabled? (CLI-only)
carto maps screenshot <id>                         # PNG render (CLI-only; MCP-Apps: view_map)

すぐ使えるレシピ

既存のマップを複製する — 動作するマップを作成する最も確実な方法です。元の設定はすでに Builder の形式になっているため、部分レイヤーの落とし穴は当てはまりません。

carto maps get <source-map-id> --json \
  | jq '.title = "My copy" | del(.id, .privacy)' \
  > new-map.json
carto maps create < new-map.json

タイトルのみを更新する（部分 PATCH）：

echo '{"title":"Better title"}' | carto maps update <map-id> --json

既存のマップにデータセットを 1 つ追加する（マージモードでは既存のデータセットが保持されます）：

carto maps get <map-id> --json > current.json
jq '.datasets += [{"$ref":"extra","type":"table","source":"proj.ds.new_table","connectionId":"<conn-id>","geoColumn":"geom","columns":["geom"],"format":"tilejson","label":"New source"}]' current.json > updated.json
carto maps update <map-id> --json < updated.json

すべてのデータセットを置き換える（破壊的操作。入力にないデータセットは削除されます）：

carto maps update <map-id> --datasets-mode replace --json < map.json

1 つのデータセットのソース SQL のみを更新する（keplerMapConfig が消去されるリスクはありません）：

carto maps datasets update <map-id> <dataset-id> --source "SELECT geom, revenue FROM stores WHERE country = 'ES'"

より詳しいレシピ（完全な JSON バンドル）については、references/examples.md を参照してください。

---

判断に迷った場合

• フィールドが不明、または正しいか疑わしい場合：carto maps schema [section] を実行すると、信頼できる JSON Schema が返されます（CLI 専用）。
• マップが何も表示されない、または表示が誤っている場合：references/troubleshooting.md の症状→解決策の表を参照してください。
• 見た目を確認する場合：MCP-Apps ホストでは view_map <id> をインラインで実行するか、シェルでは carto maps screenshot <id>（PNG）を実行します。
• AI エージェントの表示を確認する場合：carto maps agents status / models / mcp-tools / core-tools を実行します（CLI 専用）。
• 書き込み後に行き詰まった場合：Builder はサーバーイベントを購読しないため、Builder のタブを再読み込みするようユーザーに伝えてください。