byted-data-search

データ検索ツール

前提条件

環境変数が必要です（スクリプトは自動で読み取ります。読み取れない場合は、ユーザーに設定を促してください）：

• 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 を使用

注意：企業タグ（is_longtou_flag など）のような long 型フィールドは数値型ですが、ブール値の判定には 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:存续'

この方法は、reg_status、category、region_level、taxpayer_type、company_org_type など、すべての keyword 型の列挙フィールドに適用できます。これらのフィールドは 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"