carto-explore-datawarehouse

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

carto-explore-datawarehouse

CARTO数据仓库探索

Before writing SQL or building maps, an agent typically needs to know what's in the warehouse. This skill covers two CARTO surfaces for that:

carto connections browse
— walk the warehouse hierarchy (project → dataset → table).
carto connections describe
— inspect a specific table's columns and types.

And one CARTO-specific concept:

Named sources — saved, parameterized SQL that maps and apps consume as if they were tables.

在编写SQL或制作地图之前，Agent通常需要了解数据仓库中的内容。本技能涵盖了CARTO的两个相关功能：

carto connections browse
— 遍历数据仓库层级结构（项目→数据集→表）。
carto connections describe
— 查看特定表的列和数据类型。

以及一个CARTO特有的概念：

Named sources（命名数据源） — 已保存的参数化SQL，地图和应用可将其当作表来使用。

When to use this skill

何时使用本技能

You don't know which tables / schemas exist in a connection.
You need a column list and types before writing SQL or authoring a map.
The user references "the named source for X" and you need to find it.

If you already know the table and just want to query it, jump straight to

carto-query-datawarehouse

你不清楚已连接的数据仓库中有哪些表/模式。
在编写SQL或制作地图前，你需要获取列列表和数据类型。
用户提到"X对应的命名数据源"，而你需要找到它。

如果你已经明确要查询的表，可直接跳转至

carto-query-datawarehouse

。

Quick reference

快速参考

bash

undefined

bash

undefined

What connections are registered?

查看已注册的连接有哪些？

carto connections list --json

Walk the hierarchy (no path = top level)

遍历层级结构（无路径则显示顶层）

carto connections browse <connection-name>

Drill in

深入查看

carto connections browse <connection-name> "carto-demo-data" carto connections browse <connection-name> "carto-demo-data.demo_tables"

Get columns + types for a specific table

获取特定表的列和数据类型

carto connections describe <connection-name> "carto-demo-data.demo_tables.nyc_collisions"


The exact path syntax depends on the engine:

| Engine | `browse` path shape |
|---|---|
| BigQuery | `project.dataset.table` |
| Snowflake | `DATABASE.SCHEMA.TABLE` |
| Postgres / Redshift | `schema.table` (no leading project/database) |
| Databricks | `catalog.schema.table` |

carto connections describe <connection-name> "carto-demo-data.demo_tables.nyc_collisions"


具体的路径语法取决于使用的引擎：

| 引擎 | `browse` 路径格式 |
|---|---|
| BigQuery | `project.dataset.table` |
| Snowflake | `DATABASE.SCHEMA.TABLE` |
| Postgres / Redshift | `schema.table`（无前缀项目/数据库） |
| Databricks | `catalog.schema.table` |

What's in this skill

本技能包含的内容

Topic	Reference
`connections browse` and `connections describe` in detail	references/connection-browse.md
Named sources — what they are, how to list and inspect them	references/named-sources.md

主题	参考文档
`connections browse` 和 `connections describe` 详细说明	references/connection-browse.md
Named sources——定义、列出及查看方法	references/named-sources.md

Always-on guidance

通用指导建议

Browse before you query. A two-second
```
connections browse
```
usually saves a five-minute "table not found" loop.
Use
--page-size
when a dataset has hundreds of tables; the default is 30.
describe
returns column types — use those types to write correct SQL (e.g. don't
```
ST_DWithin
```
against a
```
STRING
```
column the user mistakenly named
```
geom
```
).
Named sources ≠ tables. They're parameterized queries. Inspect the underlying tables before assuming a column you see in the source exists in raw form.
carto-demo-data
is a public BigQuery dataset CARTO ships —
```
carto connections browse <bq-connection> "carto-demo-data"
```
works on any BigQuery connection that has the right IAM, and is a fast way to validate a fresh connection without touching customer data.

查询前先浏览。执行一次仅需两秒的
```
connections browse
```
通常能避免五分钟的"表未找到"排查循环。
使用
--page-size
参数：当数据集包含数百张表时，可使用该参数；默认每页显示30条。
describe
返回列的数据类型——利用这些类型编写正确的SQL（例如，不要对用户误命名为
```
geom
```
的
```
STRING
```
列使用
```
ST_DWithin
```
函数）。
Named sources ≠ 表。它们是参数化查询。在假设你在数据源中看到的列以原始形式存在之前，请先查看其底层表。
**
```
carto-demo-data
```
**是CARTO提供的公开BigQuery数据集——只要BigQuery连接具备正确的IAM权限，执行
```
carto connections browse <bq-connection> "carto-demo-data"
```
即可访问，这是一种无需接触客户数据就能快速验证新连接的方法。