数据查询工具#

前置要求#

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

• 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日期类字段，范围查询用 betweenlong / 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）

输出示例：

text

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

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

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

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

常见示例：

bash

# 查看企业状态有哪些取值
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:存续 过滤。

第二步：查询数据#

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

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否排序字段名，不填使用默认排序--sort-order否asc 或 desc（默认 desc）--page否页码，从 1 开始（默认 1）

过滤条件格式#

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

操作符含义示例适用字段类型eq精确匹配reg_status:eq:存续keyword, date, 数值like模糊匹配（短语匹配）company_name:like:字节跳动textin多值匹配（逗号分隔）reg_status:in:存续,在业keywordnot_in排除匹配（逗号分隔）reg_status:not_in:注销,吊销keywordbetween日期范围（起始,结束）estiblish_time:between:2020-01-01,2025-12-31date, datetimerange数值范围（min,max；半开区间用 ,100 或 50,）company_total_count:range:100,long, integer, float, doublekeyword全文搜索keyword:keyword:新能源补贴text

常见错误：

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

多条件组合示例：

text

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

当前已知数据源速查#

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

数据源ID名称典型用途关键注意enterprise_basic_wide企业基本信息工商注册信息、法人、注册资本、经营范围、股东融资等company_name 是 text 类型→用 like；max_page_size=5industry_chain_company_info产业链企业信息产业链下的企业、按标签筛选（龙头/高新/专精特新/独角兽等）chain_name/ node_name 是 text→用 like；标签字段（is_longtou_flag 等）是 long→用 eq:1``industry_chain_node_region_metric产业链节点区域指标产业链的区域分布统计、企业数量、财务指标、知识产权等支持聚合统计，max_page_size=50stock_company_brief上市公司简况A 股上市公司基本面、F10、IPO、分红、高管等必须 用 code:eq:证券编码 查询（如 code:eq:000001）；max_page_size=5

常见查询示例#

企业工商信息查询#

bash

# 模糊搜索企业
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'

产业链企业查询#

bash

# 查某产业链下的龙头企业
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:广东'

产业链区域指标查询#

bash

# 查某产业链在各省份的企业数量
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'

上市公司查询#

bash

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

探查字段取值后再过滤#

bash

# 不确定 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:信息传输、软件和信息技术服务业'

聚合统计查询#

bash

# 统计符合条件的总记录数
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 次调用
• 如需更多调用次数，请购买 火山引擎-高质量数据集

错误处理#

错误类型原因解决方案认证失败环境变量未设置或凭证无效检查 VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY，参考 用户指南 获取 AK/SK数据源不存在datasource_id 错误调用 describe_datasource.py --datasource-id all 确认字段不支持操作符操作符与字段类型不匹配检查字段 type 并参照"字段类型与操作符对照表"字段不可用字段名拼写错误或不可过滤调用 describe_datasource.py --datasource-id <ID> 确认无结果返回过滤条件过严或字段取值不对先用 get_field_enums.py 探查字段实际取值，或放宽条件（如 eq 改为 like）频率限制调用次数超限分钟限流等 1 分钟，日限流等次日

环境变量配置方式：

bash

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