archery-query

Files (4)

• SKILL.md
• commands.md · reference/
• errors.md · reference/
• output-formats.md · reference/

SKILL.md (first lines)

# Archery SQL 查询

## 何时使用

- 用户要执行 SQL 查库（通用场景）
- 需要 JSON 结果、保存文件、或 Display 可视化

**优先使用 `archery-quick-query`：** 若任务匹配本机已配置的快捷查询（见 `archery init` 部署的 catalog），优先 `archery quick-query run <name>`。

**不知道实例名或库名片段时：** 先用 `archery-database-search`（模糊/正则，默认 `mysql` + `slave`）或 `archery-instance`（精确 `instance find`），再执行 query。

**查看表结构（列名/类型）：** 用 `archery-table-schema`（`instance table-schema`，实例可省略），不必手写 DESCRIBE。

**不要使用本 Skill：**

- 报表 XML、`report_document`、`report_document_source`、报表元数据 → `archery-report-query`
- 告警总览 → `archery-alert`
- 仅启动 Display → `archery-display`

## 命令速查

```bash
# 省略 --instance（库名在缓存中唯一匹配时，需先 instance refresh）
archery query --db <库> --sql "<SQL>" --full

# 完整 JSON 输出到 stdout
archery query --instance <实例> --db <库> --sql "<SQL>" --full

# 保存到文件，stdout 仅输出路径
archery query --instance <实例> --db <库> --sql "<SQL>" --file

# 推送 Display 可视化
archery query --instance <实例> --db <库> --sql "<SQL>" --display --title "标题"
```

## 必填参数

| 参数 | 说明 |
|------|------|
| `--instance` | Archery 实例名（可省略，按 `--db` 从缓存解析） |
| `--db` | 数据库名 |
| `--sql` | SQL 内容 |

## 输出模式

互斥，优先级：`--full` > `--file` > `--display` > 配置默认（DefaultOutputMode）

| 标志 | stdout 输出 |
|------|-------------|
| `--full` | 完整 QueryResponse JSON |
| `--file` | 单行文件路径 |
| `--display` | `FilePath:` / `SessionId:` / `URL:` 三行 |

结果文件目录：`%APPDATA%/archery-cli/results/`

## 约束

1. 默认只执行只读 `SELECT`
2. Shell 中 SQL 含引号需正确转义
3. SQL 标识符保持原始命名与大小写

## 参考

- 完整参数表：[reference/commands.md](reference/commands.md)
- 输出格式：[reference/output-formats.md](reference/output-formats.md)
- 常见错误：[reference/errors.md](reference/errors.md)

From xqdgithub/archery-cli, MIT.

More from xqdgithub/archery-cli