> ## 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 Syntax Reference > The complete tested grammar of Protect's query language — every operator, every field path, every value type This page is the canonical reference. Every field name and operator was verified against the live product autocomplete and tested with running queries. ## Grammar In plain English: a query is **one or more `field:value` clauses joined by `AND` / `OR`, optionally prefixed with `NOT`**. Field names can be dotted (`system.crowdstrike.deployed`). Values are typed — strings, booleans, enums, or relative dates like `now-7d`. Concrete examples: * `os:Windows` — one clause * `os:Windows AND tags:End-User` — two clauses joined by `AND` * `tags:End-User AND NOT system.crowdstrike.deployed:true` — three-clause query with negation * `lastOnline:now-7d` — relative time (devices seen in the last 7 days) The formal grammar (EBNF) — useful as a reference for tooling, but the four examples above cover real-world usage: ```text theme={null} Query := Clause ( Connector Clause )* Clause := Field ":" Value | "NOT" Clause Connector := "AND" | "OR" Field := identifier ( "." identifier )* Value := | | | | Duration := "now-" Number ("h" | "d" | "w" | "y") ``` Read each line as a definition: * `Query` is one `Clause`, followed by zero or more `Connector + Clause` pairs * `Clause` is either `field:value` or `NOT` followed by another clause * `Connector` is the literal word `AND` or `OR` * `Field` is a dotted identifier path (`hostName`, `system.crowdstrike.deployed`) * `Value` is one of the supported types * `Duration` is `now-` followed by a number and a unit suffix (`h`, `d`, `w`, `y`) ## Operators | Operator | Purpose | Example | | -------- | ------------------------- | ------------------------------ | | `:` | Match (the only operator) | `os:Windows` | | `AND` | Logical AND | `os:Windows AND tags:End-User` | | `OR` | Logical OR | `tags:Server OR tags:VM` | | `NOT` | Negate a clause | `NOT tags:Stock` | **There is no `=`, `<`, `>`, `<=`, `>=`, `contains`, `starts with`, `ends with`, `IN`, or `is empty` operator.** The grammar is intentionally minimal — composition is via `AND` / `OR` / `NOT`. ## Value types | Type | Format | Example | | | | | ------- | ---------------------------------------- | --------------------------------------------------- | - | --------------- | ---------------------- | | String | bare or quoted (use bare when no spaces) | `Windows`, `"Windows 11"` | | | | | Enum | one of the field's allowed values | `os:Windows` (allowed: `Windows`, `MacOs`, `Linux`) | | | | | Boolean | `true` or `false` | `system.crowdstrike.deployed:false` | | | | | Time | \`now-Nh | d | w | y\` or ISO date | `now-7d`, `2026-01-01` | | IP | IPv4 / IPv6 | `192.168.1.1` | | | | ## Confirmed top-level fields These are the device fields surfaced by the search bar's autocomplete on `/devices`. Field names, types, and descriptions are taken verbatim from the in-product hints. ### Identity & basics | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------- | | `hostName` | string | The name of the device | | `id` | string | A unique identifier generated by ThreatAware | | `os` | enum | The family of the OS of the device, either `Windows`, `MacOs`, or `Linux` | | `osVersion` | string | The version of the operating system of the device | | `macAddress` | string | The current hardware address of the active network adapter | | `privateIp` | ip | The current Private IP address of the active network adapter | | `publicIp` | ip | The current Public IP address of the network the user is on | ### Time fields | Field | Type | Description | | ------------ | ---- | ------------------------------------------------------------------- | | `lastLogin` | time | The last time a login was registered on the device | | `lastOnline` | time | The last time any activity was recorded on the device by any system | ### User association | Field | Type | Description | | --------------------- | ------ | ------------------------------------------------------------ | | `lastUser.email` | string | The matched email of the last user on the device | | `lastUser.name` | string | The name of the last user on the device | | `lastUser.department` | string | The department, if available, of the last user on the device | | `lastUser.jobTitle` | string | The job title, if available, of the last user on the device | ### Location | Field | Type | Description | | ---------------------- | ----------- | -------------------------------------------------------------------- | | `location.country` | string | The country the user is currently in, based on last Public IP | | `location.countryCode` | string | The country code the user is currently in, based on last Public IP | | `location.city` | string | The approximate city the user is nearest to, based on last Public IP | | `location.coordinates` | coordinates | The approximate coordinates of the user, based on last Public IP | ### Metadata (hardware, identifiers) All `metadata.*` fields are strings: | Field | Notes | | ---------------------------- | ------------------------------------------------------------------- | | `metadata.architecture` | | | `metadata.cpu_cores` | | | `metadata.cpu_model` | | | `metadata.cpu_speed` | | | `metadata.device_type` | Tenant-defined enum — see [Device types](#device-type-values) below | | `metadata.disk_type` | | | `metadata.domain` | | | `metadata.free_storage` | | | `metadata.manufacturer` | | | `metadata.model` | | | `metadata.os_build` | | | `metadata.risk` | | | `metadata.serial_number` | | | `metadata.servicenow_id` | | | `metadata.servicenow_status` | | | `metadata.total_ram` | | | `metadata.total_storage` | | | `metadata.video_card` | | | `metadata.warranty_expiry` | | ### Tags | Field | Type | Description | | ------ | ------ | --------------------------------------------------- | | `tags` | string | Dynamic or user defined tags that have been applied | Tag values are whatever you've defined in [Settings → Tags](/settings/tags). For example: `End-User`, `EMEA`, `NA`, `APAC`, `Mac`, `BYOD`, `Server`, `VM`, `Stock`. ### Nested collections These accept dot-notation drill-down or specialised query forms: | Field | Notes | | ---------- | -------------------------------------------------------------- | | `issues` | All unresolved issues on a device | | `software` | All installed software on a device | | `systems` | All connected systems and security tools installed on a device | ### Vitals (`system.*` prefix) Each connected integration is exposed as a prefix with four boolean sub-fields: ```text theme={null} system..deployed boolean system..functioning boolean system..configuredCorrectly boolean system..required boolean ``` Integration prefixes include: | Prefix | Integration | | ------------------------------- | -------------------------------------- | | `system.azure_ad` | Microsoft Entra ID / Azure AD | | `system.crowdstrike` | CrowdStrike Falcon | | `system.jamf` | JAMF Pro | | `system.microsoft_defender_atp` | Microsoft Defender for Endpoint | | `system.microsoft_intune` | Microsoft Intune | | `system.onprem_ad` | On-premises Active Directory | | `system.sccm` | Microsoft SCCM / Configuration Manager | | `system.servicenow` | ServiceNow | | `system.zscaler_client` | ZScaler Client | Your tenant's set depends on which integrations are connected. ## Device-type values `metadata.device_type` is an enum, but values are tenant-defined rather than universal. For example: * `EndUser` * `EndUser - EOL` * `EndUser - Legacy` * `Macs - OS X` * `Windows Server` * `Linux` * `Unmanaged (BYOD) - Default Naming Convention` * `Unmanaged - Review (potential corportate)` Your tenant's list may differ. Use autocomplete (`metadata.device_type:` and look at suggestions) to see your tenant's values. ## Time values The autocomplete after `:` on a `time` field offers: | Value | Meaning | | ------------ | ---------------- | | `now-1h` | 1 hour ago | | `now-1d` | 1 day ago | | `now-1w` | 1 week ago | | `now-7d` | 7 days ago | | `now-30d` | 30 days ago | | `now-1y` | 1 year ago | | `2026-01-01` | ISO date literal | How time matching is interpreted by the system (within range vs exact) is not exposed in autocomplete. Test with known data before relying on it in saved views. ## Verified test results Example queries (with the `Active` filter applied). Counts are illustrative and will vary by tenant: | Query | Result | | ----------------------------------- | ------------------------------------------------- | | `os:Windows` | 1,033 / 1,229 | | `tags:End-User AND os:Windows` | 870 / 1,229 | | `tags:Stock` | 7 / 1,229 | | `tags:Server OR tags:VM` | 79 / 1,229 | | `system.crowdstrike.deployed:false` | 146 / 1,229 | | `os=Windows` (wrong operator) | 0 / 1,229 — silently returns no matches, no error | ## Worked examples ```text theme={null} tags:End-User AND system.crowdstrike.required:true AND system.crowdstrike.deployed:false ``` End-User devices that should have CrowdStrike but don't. ```text theme={null} system.crowdstrike.deployed:true AND system.crowdstrike.functioning:false ``` CrowdStrike present but not actively reporting — silent failure. ```text theme={null} system.microsoft_intune.functioning:true AND system.microsoft_intune.configuredCorrectly:false ``` Intune working but config drift. ```text theme={null} NOT tags:Stock AND NOT tags:BYOD AND system.crowdstrike.required:false ``` Devices that should be in scope for EDR but aren't required. ## Saved views Build a query → click the floppy icon in the footer → name → choose visibility (Private / Team / Everyone). Saved views appear in the **Default View ▾** dropdown top-right and are the basis for [Scheduled Reports](/scheduled-reports). ## What's not in the grammar Tested against autocomplete and Enter-submit. The following patterns either silently don't filter or aren't suggested: * Comparison operators `<`, `>`, `<=`, `>=` * `contains`, `starts with`, `ends with` * `IN (...)` / `NOT IN` * `is empty` / `is not empty` If you need expression power beyond `AND`/`OR`/`NOT` over `field:value`, use the [API](/api-reference/introduction). ## See also Introductory walkthrough Where you'll write most queries Same syntax drives tag rules