byted-data-search

Files (6)

• LICENSE
• SKILL.md
• describe_datasource.py · scripts/
• get_field_enums.py · scripts/
• mcp_gateway_client.py · scripts/
• query_datasource.py · scripts/

SKILL.md (first lines)

# 数据查询工具

## 前置要求

需要环境变量（脚本会自动读取，若读取不到需提醒用户设置）：
- `VOLCENGINE_ACCESS_KEY`（或 `VOLC_ACCESS_KEY`）
- `VOLCENGINE_SECRET_KEY`（或 `VOLC_SECRET_KEY`）

## 工作流程（严格按顺序执行）

### 第一步：查询可用数据源（必须先执行）

在构造任何查询之前，**必须先调用此步骤**了解有哪些数据源及其字段定义。这一步的作用是：确认用户需要的数据存在于哪个数据源中，以及该数据源有哪些字段和过滤规则。跳过这一步直接去猜字段名几乎一定会出错。

```bash
# 列出所有可用数据源摘要（含 datasource_id、名称、描述、维度/过滤字段数量）
python3 scripts/describe_datasource.py --datasource-id all

# 获取某个数据源的完整字段定义（维度 dimensions、字段类型、可用过滤操作符）
python3 scripts/describe_datasource.py --datasource-id <数据源ID>
```

返回内容包含：
- `datasource_id`：数据源唯一标识
- `datasource_name`：数据源中文名称
- `description`：数据源说明
- `dimensions`：所有字段列表，每个字段包含 field（字段名）、label（显示名）、type（类型）、description（描述）、filterable（是否可作为过滤条件字段）
- `notes`：使用备注

**关键：根据返回的字段信息（尤其是 field 名称和 type 类型），确定需要用到的字段和过滤操作符，再进入第二步。**

### 字段类型与操作符对照表

每种字段类型只支持特定操作符。用错操作符会直接报错，所以在构造 filters 之前请务必对照此表。

| 字段类型 | 支持的操作符 | 说明 |
|---------|------------|------|
| `keyword` | `eq`, `in`, `not_in` | 精确匹配类字段（如编码、状态、类型） |
| `text` | `like`, `keyword` | 文本类字段（如名称、地址、描述），支持模糊搜索 |
| `date` / `datetime` | `between`, `eq` | 日期类字段，范围查询用 between |
| `long` / `integer` / `float` / `double` | `range`, `eq` | 数值类字段，范围查询用 range |

> 注意：`long` 类型字段如企业标签（`is_longtou_flag` 等）虽然是数值类型，但用于布尔判断时用 `eq` 即可，如 `is_longtou_flag:eq:1`。

### 字段取值不确定时：先探查再过滤

构造过滤条件时，经常会遇到"知道要按某个字段过滤，但不确定该字段的实际取值是什么"的情况。比如用户想按企业状态筛选，但不知道取值是"存续"、"在业"还是"正常"；或者想按产业分类过滤，但不确定分类名称的准确写法。

**正确做法：先做一次不带该过滤条件（或只带其他确定条件）的查询，从返回数据中观察目标字段的实际取值，再用准确的值构造过滤条件。**

具体步骤：
1. 先用宽松条件查询几条数据，观察目标字段返回了哪些值
2. 如果需要看该字段有哪些不同取值，可以用 `--group-by` + `--aggregation` 做分组统计
3. 确认取值后，再加上精确的过滤条件做正式查询

示例——想按"企业状态"过滤但不确定取值：
```bash
# 第 1 步：先查几条数据，观察 reg_status 字段的实际值
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'company_name:like:科技'

# 第 2 步：或者直接做分组统计，看 reg_status 有哪些取值及各有多少条
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'company_name:like:科技' \
  --group-by 'reg_status' \
  --aggregation 'company_id:count'

# 第 3 步：确认取值后，加上精确过滤条件
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'company_name:like:科技;reg_status:eq:存续'
```

这个策略适用于所有 `keyword` 类型的枚举字段（如 `reg_status`、`category`、`region_level`、`taxpayer_type`、`company_org_type` 等），因为这些字段使用 `eq` 精确匹配，写错一个字都会导致零结果。

### 查询字段枚举值

当你不确定某个字段有哪些可选值时（尤其是 `keyword` 类型的枚举字段），可以用专门的枚举值查询脚本一步获取，而不必手动组合 `--group-by` 和 `--aggregation` 参数。该脚本返回最多 200 个不同取值，按出现频次从高到低排列。

这在以下场景特别有用：
- 构造 `eq` 或 `in` 过滤条件前，需要知道字段的准确取值（如 `reg_status` 到底是"存续"还是"在业"）
- 想快速了解某个分类字段（如 `category`、`region_level`、`company_org_type`）有哪些选项
- 需要在特定条件范围内（如某条产业链内）查看字段的取值分布

```bash
# 基本用法：查看某个字段有哪些取值
python3 scripts/get_field_enums.py \
  --datasource-id <数据源ID> \
  --field <字段名>

# 带过滤条件：只看满足条件的数据中该字段有哪些取值
python3 scripts/get_field_enums.py \
  --datasource-id <数据源ID> \
  --field <字段名> \
  --filters '<过滤条件>'
```

参数说明：

| 参数 | 必填 | 说明 |
|------|------|------|
| `--datasource-id` | 是 | 数据源 ID |
| `--field` | 是 | 要查询枚举值的字段名 |
| `--filters` | 否 | 前置过滤条件，格式同 query_datasource |
| `--limit` | 否 | 最多返回的枚举值数量（默认 20，上限 50） |

输出示例：
```
数据源: enterprise_basic_wide
字段:   reg_status
共找到 8 个不同取值（最多显示 200 个）:

   1. 存续  (5832174 条)
   2. 注销  (3021487 条)
   3. 在业  (1245633 条)
   4. 吊销  (412056 条)
   ...

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples