数据查询工具

前置要求

需要环境变量（脚本会自动读取，若读取不到需提醒用户设置）：

• - VOLCENGINEACCESSKEY（或 VOLCACCESSKEY）
• VOLCENGINESECRETKEY（或 VOLCSECRETKEY）

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

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

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

bash

列出所有可用数据源摘要（含 datasource_id、名称、描述、维度/过滤字段数量）

python3 scripts/describe_datasource.py --datasource-id all

获取某个数据源的完整字段定义（维度 dimensions、字段类型、可用过滤操作符）

python3 scripts/describe_datasource.py --datasource-id <数据源ID>

返回内容包含：

• - datasourceid：数据源唯一标识
• datasourcename：数据源中文名称
• 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 类型字段如企业标签（islongtouflag 等）虽然是数值类型，但用于布尔判断时用 eq 即可，如 islongtouflag:eq:1。

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

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

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

具体步骤：

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

示例——想按企业状态过滤但不确定取值：
bash

第 1 步：先查几条数据，观察 reg_status 字段的实际值

python3 scripts/query_datasource.py \
--datasource-id enterprisebasicwide \
--filters company_name:like:科技

第 2 步：或者直接做分组统计，看 reg_status 有哪些取值及各有多少条

python3 scripts/query_datasource.py \ --datasource-id enterprisebasicwide \ --filters company_name:like:科技 \ --group-by reg_status \ --aggregation company_id:count

第 3 步：确认取值后，加上精确过滤条件

python3 scripts/query_datasource.py \ --datasource-id enterprisebasicwide \ --filters companyname:like:科技;regstatus:eq:存续

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

查询字段枚举值

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

这在以下场景特别有用：

• - 构造 eq 或 in 过滤条件前，需要知道字段的准确取值（如 regstatus 到底是存续还是在业）
• 想快速了解某个分类字段（如 category、regionlevel、companyorgtype）有哪些选项
• 需要在特定条件范围内（如某条产业链内）查看字段的取值分布

bash

基本用法：查看某个字段有哪些取值

python3 scripts/getfieldenums.py \
--datasource-id <数据源ID> \
--field <字段名>

带过滤条件：只看满足条件的数据中该字段有哪些取值

python3 scripts/getfieldenums.py \ --datasource-id <数据源ID> \ --field <字段名> \ --filters <过滤条件>

参数说明：

参数	必填	说明
--datasource-id	是	数据源 ID
--field

是 | 要查询枚举值的字段名 |
| --filters | 否 | 前置过滤条件，格式同 query_datasource |
| --limit | 否 | 最多返回的枚举值数量（默认 20，上限 50） |

输出示例：

数据源: enterprisebasicwide
字段: reg_status
共找到 8 个不同取值（最多显示 200 个）:

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

[JSON] [存续, 注销, 在业, 吊销, ...]

最后一行的 [JSON] 行是机器可读格式，方便程序化提取枚举值列表。

常见示例：
bash

查看企业状态有哪些取值

python3 scripts/getfieldenums.py \
--datasource-id enterprisebasicwide --field reg_status

查看所属行业分类有哪些

python3 scripts/getfieldenums.py \ --datasource-id enterprisebasicwide --field category

查看产业链区域指标中 region_level 的取值

python3 scripts/getfieldenums.py \ --datasource-id industrychainnoderegionmetric --field region_level

在新能源汽车产业链范围内，查看企业省份分布

python3 scripts/getfieldenums.py \ --datasource-id industrychaincompanyinfo --field basename \ --filters chain_name:like:新能源汽车

查看纳税人类型有哪些

python3 scripts/getfieldenums.py \ --datasource-id enterprisebasicwide --field taxpayer_type

提示：拿到枚举值后，就可以在正式查询中使用 eq 或 in 精确过滤了。比如确认取值为存续后，就可以用 reg_status:eq:存续 过滤。

第二步：查询数据

根据第一步获取的字段信息构造查询命令：

bash
python3 scripts/query_datasource.py \
--datasource-id <数据源ID> \
--filters <过滤条件> \
--page 1

完整参数说明：

参数	必填	说明
--datasource-id	是	数据源 ID，从第一步获取
--filters

否 | 过滤条件，格式见下方，多个条件用 ; 分隔 |
| --aggregation | 否 | 聚合操作：count（总数统计）、field:count（字段计数）、field:distinct（去重计数）、field:sum/avg/max/min |
| --group-by | 否 | 分组字段，逗号分隔，需配合 --aggregation 使用 |
| --sort-field | 否 | 排序字段名