carto-query-datawarehouse

carto-query-datawarehouse

针对 CARTO 已注册的任何连接运行 SQL——无论是否涉及空间数据。提供两种执行方式，MCP 和 CLI 一一对应：

	返回行的 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 方式。检测信号：carto-basics/references/access-paths.md。

何时使用此技能

• 用户想要统计行数、运行探索性 SELECT，或构建转换。
• 用户正在排查运行缓慢或失败的 SQL。
• Agent 需要在编写地图前物化一张中间表。
• 用户想要临时执行空间连接、缓冲区分析或 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）会改用带有 1 年缓存响应的 GET；仅用于确定性的小型查询。

此技能包含的内容

主题	参考资料
同步与异步执行、缓存、超时	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

始终适用的指南

• 始终指定连接。 连接名称来自 explore_data（list_connections）/ carto connections list，而不是数据仓库的项目 ID。
• 对于任何可能耗时超过 60 s 的查询，优先使用异步路径。 无论用户愿意等待多久，同步读取都有严格的 1 分钟服务端超时限制。
• 不要不加判断地对数据仓库表执行 SELECT *。 空间表可能包含超过 1 亿行；探索时应指定列并添加 LIMIT。
• 方言不匹配是最常见的困惑来源。 Snowflake 中的写法是 ST_DWITHIN，BigQuery/PostGIS/Redshift 中则是 ST_DWithin。各方言参考资料提供了标准写法。
• 分析活动数据时（谁编辑了什么、配额使用情况、登录模式），请使用 carto activity query——仅限 CLI，它会通过 DuckDB 查询已下载的数据。请参阅 references/activity-queries.md。