查询数据

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

查询前确认

请先确认：

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。

查询物理层数据

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

查看数据源和表结构

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

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：

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 查询结果

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

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 截断。

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。

导出物理层查询结果

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

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。

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

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

查询语义层模型

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

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

查看模型和字段

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

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

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

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=状态

查询单个模型

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

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 查询模型

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

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

一个最小 Query DSL JSON 示例：

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

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。它可以导出单模型 select 结果，也可以导出 Query DSL 查询结果。

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 查数时，建议在任务描述中写清：

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

可以直接这样描述任务：

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

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

安全边界

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

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

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

常见排查

现象	处理方式
找不到数据源	先执行 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，或换一个输出文件名。