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

# Query Language

> The unified search syntax used across Devices, Users, Issues, Software, Logic Engine, and Action triggers

This page is the operator-level introduction. The full grammar with all confirmed field paths is at [Reference → Query Syntax](/reference/query-syntax).

## Where queries work

| Surface                           | What you can query                                            |
| --------------------------------- | ------------------------------------------------------------- |
| **Device Explorer command bar**   | Devices, with natural-language fallback in AI-enabled tenants |
| **Devices** grid search           | The full device schema                                        |
| **User Inventory** search         | User fields and accounts                                      |
| **Software Inventory** search     | Software fields (scoped by the chosen tag)                    |
| **Issues** search                 | Issue, severity, product, device, tag                         |
| **Action Center → Create Action** | Same syntax used to define an Action's trigger set            |
| **Tag Logic Engine**              | Same syntax used to drive dynamic tag membership              |

The same grammar across every surface means one mental model.

## Shape

Every clause is:

```text theme={null}
<field>:<value>
```

The operator is **`:`** (not `=`). Combine clauses with `AND`, `OR`, and `NOT`:

```text theme={null}
os:Windows AND tags:End-User
```

```text theme={null}
tags:Server OR tags:VM
```

```text theme={null}
NOT tags:Stock
```

Hit **Enter** to apply. Saved queries become \*\*Custom \*\*\* in the view dropdown until you click **Save View** (the floppy icon in the footer).

## Value types

Values are typed — autocomplete shows what's valid per field:

| Type           | Example values                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `string`       | `End-User`, `Windows 11`, `john.smith@company.com`                                                                              |
| `boolean`      | `true`, `false`                                                                                                                 |
| `enum`         | (e.g. `os` accepts `Windows`, `MacOs`, `Linux` only)                                                                            |
| `time`         | `now-1h`, `now-1d`, `now-7d`, `now-30d`, `now-1y`, ISO date like `2026-01-01`                                                   |
| `ip`           | IPv4 / IPv6                                                                                                                     |
| `string` (tag) | Any tag defined in [Settings → Tags](/settings/tags) — `End-User`, `EMEA`, `NA`, `APAC`, `Mac`, `BYOD`, `Server`, `VM`, `Stock` |
| `prefix`       | Use `.` to drill into nested fields, e.g. `system.crowdstrike.deployed`                                                         |
| `nested`       | Sub-collections like `issues`, `software`, `systems`                                                                            |

## Autocomplete

The search input autocompletes both **field names** and **values**. As you type, it suggests:

* Matching field names (with type and description)
* After `:`, the valid values for that field

So you can build queries fully via autocomplete — type a few characters, arrow-select, repeat.

## Verified examples

Example queries:

<Tabs>
  <Tab title="OS family">
    ```text theme={null}
    os:Windows
    ```

    Filters to Windows devices. `os` is an enum of `Windows`, `MacOs`, `Linux`.
  </Tab>

  <Tab title="Tag scope">
    ```text theme={null}
    tags:End-User
    ```

    Devices carrying the `End-User` tag. The field is `tags` (plural).
  </Tab>

  <Tab title="Combine">
    ```text theme={null}
    tags:End-User AND os:Windows
    ```

    Both conditions must hold.
  </Tab>

  <Tab title="Either-or">
    ```text theme={null}
    tags:Server OR tags:VM
    ```

    Devices carrying either tag.
  </Tab>

  <Tab title="Negation">
    ```text theme={null}
    NOT tags:Stock
    ```

    Devices that do NOT carry the `Stock` tag.
  </Tab>

  <Tab title="Vital state">
    ```text theme={null}
    system.crowdstrike.deployed:false
    ```

    Devices where CrowdStrike is not deployed. Each integration exposes `.deployed`, `.functioning`, `.configuredCorrectly`, `.required` as booleans.
  </Tab>
</Tabs>

## Vital states are booleans

A common source of confusion: Vital state isn't a single string. Each integration exposes four boolean fields per device:

| Field                                      | Meaning                                                        |
| ------------------------------------------ | -------------------------------------------------------------- |
| `system.<integration>.required`            | This control is required for this device (driven by tag rules) |
| `system.<integration>.deployed`            | The control is present                                         |
| `system.<integration>.functioning`         | The control is actively reporting                              |
| `system.<integration>.configuredCorrectly` | The control's configuration matches your policy                |

Compose them with `AND` for the state you want:

| Want                                      | Query                                                                                                                                                           |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| All Healthy CrowdStrike devices           | `system.crowdstrike.required:true AND system.crowdstrike.deployed:true AND system.crowdstrike.functioning:true AND system.crowdstrike.configuredCorrectly:true` |
| CrowdStrike not deployed                  | `system.crowdstrike.required:true AND system.crowdstrike.deployed:false`                                                                                        |
| Broken CrowdStrike agent (silent failure) | `system.crowdstrike.deployed:true AND system.crowdstrike.functioning:false`                                                                                     |
| Misconfigured but working                 | `system.crowdstrike.functioning:true AND system.crowdstrike.configuredCorrectly:false`                                                                          |

## Real integration prefixes

Integrations that expose `system.*` Vitals include:

* `system.azure_ad`
* `system.crowdstrike`
* `system.jamf`
* `system.microsoft_defender_atp`
* `system.microsoft_intune`
* `system.onprem_ad`
* `system.sccm`
* `system.servicenow`
* `system.zscaler_client`

Your tenant's list reflects whichever integrations are connected.

## Saved views

Build a query → click the **Save** icon in the footer → name it → it appears in the view dropdown next to \*\*Custom \*\*\*. Saving lets you reuse the query and schedule it as a [report](/scheduled-reports).

## Natural language

In AI-enabled tenants, the command bar in [Device Explorer](/device-explorer) accepts plain English. The AI translates intent into a structured query you can then edit:

> "show me windows devices in End-User that don't have CrowdStrike"

becomes something like:

```text theme={null}
os:Windows AND tags:End-User AND system.crowdstrike.deployed:false
```

Always read the translated query before saving — the AI is good but not infallible.

## Tips

<Tip>
  **Always start with autocomplete.** Type the field name slowly — the description tooltip tells you the type and whether there's an enum. Saves a lot of guessing.
</Tip>

<Tip>
  **Compose Vitals four-way.** Don't fight a missing `Healthy` literal. Embrace the four-boolean model — it's strictly more expressive than a single state string.
</Tip>

<Tip>
  **Save the queries you write more than twice.** Saved views appear in the Default View dropdown and are the basis for [Scheduled Reports](/scheduled-reports).
</Tip>

## What's not in the query language

Based on autocomplete-only verification, these patterns are **not** supported by the current grammar:

* `<`, `>`, `<=`, `>=` numeric / time comparisons (autocomplete offers value tokens, not comparators)
* `contains`, `starts with`, `ends with` (string operators)
* `IN (...)` lists — use `OR` instead
* `is empty` / `is not empty`

If you need a comparison that the operator `:` can't express directly, build it via composition (multiple clauses with `AND`/`OR`/`NOT`) or use the [API](/api-reference/introduction) for richer filtering.

## See also

<CardGroup cols={3}>
  <Card title="Query Syntax (full reference)" icon="book" href="/reference/query-syntax">
    Every confirmed field path
  </Card>

  <Card title="Tags & Logic Engine" icon="tag" href="/tags-and-logic-engine">
    Same syntax drives tag rules
  </Card>

  <Card title="Devices" icon="laptop" href="/device-management">
    Where you'll spend most query time
  </Card>
</CardGroup>