🇨🇳中文介绍

数据查询工具

前置要求

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

• VOLCENGINE_ACCESS_KEY（或 VOLC_ACCESS_KEY）
• VOLCENGINE_SECRET_KEY（或 VOLC_SECRET_KEY）

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

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

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

# 列出所有可用数据源摘要（含 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 之前请务必对照此表。

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

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

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

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

具体步骤：

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

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

# 第 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）有哪些选项

• 需要在特定条件范围内（如某条产业链内）查看字段的取值分布

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

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

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

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

参数说明：

输出示例：

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

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

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

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

常见示例：

# 查看企业状态有哪些取值
python3 scripts/get_field_enums.py \
  --datasource-id enterprise_basic_wide --field reg_status

# 查看所属行业分类有哪些
python3 scripts/get_field_enums.py \
  --datasource-id enterprise_basic_wide --field category

# 查看产业链区域指标中 region_level 的取值
python3 scripts/get_field_enums.py \
  --datasource-id industry_chain_node_region_metric --field region_level

# 在"新能源汽车"产业链范围内，查看企业省份分布
python3 scripts/get_field_enums.py \
  --datasource-id industry_chain_company_info --field base_name \
  --filters 'chain_name:like:新能源汽车'

# 查看纳税人类型有哪些
python3 scripts/get_field_enums.py \
  --datasource-id enterprise_basic_wide --field taxpayer_type

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

第二步：查询数据

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

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

完整参数说明：

过滤条件格式

格式：字段名:操作符:值，多个条件用 ; 分隔。

常见错误 ：

• text 类型字段（如 company_name）不能用 eq，须用 like 或 keyword
• keyword 类型字段（如 reg_status）不能用 like，须用 eq / in / not_in
• 如果查询报错"字段不支持操作符"，回到第一步检查字段 type

多条件组合示例：

company_name:like:科技;region_province_name:like:广东;estiblish_time:between:2020-01-01,2025-12-31

当前已知数据源速查

以下为常见数据源，完整清单请调用 describe_datasource.py --datasource-id all 获取：

常见查询示例

企业工商信息查询

# 模糊搜索企业
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'company_name:like:字节跳动'

# 按省份+行业筛选企业
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'region_province_name:eq:广东;category:eq:信息传输、软件和信息技术服务业'

# 查询特定日期后成立的企业
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'company_name:like:科技;estiblish_time:between:2023-01-01,2025-12-31'

产业链企业查询

# 查某产业链下的龙头企业
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_company_info \
  --filters 'chain_name:like:新能源汽车;is_longtou_flag:eq:1'

# 查某产业链下的专精特新企业（按省份筛选）
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_company_info \
  --filters 'chain_name:like:半导体;is_ssdi_flag:eq:1;base_name:eq:广东'

产业链区域指标查询

# 查某产业链在各省份的企业数量
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_node_region_metric \
  --filters 'chain_name:like:新能源;region_level:eq:省' \
  --sort-field company_total_count \
  --sort-order desc

# 聚合统计某产业链的总企业数
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_node_region_metric \
  --filters 'chain_name:like:人工智能' \
  --aggregation 'company_total_count:sum'

上市公司查询

# 按证券编码查询上市公司简况（code 必传）
python3 scripts/query_datasource.py \
  --datasource-id stock_company_brief \
  --filters 'code:eq:000001'

探查字段取值后再过滤

# 不确定 category（所属行业）有哪些取值？用枚举值查询一步搞定
python3 scripts/get_field_enums.py \
  --datasource-id enterprise_basic_wide --field category

# 看到取值后，用精确值过滤
python3 scripts/query_datasource.py \
  --datasource-id enterprise_basic_wide \
  --filters 'category:eq:信息传输、软件和信息技术服务业'

聚合统计查询

# 统计符合条件的总记录数
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_company_info \
  --filters 'chain_name:like:新能源汽车' \
  --aggregation 'count'

# 按省份分组统计企业数量
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_company_info \
  --filters 'chain_name:like:新能源汽车' \
  --group-by 'base_name' \
  --aggregation 'company_id:count'

# 按省份分组统计并去重
python3 scripts/query_datasource.py \
  --datasource-id industry_chain_company_info \
  --filters 'chain_name:like:新能源汽车' \
  --group-by 'base_name' \
  --aggregation 'company_id:distinct'

调用限制

• 频率限制 ：每分钟最多 10 次调用
• 每日上限 ：每天最多 200 次调用
• 如需更多调用次数，请购买 火山引擎-高质量数据集

错误处理

环境变量配置方式：

export VOLCENGINE_ACCESS_KEY="your-access-key"
export VOLCENGINE_SECRET_KEY="your-secret-key"

Weekly Installs

51

Source

skills.volces.c…-samples

First Seen

9 days ago

Security Audits

SocketPass

Installed on

openclaw47

gemini-cli7

github-copilot7

codex7

kimi-cli7

cursor7