---
title: 查询数据
navTitle: 查询数据
---
# 查询数据

AI 辅助开发时，经常需要先查一小段真实数据来理解字段含义、验证过滤条件或确认页面展示结果。SuccApp CLI 提供两类查询入口：`db` 面向数据库物理层，适合查看数据源、schema、物理表和执行只读 SQL；`model` 面向 SuccApp 语义层模型，适合按 `.tbl` 模型、字段、权限和 Query DSL 查询业务口径数据。

## 查询前确认{#requirements}

请先确认：

1. 当前 AI 入口可以调用 SuccApp CLI，或团队提供了等价的受控工具入口。
2. SuccApp CLI 已登录目标服务器，命令行可访问当前账号有权限查看的数据源和模型。
3. 本次查询目标已经明确：是排查物理表数据，还是验证 SuccApp 模型口径。
4. 涉及生产数据、敏感数据或大范围导出时，已经确认数据范围和用途。

查询入口选择建议：

| 目标 | 推荐入口 | 适用场景 |
| --- | --- | --- |
| 查数据库连接、schema、物理表、字段和原始行 | `succapp db ...` | 排查物理表是否有数据、字段名是否正确、SQL 是否能在目标数据源执行。 |
| 查 `.tbl` 模型、模型字段、模型过滤后的业务数据 | `succapp model ...` | 验证页面、报表、仪表板或 Query DSL 使用的语义层口径。 |
| 查询少量样例数据给 AI 分析 | `db query` 或 `model select/query` | 返回有限行数，适合直接放到终端输出或 AI 上下文。 |
| 导出较多数据到文件 | `db export` 或 `model export` | 生成 CSV 文件，不把完整结果写入 stdout。 |

## 查询物理层数据{#physical-data}

物理层查询直接面向数据库和物理表。它适合在建模、排障或写 SQL 前确认数据源、schema、表结构和原始数据。

### 查看数据源和表结构{#physical-structure}

先让 AI 或命令行查看可访问的数据源，再逐步定位 schema、表和字段：

```bash
succapp db source list
succapp db source list --json
succapp db source show <datasource>
succapp db schema list <datasource>
succapp db table list <datasource>
succapp db table describe <datasource> <table>
```

执行 SQL 前，应先通过 CLI 输出确认目标数据源的数据库产品或方言线索，例如数据库产品名、产品版本、连接器、JDBC 驱动、默认 schema 或 catalog。不同数据库的分页、日期函数、字符串拼接、大小写引用、schema 写法和类型转换语法可能不同，AI 不能在未确认数据库类型时直接套用通用 SQL。

如果命令输出中没有直接显示数据库产品名，也要根据 `dbConnector`、`driver`、`databaseProductVersion`、`defaultSchema` 等信息判断方言；仍无法判断时，先询问用户或让团队补充数据源说明，再生成 SQL。

如果目标表不在默认 schema 下，列出表时把 schema 作为第二个位置参数；描述表和执行 SQL 时再使用 `--schema`：

```bash
succapp db table list <datasource> PUBLIC
succapp db table describe <datasource> <table> --schema=PUBLIC
succapp db query <datasource> "select * from orders" --schema=PUBLIC --max-rows=20
```

### 预览 SQL 查询结果{#physical-preview}

使用 `db query` 执行只读 SQL 查询。预览结果默认只返回前 `100` 行，服务端上限为 `1000` 行；需要更少样例时用 `--max-rows` 明确限制。

```bash
succapp db query <datasource> "select * from orders" --max-rows=20
succapp db query <datasource> --file=./query.sql --schema=PUBLIC --timeout=10 --max-rows=100
cat query.sql | succapp db query <datasource> --max-rows=100 --json
```

需要给 AI 稳定读取结果时，可以加 `--json`。JSON 结果中的 `fields` 描述字段，`rows` 是对象行数组，`rowCount` 是本次实际返回行数，`truncated` 表示结果是否被 `maxRows` 截断。

```bash
succapp db query <datasource> "select id, name from orders" --max-rows=20 --json
```

`db query` 是只读入口。服务端会拒绝非只读 SQL，并通过只读查询连接执行，避免 AI 在查数场景误修改业务数据。

SQL 来源只能选择一种：命令位置参数 `<sql>`、`--file=./query.sql`，或管道 stdin。没有传 `<sql>` 和 `--file` 时，如果命令从管道接收到内容，会把 stdin 作为 SQL；交互终端中没有输入来源时，命令会提示缺少 SQL。

### 导出物理层查询结果{#physical-export}

预览命令适合小样本查询；需要较多数据时使用 `db export` 导出 CSV 文件。导出必须指定 `--output`，不会把完整数据写入 stdout。

```bash
succapp db export <datasource> orders --output=orders.csv
succapp db export <datasource> --query="select id, name from orders" --output=orders.csv
succapp db export <datasource> --query-file=./query.sql --output=orders.csv
```

输出文件已存在时，命令会要求显式确认；确认覆盖时使用 `--force`。

```bash
succapp db export <datasource> --query-file=./query.sql --output=orders.csv --force
```

导出目标只能选择一种：表名 `<table>`、`--query` 或 `--query-file`。`--output` 是必填项，输出目录不存在时 CLI 会尝试创建；如果远端导出、网络或本地写入失败，目标文件不会被写成半截结果。

## 查询语义层模型{#semantic-model}

语义层查询面向 SuccApp 数据模型。它不要求 AI 直接理解底层物理表关系，而是通过 `.tbl` 模型、模型字段、模型过滤表达式和 Query DSL 查询业务口径数据。

当数据用于页面、报表、仪表板、应用组件或已有模型口径校验时，优先使用 `model` 命令。这样可以更贴近产品实际取数路径，也更容易发现模型字段、权限、过滤条件和物理表之间的不一致。

### 查看模型和字段{#model-structure}

先定位模型，再查看模型摘要、字段和索引：

```bash
succapp model list --project DEMO --limit=20
succapp model show /DEMO/data/tables/APP/客户.tbl
succapp model fields /DEMO/data/tables/APP/客户.tbl
succapp model indexes /DEMO/data/tables/APP/客户.tbl
```

字段较多时，可以按维度、度量或关键字过滤：

```bash
succapp model fields /DEMO/data/tables/APP/客户.tbl --dim
succapp model fields /DEMO/data/tables/APP/客户.tbl --measure
succapp model fields /DEMO/data/tables/APP/客户.tbl --contains=状态
```

### 查询单个模型{#model-select}

如果只需要查询一个 `.tbl` 模型，使用 `model select`。`--where` 使用 SuccApp 模型表达式，`--select` 指定返回字段，`--order` 指定排序，`--max-rows` 控制预览行数。

```bash
succapp model select /DEMO/data/tables/APP/客户.tbl --max-rows=20
succapp model select /DEMO/data/tables/APP/客户.tbl --select ID,NAME,STATUS --where "STATUS='ACTIVE'" --order "CREATE_TIME desc" --max-rows=20 --json
```

`model select` 的预览结果同样默认返回前 `100` 行，服务端上限为 `1000` 行。返回结构与 `db query` 保持一致，便于 AI 用同一种方式读取 `fields`、`rows`、`rowCount`、`maxRows` 和 `truncated`。

### 使用 Query DSL 查询模型{#model-query}

当查询涉及多个模型、分组、排序、聚合或已有 `.query` 逻辑时，使用 `model query` 执行 Query DSL JSON。

执行语义层查询前，先查看 Query DSL JSON 格式，再根据模型字段生成查询。Query DSL 描述的是 SuccApp 模型查询，不是数据库 SQL；`sources` 指向模型，`fields` 描述返回字段或表达式，`filter`、`sorts`、`options` 等属性用于表达过滤、排序和行数限制。

一个最小 Query DSL JSON 示例：

```json
{
  "sources": ["/DEMO/data/tables/APP/客户.tbl"],
  "fields": [
    {
      "alias": "NAME",
      "exp": "NAME"
    },
    {
      "alias": "STATUS",
      "exp": "STATUS"
    }
  ],
  "filter": "STATUS='ACTIVE'",
  "options": {
    "enableLimit": true,
    "limit": 20
  }
}
```

```bash
succapp model query --query-file=./query.json --max-rows=100 --json
cat query.json | succapp model query --stdin --json
```

`model query` 的 Query DSL 来源只能选择一种：`--query`、`--query-file` 或 `--stdin`。JSON 较短时可以用 `--query` 直接传入；实际任务中更推荐使用文件或 stdin，便于 AI Agent 生成、检查和复用。

AI 生成或修改 Query DSL 前，应先执行 `model show` 和 `model fields` 查看相关模型、字段和字段类型，避免使用不存在的字段或绕开模型口径。需要复用已有查询文件时，先查看对应 `.query` 或 `query.json` 的结构，再局部调整字段、过滤条件或行数限制。

### 导出语义层查询结果{#model-export}

需要导出模型查询结果时使用 `model export`。它可以导出单模型 `select` 结果，也可以导出 Query DSL 查询结果。

```bash
succapp model export /DEMO/data/tables/APP/客户.tbl --select ID,NAME --output=customers.csv
succapp model export --query-file=./query.json --output=result.csv
cat query.json | succapp model export --stdin --output=result.csv
```

导出结果写入 CSV 文件；输出文件已存在时，使用 `--force` 明确覆盖。

`model export` 的导出目标只能选择一种：模型路径 `<model>`、`--query`、`--query-file` 或 `--stdin`。导出单模型时，可以继续使用 `--select`、`--where` 和 `--order` 控制字段、过滤和排序；导出 Query DSL 时，这些查询条件应写在 Query DSL JSON 中。

## AI 查询建议{#ai-guidelines}

让 AI 查数时，建议在任务描述中写清：

1. 优先使用物理层还是语义层。
2. 数据源、schema、表名或模型路径。
3. 需要返回的字段、过滤条件和样例行数。
4. 输入来源是直接参数、本地文件，还是管道 stdin。
5. 是否允许导出 CSV 文件，以及允许写入的输出路径。
6. 是否涉及生产数据或敏感字段。

可以直接这样描述任务：

```text
请先用 succapp model fields 查看 /DEMO/data/tables/APP/客户.tbl 的字段，再用 model select 查询 STATUS='ACTIVE' 的 20 行样例数据。只允许只读查询，不要导出文件。
```

如果只是分析业务口径，优先让 AI 使用 `model` 命令；如果是排查数据库连接、字段名、SQL 方言或物理表数据，使用 `db` 命令。

## 安全边界{#security}

查数默认应遵守最小数据原则：

1. 预览查询先用 `--max-rows` 限制样例行数。
2. 大数据结果走 `export` 写文件，不把完整数据灌入 AI 对话。
3. 生产环境优先查汇总或脱敏字段，避免直接暴露敏感明细。
4. 不让 AI 在未确认的情况下执行写入、删除、建表、改表等 SQL。
5. 修改模型、查询文件或数据源配置前，先检查引用影响。

`db query` 和 `model select/query` 面向预览，适合验证和理解；`db export` 和 `model export` 面向文件导出，应在确认用途和范围后再执行。

## 常见排查{#troubleshooting}

| 现象 | 处理方式 |
| --- | --- |
| 找不到数据源 | 先执行 `succapp db source list`，确认当前账号和服务器能看到目标数据源。 |
| 找不到表或字段 | 查看 schema 是否正确；再执行 `db table list`、`db table describe` 或 `model fields` 确认名称。 |
| SQL 在数据库工具能跑，`db query` 失败 | 检查是否使用了非只读语句、数据库方言、schema 或当前账号权限。 |
| 模型查询结果和物理表不一致 | 优先检查 `.tbl` 模型字段、过滤条件、权限字段、计算字段和模型引用的数据源。 |
| `truncated` 为 `true` | 结果超过预览上限。减少过滤范围、提高 `--max-rows`，或改用 `export` 导出 CSV。 |
| 提示输入冲突 | 同一类输入传了多个来源，例如同时传 `<sql>` 和 `--file`，或同时传 `<model>` 和 `--query-file`。保留一个来源后重试。 |
| 提示缺少输出文件 | `db export` 和 `model export` 必须传 `--output`。确认可以写入的本地路径后重试。 |
| 导出文件已存在 | 确认可以覆盖后加 `--force`，或换一个输出文件名。 |