carto-query-datawarehouse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

carto-query-datawarehouse

Run SQL — spatial or otherwise — against any connection CARTO has registered. The CLI exposes two surfaces:

carto sql query
—
```
SELECT
```
queries that return rows. Has a 1-minute timeout. Optional client-side caching.
carto sql job
— DDL/DML jobs (
```
CREATE TABLE AS SELECT
```
,
```
UPDATE
```
,
```
INSERT
```
). No timeout; polls until done; returns no rows.

Plus a sibling for usage analytics:

carto activity query
— DuckDB-backed SQL over downloaded CARTO activity data. Local execution, separate from warehouse SQL.

针对CARTO已注册的任意连接运行SQL（空间SQL或其他类型）。CLI提供两种操作方式：

carto sql query
— 返回行数据的
```
SELECT
```
查询。超时时间为1分钟，支持可选的客户端缓存。
carto sql job
— DDL/DML任务（如
```
CREATE TABLE AS SELECT
```
、
```
UPDATE
```
、
```
INSERT
```
）。无超时限制，会轮询直到任务完成，不返回行数据。

此外还有一个用于使用情况分析的功能：

carto activity query
— 基于DuckDB，对下载的CARTO活动数据执行SQL。本地执行，与数据仓库SQL相互独立。

When to use this skill

何时使用此技能

The user wants to count rows, run an exploratory
```
SELECT
```
, or build a transformation.
The user is debugging slow / failing SQL.
The agent needs to materialize an intermediate table before authoring a map.
The user wants to run an ad-hoc spatial join, buffer, or H3 aggregation.

用户需要统计行数、执行探索性
```
SELECT
```
查询，或构建数据转换任务。
用户正在调试运行缓慢或执行失败的SQL。
Agent需要在制作地图之前物化中间表。
用户需要执行临时空间连接、缓冲区分析或H3聚合操作。

Quick reference

快速参考

bash

undefined

bash

undefined

Read query (returns rows; 1-min timeout)

读取查询（返回行数据；1分钟超时）

carto sql query <connection> "SELECT * FROM dataset.table LIMIT 10"

Long-running job (DDL/DML; polls to completion; no rows back)

长时间运行的任务（DDL/DML；轮询至完成；不返回行数据）

carto sql job <connection> "CREATE TABLE my_ds.out AS SELECT ..."

From file

从文件读取

carto sql query <connection> --file query.sql

Piped

管道输入

echo "SELECT 1" | carto sql query <connection>


| Use | Command |
|---|---|
| Exploratory `SELECT` (small result, fast) | `sql query` |
| Cached `SELECT` (deterministic, 1y TTL) | `sql query ... --cache` |
| `CREATE TABLE AS SELECT`, large `UPDATE` | `sql job` |
| 5+ minute aggregation | `sql job` (queries time out at 1 min) |

`--cache` switches to GET with a cached response (1 year, 1 min timeout). Use only for queries that are deterministic and small enough for a URL.

echo "SELECT 1" | carto sql query <connection>


| 使用场景 | 命令 |
|---|---|
| 探索性`SELECT`（结果量小、速度快） | `sql query` |
| 缓存`SELECT`（确定性查询，1年TTL） | `sql query ... --cache` |
| `CREATE TABLE AS SELECT`、大型`UPDATE` | `sql job` |
| 5分钟以上的聚合操作 | `sql job`（`sql query`查询超时时间为1分钟） |

`--cache`参数会切换为使用缓存响应的GET请求（缓存有效期1年，超时时间1分钟）。仅适用于确定性且内容足够短、可放入URL的查询。

What's in this skill

此技能包含的内容

Topic	Reference
`sql query` vs `sql job` , caching, timeouts	references/sql-jobs-and-caching.md
Spatial SQL idioms — BigQuery dialect	references/spatial-sql-bigquery.md
Spatial SQL idioms — Snowflake dialect	references/spatial-sql-snowflake.md
Spatial SQL idioms — Postgres / PostGIS dialect	references/spatial-sql-postgres.md
Querying CARTO activity data (local DuckDB)	references/activity-queries.md

主题	参考文档
`sql query` 与 `sql job` 的区别、缓存、超时设置	references/sql-jobs-and-caching.md
空间SQL用法——BigQuery方言	references/spatial-sql-bigquery.md
空间SQL用法——Snowflake方言	references/spatial-sql-snowflake.md
空间SQL用法——Postgres/PostGIS方言	references/spatial-sql-postgres.md
查询CARTO活动数据（本地DuckDB）	references/activity-queries.md

Always-on guidance

通用指南

Always specify a connection.
```
<connection>
```
in
```
sql query <connection> ...
```
is the connection name from
```
connections list
```
, not the warehouse project ID.
Use
--json
when an agent will parse the output. Default text output is for humans.
Prefer
sql job
for any query that might exceed 60 s.
```
sql query
```
has a hard 1-minute server-side timeout regardless of the user's patience.
Don't
SELECT *
on warehouse tables blindly. Spatial tables can be 100M+ rows; always project columns and add
```
LIMIT
```
for exploration.
Dialect mismatch is the #1 source of confusion.
```
ST_DWithin
```
exists in PostGIS and Redshift, but is
```
ST_DWITHIN
```
in Snowflake and lives under
```
ST_DWithin
```
in BigQuery's
```
bigquery-public-data.geo_us_boundaries
```
style. The reference per dialect explains the canonical form.
For activity-data analysis (who edited what, quota usage, login patterns), use
```
activity query
```
— it runs DuckDB SQL locally over downloaded data. See references/activity-queries.md.

始终指定连接。
```
sql query <connection> ...
```
中的
```
<connection>
```
是
```
connections list
```
中的连接名称，而非数据仓库项目ID。
当Agent需要解析输出时使用
--json
参数。默认文本输出是面向人类用户的。
对于可能超过60秒的查询，优先使用
sql job
。无论用户是否等待，
```
sql query
```
都有严格的1分钟服务器端超时限制。
不要盲目对数据仓库表执行
SELECT *
。空间表可能包含1亿+行数据；探索时务必指定所需列并添加
```
LIMIT
```
限制。
方言不匹配是最常见的困惑来源。
```
ST_DWithin
```
在PostGIS和Redshift中存在，但在Snowflake中为
```
ST_DWITHIN
```
，在BigQuery的
```
bigquery-public-data.geo_us_boundaries
```
风格下则为
```
ST_DWithin
```
。各方言的参考文档会说明标准写法。
如需进行活动数据分析（如谁编辑了什么、配额使用情况、登录模式），请使用
```
activity query
```
——它会基于下载的数据在本地运行DuckDB SQL。详情请见references/activity-queries.md。