> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zdlake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query builder

> Compose recursive AND/OR conditions for entity searches.

Use `where` to filter any search endpoint. Its shape follows a recursive condition-group model: each group combines child conditions with `and` or `or`, and every child can be another group.

```json theme={null}
{
  "where": {
    "logical_operator": "and",
    "conditions": [
      { "field": "cvss", "operator": "gte", "value": 9 },
      {
        "logical_operator": "or",
        "conditions": [
          { "field": "cisa_kev", "operator": "equals", "value": true },
          {
            "field": "exploited_as_zero_day",
            "operator": "equals",
            "value": true
          }
        ]
      }
    ]
  }
}
```

This evaluates as:

```text theme={null}
cvss >= 9 AND (cisa_kev = true OR exploited_as_zero_day = true)
```

`q`, `id`, and the entity implied by a typed endpoint compose with `where` as an outer `AND`.

## Groups and conditions

A group has two fields:

| Field | Type | Description |
| - | - | - |
| `logical_operator` | `and` or `or` | How the group combines its children |
| `conditions` | array | One or more conditions or nested groups |

A leaf condition has `field`, `operator`, and usually `value`. `exists` and `not_exists` omit `value`.

Requests may contain at most 20 leaf conditions and may nest groups up to eight levels deep.

## Operators

| Operator | Value | Fields |
| - | - | - |
| `equals`, `not_equals` | scalar | string, enum, number, date, boolean |
| `in`, `not_in` | scalar array | string, enum, number |
| `contains`, `not_contains` | string | string and array text |
| `gt`, `gte`, `lt`, `lte` | number or `YYYY-MM-DD` | number and date |
| `array_has_any` | string array | array |
| `array_has_all` | string array | array |
| `not_array_has_any` | string array | array |
| `exists`, `not_exists` | no value | any field |

## Fields

The runtime and OpenAPI schema share this field list. “Commonly populated for” describes the normalized records that usually carry a value; it is not a separate syntax per endpoint.

| Field | Type | Commonly populated for |
| - | - | - |
| `id` | string | all entities |
| `entity` | enum | cross-entity `/search` |
| `alias` | string array | vulnerabilities, advisories, weaknesses, attack patterns |
| `record_state` | enum | all entities |
| `published_at` | date | vulnerabilities, advisories, weaknesses |
| `updated_at` | date | all entities |
| `cvss` | number from `0` to `10` | vulnerabilities |
| `epss` | number from `0` to `1` | vulnerabilities |
| `exploitation_status` | enum | vulnerabilities |
| `exploited_as_zero_day` | boolean | vulnerabilities |
| `cisa_kev` | boolean | vulnerabilities |
| `weakness` | string array | vulnerabilities, advisories, attack patterns |
| `software_kind` | string array | software |
| `ecosystem` | string array | vulnerabilities, advisories, software with kind `package` |
| `affected_software` | string array | vulnerabilities, advisories |

Entity values are `vulnerability`, `advisory`, `software`, `weakness`, and `attack-pattern`. Use canonical identifiers such as `CVE-2021-44228`, `CWE-79`, and `pkg:npm/lodash`.

## Cross-entity example

```bash theme={null}
curl "https://api.zdlake.com/search" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "logical_operator": "or",
      "conditions": [
        {
          "logical_operator": "and",
          "conditions": [
            { "field": "entity", "operator": "equals", "value": "vulnerability" },
            { "field": "cvss", "operator": "gte", "value": 9 }
          ]
        },
        {
          "logical_operator": "and",
          "conditions": [
            { "field": "entity", "operator": "equals", "value": "software" },
            { "field": "software_kind", "operator": "equals", "value": "package" },
            { "field": "ecosystem", "operator": "array_has_any", "value": ["npm"] }
          ]
        }
      ]
    },
    "limit": 50
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.