#601

Global Rank · of 601 Skills

byted-data-search AI Agent Skill

View Source: bytedance/agentkit-samples

Medium

Installation

npx skills add bytedance/agentkit-samples --skill byted-data-search

92

Installs

数据查询工具

前置要求

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

  • 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 之前请务必对照此表。

字段类型 支持的操作符 说明
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. 确认取值后，再加上精确的过滤条件做正式查询

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

# 第 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 '<过滤条件>'

参数说明：

参数 必填 说明
--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 条)
   ...

[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

完整参数说明：

参数 必填 说明
--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:字节跳动 text
in 多值匹配（逗号分隔） reg_status:in:存续,在业 keyword
not_in 排除匹配（逗号分隔） reg_status:not_in:注销,吊销 keyword
between 日期范围（起始,结束） estiblish_time:between:2020-01-01,2025-12-31 date, datetime
range 数值范围（min,max；半开区间用 ,100 或 50,） company_total_count:range:100, long, integer, float, double
keyword 全文搜索 keyword:keyword:新能源补贴 text

常见错误：

  • 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 获取：

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

常见查询示例

企业工商信息查询

# 模糊搜索企业
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 次调用
  • 如需更多调用次数，请购买 火山引擎-高质量数据集

错误处理

错误类型 原因 解决方案
认证失败 环境变量未设置或凭证无效 检查 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 分钟，日限流等次日

环境变量配置方式：

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

Installs

Installs 92
Global Rank #601 of 601

Security Audit

ath Safe
socket Safe
Alerts: 0 Score: 90
snyk Medium
EU EU-Hosted Inference API

Power your AI Agents with the best open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

Explore Inference API

GLM

GLM 5

$1.00 / $3.20

per M tokens

Kimi

Kimi K2.5

$0.60 / $2.80

per M tokens

MiniMax

MiniMax M2.5

$0.30 / $1.20

per M tokens

Qwen

Qwen3.5 122B

$0.40 / $3.00

per M tokens

How to use this skill

1

Install byted-data-search by running npx skills add bytedance/agentkit-samples --skill byted-data-search in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.

2

No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.

3

The skill enhances your agent's understanding of byted-data-search, helping it follow established patterns, avoid common mistakes, and produce production-ready output.

What you get

Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.

Compatibility

This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.

EU Made in Europe

Chat with 100+ AI Models in one App.

Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.

Start for free View pricing
Customer Support