carto-query-datawarehouse

carto-query-datawarehouse

CARTO に登録されている任意の接続に対して、空間 SQL を含む SQL を実行します。MCP と CLI で対応する 2 つの実行方法があります。

	行を返す SELECT（タイムアウト 1 分）	DDL/DML と長時間クエリ（タイムアウトなし、行は返しません）
MCP（主要）	execute_query	execute_async_query（submit／status／cancel）
CLI（代替）	carto sql query	carto sql job

アクセス経路の選択。 CARTO MCP サーバーが接続されている場合は、execute_query と execute_async_query を使って SQL を実行してください。どちらもトークン認証済みのセッションで利用できます。ここに記載されている方言のガイダンスとパフォーマンスに関するルールは、どちらの経路でも同様に適用されます。サーバーが接続されていない場合、または SQL がスクリプト化されている／CI で実行される場合は、carto sql CLI を使用してください。carto activity query（ダウンロード済みのアクティビティデータに対するローカル DuckDB）は CLI 専用 で、MCP に相当する機能はありません。判別の手がかり：アクセス経路。

このスキルを使う場面

• ユーザーが行数を数えたい、探索的な SELECT を実行したい、または変換を作成したい場合。
• ユーザーが遅い SQL や失敗する SQL の問題を調査している場合。
• エージェントがマップを作成する前に、中間テーブルを実体化する必要がある場合。
• ユーザーがアドホックな空間結合、バッファー、または H3 集計を行いたい場合。

クイックリファレンス（CLI）

# Read query (returns rows; 1-min timeout)
carto sql query <connection> "SELECT * FROM dataset.table LIMIT 10"

# Long-running job (DDL/DML; polls to completion; no rows back)
carto sql job <connection> "CREATE TABLE my_ds.out AS SELECT ..."

# From file / piped
carto sql query <connection> --file query.sql
echo "SELECT 1" | carto sql query <connection>

用途	経路
探索的な SELECT（小規模、高速）	同期 — execute_query / sql query
キャッシュされた SELECT（決定的、TTL 1 年）	sql query ... --cache
CREATE TABLE AS SELECT、大規模な UPDATE、5 分以上かかる集計	非同期 — execute_async_query / sql job

--cache（CLI）は GET に切り替え、レスポンスを 1 年間キャッシュします。決定的で小規模なクエリに限って使用してください。

このスキルの内容

トピック	リファレンス
同期／非同期実行、キャッシュ、タイムアウト	references/sql-jobs-and-caching.md
空間 SQL の慣用表現 — BigQuery 方言	references/spatial-sql-bigquery.md
空間 SQL の慣用表現 — Snowflake 方言	references/spatial-sql-snowflake.md
空間 SQL の慣用表現 — Postgres／PostGIS（および Redshift）方言	references/spatial-sql-postgres.md
CARTO アクティビティデータのクエリ（ローカル DuckDB、CLI 専用）	references/activity-queries.md

常に守るガイダンス

• 必ず接続を指定してください。 接続名は、ウェアハウスのプロジェクト ID ではなく、explore_data（list_connections）／carto connections list から取得します。
• 60 秒を超える可能性があるクエリには、非同期経路を優先してください。 同期読み取りは、ユーザーがどれだけ待てるかにかかわらず、サーバー側で 1 分のタイムアウトが設定されています。
• ウェアハウステーブルに対して、むやみに SELECT * を実行しないでください。 空間テーブルは 1 億行を超える場合があります。列を指定し、探索時には LIMIT を追加してください。
• 方言の不一致は、混乱の最大の原因です。 Snowflake では ST_DWithin は ST_DWITHIN、BigQuery／PostGIS／Redshift では ST_DWithin です。各方言のリファレンスに標準的な形式が記載されています。
• アクティビティデータを分析する場合（誰が何を編集したか、クォータの使用状況、ログインパターンなど）は、carto activity query を使用してください。これは CLI 専用で、ダウンロード済みのデータに対する DuckDB を使用します。references/activity-queries.md を参照してください。