Business Search 查询语法

Bright Data Business Search 的结构化查询是 mode 为 ludicrous 时作为 query 传入的 JSON 对象。查询使用七个运算符：equals、in、range 和 text 各接收一个字段名和一个值，生成一个条件；and、or 和 not 接收条件并将其组合。本页说明每个运算符的取值形式、运算符如何嵌套、每种字段类型接受哪些运算符，以及格式错误的查询会返回哪些校验错误。字段名列表见公司搜索和人物搜索。

结构化查询支持哪些运算符

运算符	取值形式	含义	示例
`and`	条件数组	所有子条件都必须匹配	`{ "and": [ ... ] }`
`or`	条件数组	至少一个子条件匹配	`{ "or": [ ... ] }`
`not`	单个条件	排除匹配该子条件的记录	`{ "not": { "equals": { "organization_type": "Educational" } } }`
`equals`	字段名和一个标量	在有类型字段上匹配精确值	`{ "equals": { "headquarters_country_code": "US" } }`
`in`	字段名和一个数组	在有类型字段上匹配列表中的任一值	`{ "in": { "headquarters_country_code": ["US", "GB"] } }`
`range`	字段名和一个包含 `>`、`>=`、`<` 或 `<=` 的对象	在有类型字段上匹配数值边界	`{ "range": { "employees_in_linkedin": { ">=": 50, "<=": 500 } } }`
`text`	字段名和一个字符串，或包含 `value`、`mode` 和 `top-k` 的对象	在文本字段中按词匹配	`{ "text": { "current_title": { "value": "product manager", "mode": "all" } } }`

and、or 和 not 以条件为子项，equals、in、range 和 text 接收字段名与值。text 示例使用的 current_title 是人物字段，其余示例使用公司字段。

如何组合条件

逻辑运算符可以嵌套。下面的请求中，一个 or 条件是 and 的子项。该公司请求匹配位于 US 或 GB 的软件或科技公司，并排除组织类型为 Educational 的记录。高亮行即为 query 对象：

curl --request POST "https://api.brightdata.com/search/company" \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "ludicrous",
    "query": {
      "and": [
        {
          "or": [
            { "text": { "industry": "software" } },
            { "text": { "industry": "technology" } }
          ]
        },
        { "in": { "headquarters_country_code": ["US", "GB"] } },
        { "not": { "equals": { "organization_type": "Educational" } } }
      ]
    },
    "limit": 3,
    "view": "summary"
  }'

import os
import requests

response = requests.post(
    "https://api.brightdata.com/search/company",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
      "mode": "ludicrous",
      "query": {
        "and": [
          {
            "or": [
              { "text": { "industry": "software" } },
              { "text": { "industry": "technology" } }
            ]
          },
          { "in": { "headquarters_country_code": ["US", "GB"] } },
          { "not": { "equals": { "organization_type": "Educational" } } }
        ]
      },
      "limit": 3,
      "view": "summary"
    },
)
print(response.text)

const response = await fetch("https://api.brightdata.com/search/company", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mode": "ludicrous",
    "query": {
      "and": [
        {
          "or": [
            { "text": { "industry": "software" } },
            { "text": { "industry": "technology" } }
          ]
        },
        { "in": { "headquarters_country_code": ["US", "GB"] } },
        { "not": { "equals": { "organization_type": "Educational" } } }
      ]
    },
    "limit": 3,
    "view": "summary"
  }),
});
console.log(await response.text());

在同一字段上，in 匹配的记录与该字段上多个 equals 条件的 or 组合相同。

文本匹配如何工作

text 条件可以是字符串（如上面的公司请求），也可以是包含 value 和 mode 的对象。mode: "all" 要求 value 中的每个词都出现在字段中，顺序和位置不限。下面的人物请求匹配同时包含 machine、learning 和 engineer 的职位：

curl --request POST "https://api.brightdata.com/search/people" \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "ludicrous",
    "query": {
      "text": {
        "current_title": {
          "value": "machine learning engineer",
          "mode": "all"
        }
      }
    },
    "limit": 3,
    "view": "summary"
  }'

import os
import requests

response = requests.post(
    "https://api.brightdata.com/search/people",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
      "mode": "ludicrous",
      "query": {
        "text": {
          "current_title": {
            "value": "machine learning engineer",
            "mode": "all"
          }
        }
      },
      "limit": 3,
      "view": "summary"
    },
)
print(response.text)

const response = await fetch("https://api.brightdata.com/search/people", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mode": "ludicrous",
    "query": {
      "text": {
        "current_title": {
          "value": "machine learning engineer",
          "mode": "all"
        }
      }
    },
    "limit": 3,
    "view": "summary"
  }),
});
console.log(await response.text());

mode 可取以下值。没有任何模式支持精确短语匹配：

模式	行为
`top-bm25`	默认值。按 BM25 排序的部分匹配
`all`	每个搜索词都必须命中
`any`	任一搜索词命中即可

top-k 限制文本条件检索的候选记录数量，默认 100。

如何表达数值边界

range 接收一个字段名以及一到两个比较键。两个键表示闭区间。下面的公司请求匹配在册员工数为 50 到 500 的公司：

curl --request POST "https://api.brightdata.com/search/company" \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "ludicrous",
    "query": {
      "range": {
        "employees_in_linkedin": { ">=": 50, "<=": 500 }
      }
    },
    "limit": 3,
    "view": "summary"
  }'

import os
import requests

response = requests.post(
    "https://api.brightdata.com/search/company",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
      "mode": "ludicrous",
      "query": {
        "range": {
          "employees_in_linkedin": { ">=": 50, "<=": 500 }
        }
      },
      "limit": 3,
      "view": "summary"
    },
)
print(response.text)

const response = await fetch("https://api.brightdata.com/search/company", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "mode": "ludicrous",
    "query": {
      "range": {
        "employees_in_linkedin": { ">=": 50, "<=": 500 }
      }
    },
    "limit": 3,
    "view": "summary"
  }),
});
console.log(await response.text());

一个键表示开区间，例如 { "followers": { ">=": 1000 } }。

每种字段类型接受哪些运算符

字段接受哪些运算符取决于字段类型。向字段发送其类型不支持的运算符会返回 HTTP 400，错误信息中会指出字段、运算符以及该运算符支持的类型。

字段类型	示例字段	接受的运算符	拒绝示例
文本	`industry`、`current_title`	`text`	对 `industry` 使用 `equals` 返回 `Operator does not support field type 'text'`
有类型（字符串、数值）	`headquarters_country_code`、`city`、`employees_in_linkedin`、`followers`	`equals`、`in`、`range`	对 `headquarters_country_code` 使用 `text` 返回 `Operator does not support field type 'string'. Supported types: text`

字段名因类目而异。完整列表见公司搜索和人物搜索。出现在 view 输出中的字段不一定可以搜索：人物的 connections 会在 summary 中返回，但不能用于 range 条件。

哪些查询会被拒绝

Business Search 在执行搜索之前会先校验请求。被拒绝的请求返回 HTTP 400，并在消息中指出出错的属性。该请求不会执行搜索，也不会计费。

规则	结果
`query` 在 Ludicrous 中必须是对象，在 Instant 和 Smart 中必须是字符串	HTTP 400：`request: "query" must be of type object` 或 `request: "query" must be a string`
`equals`、`in` 和 `range` 只适用于有类型字段	HTTP 400：`Operator does not support field type 'text'`
`text` 只适用于文本字段	HTTP 400：`Operator does not support field type 'string'. Supported types: text`
`text` 中的 `mode` 必须是可接受的取值	HTTP 400，并列出可接受的取值

query 对象之外的拒绝原因，例如无效的 limit、未知的 view 字段或超过 200 个字符的自然语言查询，见 Business Search 错误代码。

常见问题

公司搜索和人物搜索的 query 对象一样吗

运算符完全相同，字段名不同。公司类目使用 industry、headquarters_country_code 和 linkedin_followers，人物类目使用 current_title、country_code 和 followers。参见公司搜索和人物搜索。

结构化查询能用于 Instant 或 Smart 模式吗

不能。ludicrous 接收结构化对象，instant 和 smart 接收自然语言字符串。类型不匹配会被以 HTTP 400 拒绝：在 Instant 中传对象会返回 request: "query" must be a string，在 Ludicrous 中传字符串会返回 request: "query" must be of type object。参见什么是 Business Search。

开始使用

数据提取

网页搜索

AI 训练数据

代理网络

结构化查询支持哪些运算符

如何组合条件

文本匹配如何工作

如何表达数值边界

每种字段类型接受哪些运算符

哪些查询会被拒绝

常见问题

公司搜索和人物搜索的 query 对象一样吗

结构化查询能用于 Instant 或 Smart 模式吗

相关页面

​结构化查询支持哪些运算符

​如何组合条件

​文本匹配如何工作

​如何表达数值边界

​每种字段类型接受哪些运算符

​哪些查询会被拒绝

​常见问题

​公司搜索和人物搜索的 query 对象一样吗

​结构化查询能用于 Instant 或 Smart 模式吗

​相关页面

结构化查询支持哪些运算符

如何组合条件

文本匹配如何工作

如何表达数值边界

每种字段类型接受哪些运算符

哪些查询会被拒绝

常见问题

公司搜索和人物搜索的 query 对象一样吗

结构化查询能用于 Instant 或 Smart 模式吗

相关页面