Business Search query syntax

Business Search structured query reference: seven operators, and, or, not, equals, in, range and text, plus nesting and text matching rules.

A Bright Data Business Search structured query is the JSON object passed as query when mode is ludicrous. The query uses seven operators. equals, in, range and text each take a field name and a value and produce one condition. and, or and not take conditions and combine them.

This page describes each operator’s value shape, how operators nest, which operators each field type accepts and the validation errors a malformed query returns. Field names are listed on Company search and People search.

Which operators does a structured query accept?

Operator	Value shape	Meaning	Example
and	Array of conditions	All child conditions must match	{ "and": [ ... ] }
or	Array of conditions	At least one child condition must match	{ "or": [ ... ] }
not	One condition	Exclude records that match the child condition	{ "not": { "equals": { "organization_type": "Educational" } } }
equals	Field name and one scalar	Match an exact value on a typed field	{ "equals": { "headquarters_country_code": "US" } }
in	Field name and an array	Match any value in the list on a typed field	{ "in": { "headquarters_country_code": ["US", "GB"] } }
range	Field name and an object with >, >=, < or <=	Match numeric bounds on a typed field	{ "range": { "employees_in_linkedin": { ">=": 50, "<=": 500 } } }
text	Field name and a string, or an object with value, mode and top-k	Match words in a text field	{ "text": { "current_title": { "value": "product manager", "mode": "all" } } }

and, or and not take conditions as children. equals, in, range and text take a field name and a value. The text example uses current_title, a people field. The other examples use company fields.

How do you combine conditions?

Logical operators nest. In the request below, an or condition is a child of and. This company request matches software or technology companies in the US or GB, excluding records whose organization type is Educational. The highlighted lines are the query object:

cURL

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"
  }'

in on one field matches the same records as an or of equals conditions on that field.

How does text matching work?

A text condition contains a string, as in the company request above, or an object with value and mode. mode: "all" requires every word in value to appear in the field, in any order and position. This people request matches titles containing all of machine, learning and engineer:

cURL

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"
  }'

mode takes one of these values. No mode matches an exact phrase:

Mode	Behavior
top-bm25	Default. BM25-ranked partial matches
all	Every search word must match
any	Any search word may match

top-k caps how many candidate records the text condition retrieves, 100 by default.

How do you express a numeric bound?

range takes a field name and one or two comparison keys. Two keys give a closed interval. This company request matches 50 to 500 employees on record:

cURL

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"
  }'

One key gives an open bound, such as { "followers": { ">=": 1000 } }.

Which operators does each field type accept?

The operator a field accepts depends on the field type. Sending an operator the type does not support returns HTTP 400 with a message naming the field, the operator and the types the operator supports.

Field type	Example fields	Operators accepted	Example rejection
Text	industry, current_title	text	equals on industry returns Operator does not support field type 'text'
Typed (string, number)	headquarters_country_code, city, employees_in_linkedin, followers	equals, in, range	text on headquarters_country_code returns Operator does not support field type 'string'. Supported types: text

Field names differ by category. The full lists are on Company search and People search. A field that appears in view output is not necessarily searchable: people connections is returned in summary but cannot be used in a range condition.

Which queries are rejected?

Business Search validates the request before running a search. A rejected request returns HTTP 400 with a message naming the property at fault. The request is not searched and not billed.

Rule	What happens
query must be an object in Ludicrous and a string in Instant and Smart	HTTP 400: request: "query" must be of type object or request: "query" must be a string
equals, in and range work only on typed fields	HTTP 400: Operator does not support field type 'text'
text works only on text fields	HTTP 400: Operator does not support field type 'string'. Supported types: text
mode inside text must be an accepted value	HTTP 400 listing the accepted values

Rejections outside the query object, such as an invalid limit, an unknown view field or a natural-language query longer than 200 characters, are listed under Why was a request rejected? on the Business Search error codes page.

Frequently asked questions

Does the query object change between company and people searches?

The operators are identical. The field names are not. The company category uses industry, headquarters_country_code and linkedin_followers. The people category uses current_title, country_code and followers. See Company search and People search.

Can I use a structured query with Instant or Smart mode?

No. ludicrous takes a structured object, and instant and smart take a natural-language string. A mismatch is rejected with HTTP 400: an object in Instant returns request: "query" must be a string, and a string in Ludicrous returns request: "query" must be of type object. See What is Business Search?.

Related

• Company search
• People search
• Business Search field views
• Business Search error codes
• What is Business Search?