筛选数据集 (BETA)

Bright Data 市场数据集 API 的 Filter 端点针对 250+ 个市场数据集中的任意一个运行大体量或基于文件的筛选任务，并返回一个 snapshot_id，您可在任务完成后下载。

将您的 API Key 粘贴到授权字段。要获取 API Key，请创建账户并了解如何生成 API Key。

何时使用 Filter？

对于可接受异步处理的批量或基于文件的任务，使用 Filter：

超过 1,000 条记录的批量导出。
按 CSV 或 JSON 文件中的大型值列表筛选，例如排除 10 万以上的公司 ID。
Search 尚不支持的数据集。
可接受异步的计划任务或后台管道。

如需对受支持数据集进行亚秒级实时查询，请改用 Search。

Filter 如何工作？

调用 Filter 端点会启动一个异步任务，并在您的账户中创建一份筛选数据的快照。
任务最长运行时间为 5 分钟。运行超时的任务将被取消。
按快照中的每条记录计费，采用标准市场费率 $2.5 CPM。
Filter 适用于全部 250+ 个市场数据集。
筛选组的最大嵌套深度为 3 层。

如何进行身份验证？

Filter 使用 Bearer token 身份验证。在 Authorization 请求头中传入您的 API Key：

Authorization: Bearer YOUR_API_KEY

从账户设置获取您的 Key。

限制

限制	值	说明
每个文件最大行数	10,000	每个上传的 CSV/JSON 文件最多可包含 10,000 行数据。表头行不计入。
每次请求最大文件数	无限制	一次 multipart 请求中可附加任意数量的文件，只要总大小不超过 200 MiB 上限。
最大请求大小	200 MiB	所有上传文件和表单数据的总大小。超过 200 MiB 的请求会被拒绝。
任务超时	5 分钟	如果筛选在 5 分钟内未完成，任务将被取消。
筛选嵌套深度	3 层	使用 `and`/`or` 的嵌套筛选组的最大深度。
最大并行任务数	每个数据集 100 个	每个数据集最多可同时运行 100 个 Filter 任务。
速率限制	120 次/小时	每小时最多的 Filter API 调用次数。

如何调用 Filter？

Filter 有两种模式：JSON 用于普通筛选，multipart 用于文件上传。

JSON 模式（无需上传文件）

将所有参数（dataset_id、records_limit 和 filter）放在 JSON 请求体中。将 Content-Type 设为 application/json：

curl -X POST "https://api.brightdata.com/datasets/filter" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "gd_l1viktl72bvl7bjuj0",
    "records_limit": 100,
    "filter": {
      "name": "name",
      "operator": "=",
      "value": "John"
    }
  }'

Filter 返回一个 snapshot_id：

{ "snapshot_id": "s_abc123..." }

Multipart 模式（文件上传）

将 dataset_id 和 records_limit 作为查询参数发送，将 filter 和上传的文件放在 form-data 请求体中。将 Content-Type 设为 multipart/form-data：

curl -X POST "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije&records_limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'filter={"operator":"and","filters":[{"name":"industries:value","operator":"includes","value":"industries.csv"}]}' \
  -F 'files[]=@/path/to/industries.csv'

要排除 10 万以上的值，将它们拆分为每个最多 10,000 行的文件，并在一次请求中全部附加：

curl -X POST "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije&records_limit=5000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'filter={"operator":"and","filters":[{"name":"company_id","operator":"not_in","value":"exclude1.csv"},{"name":"company_id","operator":"not_in","value":"exclude2.csv"},{"name":"company_id","operator":"not_in","value":"exclude3.csv"}]}' \
  -F 'files[]=@exclude1.csv' \
  -F 'files[]=@exclude2.csv' \
  -F 'files[]=@exclude3.csv'

有关 CSV 和 JSON 文件格式规则、文件引用以及上传故障排除，请参阅使用 CSV/JSON 文件筛选数据集。

Filter 返回什么？

Filter 返回一个 snapshot_id。在任务完成后，使用它通过快照 API 下载筛选后的记录：

Filter 的费用是多少？

Filter 的费用为 $2.5 CPM（每返回 1,000 条记录），与市场价格相同。筛选返回 0 条记录时不收费。

Filter 可能返回哪些错误？

状态码	含义	处理方式
`400`	筛选或参数有误	使用获取数据集元数据核对字段名。
`401`	API Key 错误或缺失	检查您的 Bearer token。
`402`	余额不足	充值或减小 `records_limit`。
`404`	未知的 `dataset_id`	确认数据集 ID。
`422`	筛选未匹配任何记录	放宽筛选条件或检查字段值。
`429`	并行任务过多（每个数据集最多 100 个）或触发速率限制（120 次/小时）	退避后重试。

筛选语法

filter 对象及其运算符、筛选组和嵌套规则与 Search 端点共享，并集中记录在一处。完整的运算符列表、筛选组、最多 3 层嵌套以及 CSV/JSON 文件引用，请参阅筛选语法参考。

何时使用 Filter？

Filter 如何工作？

如何进行身份验证？

限制

如何调用 Filter？

JSON 模式（无需上传文件）

Multipart 模式（文件上传）

Filter 返回什么？

Filter 的费用是多少？

Filter 可能返回哪些错误？

筛选语法

相关文档

授权

查询参数

请求体

响应

​何时使用 Filter？

​Filter 如何工作？

​如何进行身份验证？

​限制

​如何调用 Filter？

​JSON 模式（无需上传文件）

​Multipart 模式（文件上传）

​Filter 返回什么？

​Filter 的费用是多少？

​Filter 可能返回哪些错误？

​筛选语法

​相关文档

授权

查询参数

请求体

响应

何时使用 Filter？

Filter 如何工作？

如何进行身份验证？

限制

如何调用 Filter？

JSON 模式（无需上传文件）

Multipart 模式（文件上传）

Filter 返回什么？

Filter 的费用是多少？

Filter 可能返回哪些错误？

筛选语法

相关文档