Query Spec

Every structured search sends a where tree and an optional page size. The tree is built from two things: composers, which combine conditions, and leaves, which test one field.

{
  "where": {"all": [
    {"field": "<name>", "<operator>": <value>}
  ]},
  "size": 25
}

A leaf names one field and applies one operator to it. Everything else in the grammar is a way of arranging leaves.

A query must carry at least one condition. An empty tree is refused with At least one search condition is required rather than returning the whole corpus.

Composers nest, so an all can contain an any that contains a not. This example asks for a company in the United States that is either mid-sized or well funded, and is not publicly listed.

{
  "where": {"all": [
    {"field": "hq_country", "match": "United States"},
    {"any": [
      {"field": "employees_count", "gte": 200},
      {"field": "last_funding_round_amount_raised", "gte": 50000000}
    ]},
    {"not": {"field": "type", "eq": "Public Company"}}
  ]},
  "size": 50
}

employees_count below is a company field. Field names are not shared between the three datasets, so a leaf only means anything against the endpoint that publishes its field.

// Wrong. Two operators in one leaf.
{"field": "employees_count", "gte": 50, "lte": 500}

// Right. Two leaves, combined.
{"all": [
  {"field": "employees_count", "gte": 50},
  {"field": "employees_count", "lte": 500}
]}

Operators are also matched to the kind of field. Numeric and date fields accept gte, lte, and exists only; text and category fields accept eq, in, match, and exists. Asking a numeric field for eq, or passing "50" as a string where a number is expected, is refused rather than reinterpreted. Each dataset page lists the operators its fields accept.

exists has one form. To ask for records where a field is absent, wrap the leaf: {"not": {"field": "salary_min", "exists": true}}.

A text field matches text, where every word in your value has to appear. An exact field compares the whole stored value, character for character, so "director" matches nothing where "Director" matches.

Several fields draw from a fixed list, and the lists live with the fields rather than here: People, Jobs and Companies each carry the values for their own. One copy per value, on the page you were already reading to find the field.

Several of those values contain commas — Oil, Gas, and Mining is one value, not three — which is the other half of why they are shown in a table there rather than run together in a sentence here.

true means the same thing on all six of them. false does not, because a field that is only written when it is true has no false to match: it is absent instead, and absent is not a value you can ask for with eq.

// Matches nothing: there is no stored false to match.
{"where": {"field": "is_b2b", "eq": false}}

// The companies that are not B2B.
{"where": {"not": {"field": "is_b2b", "eq": true}}}

Date fields take an absolute YYYY-MM-DD or a relative value that the server resolves to an absolute day before the query runs. That means a saved query keeps meaning "the last 30 days" instead of freezing on the day it was written.

{"where": {"all": [
  {"field": "posted", "gte": "now-30d"},
  {"field": "employment_type", "match": "Contract"}
]}}

A relative value on a field that is not a date is refused. The date fields are marked as such in each dataset's field table.

A profile holds many jobs and many degrees. Without a scope, two conditions can be satisfied by two different records: one job at Google, and a separate job as a director somewhere else. A scope forces both to land on the same record.

// "Was a director at Google": both conditions, one job.
{"where": {"has_experience": {"all": [
  {"field": "company_name", "match": "Google"},
  {"field": "level", "eq": "Director"}
]}}}

// "Worked at Google, and was a director somewhere":
// two conditions, possibly two different jobs.
{"where": {"all": [
  {"field": "company_name", "match": "Google"},
  {"field": "level", "eq": "Director"}
]}}

People are the only entity with scopes. A job document is one job and a company document is one company, so there is nothing to group. Scopes also do not nest inside one another, and each scope accepts only the fields that belong to it.

A search response includes next while more results remain. Pass that value back as after, with the same where tree, to get the following page. On the last page next is absent rather than empty, so its absence is how you know you are done.

// Page 1 response
{"data": {"job_ids": ["Jb71xKcAoP"], "next": "WzE3MjQwMDAwMDAsIkpiNzF4S2NBb1AiXQ"}}

// Page 2 request
{"where": {"all": [{"field": "title", "match": "data engineer"}]},
 "size": 100,
 "after": "WzE3MjQwMDAwMDAsIkpiNzF4S2NBb1AiXQ"}

A field name that is not in the dataset's list is refused. The three datasets do not share one vocabulary, so check the name against the page for the endpoint you are calling. A translation failure costs nothing: the query is checked before any Credit is charged.

The grammar is shared; the vocabulary is not. Each dataset publishes its own field list with the operators each field accepts, and a name from one dataset is not valid in another.

What a search can filter on and what a detail response can return are two different lists. A field may be returnable without being queryable, and the query vocabulary is deliberately the smaller of the two.