Reference: Filter syntax

Filter query requests to constrain records returned in a response, or mutation requests to constrain a created group's endpoint membership, or a created action's targeted groups.

Filters compare a field value or group membership, passed in the request, to the corresponding field value or group membership on a record. If the record matches the filter, the record is added to the collection.

Filters generally evaluate one of the following comparisons:

  • path and value - a record field and the associated value

  • sensor and value - a sensor evaluation and associated result value, compared to the record

  • memberOf - endpoint group membership

Filters that compare values use relational operators, enumerated in the op field. If a filter does not define op, the default is EQ . For more information on available relational operators, see FieldFilterOp in the Documentation Explorer pane of the query explorer.

Relational operators might be restricted to certain data types, data sources, or field data type comparisons.

The following relational operators are available for filters, subject to restrictions:

  • CONTAINS - for string data type fields, the record field value contains the filter value

  • ENDS_WITH - for string data type fields, the record field value ends with the filter value

  • EQ - the record field value equals the filter value

  • GT - for data types that can be compared, the record field value is greater than the filter value

  • GTE - for data types that can be compared, the record field value is greater than or equal to the filter value

  • LT - for data types that can be compared, the record field value is less than the filter value

  • LTE - for data types that can be compared, the record field value is less than or equal to the filter value

  • MATCHES - for string data type fields, the record field value matches the filter value; the filter value is evaluated as a Perl syntax regular expression

  • READ_AFTER - for certain data sources, the record field value is read after the filter date and time value

  • STARTS_WITH - for string data type fields, the record field value starts with the filter value

  • UPDATED_AFTER - for certain data sources, the record field value is updated after the filter date and time value

Filters also use logical operators to evaluate whether a filter or combination of filters is true or false.

  • negated (NOT operator) - If a filter contains negated: true, records that do not match a filter statement are included in a collection. If a filter contains negated: true, records that match a filter statement are included in a collection. The default is negated: false (matching records belong to the collection).

  • any (AND, OR operators) - If a filter includes multiple filter statements and contains any: false, a record must match every field filter to be included in the collection. If a filter includes multiple filter statements and contains any: true, a record belongs to the collection if it matches one or more of the field filters. The default is any: false (a record must match every field filter).

Query filter syntax does not support the get statement functionality that Interact supports to retrieve specific fields and information from records in the returned collection. Query filters function like the from clause when asking a question, to limit the records in the returned collection. Depending on the query, you might retrieve field information as object metadata. When querying endpoints, use the endpoints.edges.node.sensorReadings field to retrieve sensor results for endpoints.

Computer group creation filter syntax

Filter computer groups when creating actions or scheduled actions, to target certain computer groups, or when constraining endpoint membership in a created computer group.

Computer group creation and action creation mutations support the following filter fields:

  • memberOf

  • sensor and value

For more information on syntax, see computerGroupFilter in the Documentation Explorer pane of the query explorer.

ClosedComputer group membership

You can define computer group membership based on named computer groups. Define a filter object using the syntax:

{memberOf: {name: "computer-group-name"}}

For example, the following request creates a computer group whose members are endpoints that are members of the All Linux computer group:

Copy
mutation createComputerGroup($name: String!, $filterGroup: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {memberOf: {name: $filterGroup}}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the computer group name variable in the QUERY VARIABLES panel:

Copy
{
    "name": "Example computer group",
    "filterGroup": "All Linux",
    "mrEnabled": false
}

The following request creates an action that targets endpoints that are members of the All Linux computer group:

Copy
mutation createAction($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $cgName: String) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {targetGroup: {filter: {memberOf: {name: $cgName}}}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the computer group name variable in the QUERY VARIABLES panel:

Copy
{
  "comment": "Example created action",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example created action",
  "packageID": 12345,
  "cgName": "All Linux"
}

ClosedSensors

You can define computer group membership based on readings of arbitrary named sensors. Define a filter object using the syntax:

{sensor: {name: "sensor-name", negated: "boolean", op: "operator", value: "filter-value"}}

Only the name and value arguments are required. If you do not define the negated argument, the default value is false. If you do not define the op argument, the default value is EQ (equals).

For example, the following request creates a group based on the Is Virtual sensor returning a value of false for endpoints, and returns only those endpoints:

Copy
mutation createComputerGroupVirtual($name: String!, $sensor: String, $negated: Boolean!, $op: FieldFilterOp!, $value: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {sensor: {name: $sensor}, negated: $negated, op: $op, value: $value}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name and value variables in the QUERY VARIABLES panel:

Copy
{
  "name": "Example computer group",
  "sensor": "Is Virtual",
  "negated": false,
  "op": "EQ",
  "value": "false",
  "mrEnabled": false
}

The following request creates an action that targets endpoints based on the Is Virtual sensor returning a value of false for endpoints, targeting only those endpoints:

Copy
mutation createActionVirtualEndpoints($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $sensor: String, $negated: Boolean!, $op: FieldFilterOp!, $value: String) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {targetGroup: {filter: {sensor: {name: $sensor}, negated: $negated, op: $op, value: $value}}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name and value variables in the QUERY VARIABLES panel:

Copy
{
  "comment": "Example created action",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example created action",
  "packageID": 12345,
  "sensor": "Is Virtual",
  "negated": false,
  "op": "EQ",
  "value": "false"
}

ClosedParameterized sensors

You can create a computer group based on parameterized sensors. Define a filter object using the syntax:

{sensor:
  {name: "sensor-name",
  params:[
    {name: "parameter-1-name", value: "parameter-1-value"},
    {name: "parameter-2-name", value: "parameter-2-value"},
    {name: "parameter-n-name", value: "parameter-n-value"}
  ]
},
  value: "filter-value"
}

Add a params name/value object for every parameter.

For example, the following request creates a computer group whose membership is based on the Custom Tag Exists sensor. Only endpoints tagged with the custom tag the-tag are returned by the sensor, and are members of this computer group:

Copy
mutation createComputerGroupTag($name: String!, $sensorName: String, $paramName: String!, $paramValue: String!, $sensorValue: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {sensor: {name: $sensorName, params: [{name: $paramName, value: $paramValue}]}, value: $sensorValue}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, value, and parameter variables in the QUERY VARIABLES panel:

Copy
{
  "name": "Example tagged endpoints group",
  "sensorName": "Custom Tag Exists",
  "sensorValue": "true",
  "paramName": "tag",
  "paramValue": "the-tag",
  "mrEnabled": false
}

The following request creates an action that targets a computer group whose membership is based on the Custom Tag Exists sensor. Only endpoints tagged with the custom tag the-tag are returned by the sensor, and are members of this targeted computer group:

Copy
mutation createActionTargetTags($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $sensorName: String, $paramName: String!, $paramValue: String!, $sensorValue: String) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {targetGroup: {filter: {sensor: {name: $sensorName, params: [{name: $paramName, value: $paramValue}]}, value: $sensorValue}}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, value, and parameter variables in the QUERY VARIABLES panel:

Copy
{
  "comment": "Example action tagged endpoints",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example action tagged endpoints",
  "packageID": 12345,
  "sensorName": "Custom Tag Exists",
  "sensorValue": "true",
  "paramName": "tag",
  "paramValue": "the-tag"
}

ClosedSingle column from multi-column sensors

You can create a computer group based on a single column from multi-column sensors by specifying the column name. Define a filter object using the syntax:

{sensor: {
  name: "sensor-name",
  column: "sensor-column-name"},
  value: "filter-value"}
}

For example, the following request creates a computer group based on the CPU Details sensor returning endpoints with an Intel CPU. Those endpoints are members of the computer group:

Copy
mutation createComputerGroupIntel($name: String!, $sensorName: String, $sensorColumn: String, $sensorValue: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {sensor: {name: $sensorName, column: $sensorColumn}, value: $sensorValue}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "name": "Example computer group Intel",
  "sensorName": "CPU Details",
  "sensorColumn": "CPU",
  "sensorValue": "Intel",
  "mrEnabled": false
}

The following request creates an action that targets endpoints based on the CPU Details sensor returning endpoints with an Intel CPU. Those endpoints are members of the computer group and targeted by this action:

Copy
mutation createActionTargetIntel($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $sensorName: String, $sensorColumn: String, $sensorValue: String) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {targetGroup: {filter: {sensor: {name: $sensorName, column: $sensorColumn}, value: $sensorValue}}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "comment": "Example action Intel endpoints",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example action Intel endpoints",
  "packageID": 12345,
  "sensorName": "CPU Details",
  "sensorColumn": "CPU",
  "sensorValue": "Intel"
}

ClosedMultiple columns from multi-column sensors

If you want to create a computer group based on multiple columns of each row of a multi-column sensor, define a filter.filters list, then define a list element for each column filter, using the following syntax:

filters: [
  {sensor: {column: "column-1-name"}, value: "column-1-value"},
  {sensor: {column: "column-2-name"}, value: "column-2-value"},
  {sensor: {column: "column-n-name"}, value: "column-n-value"}
]

You can only use a single level of child filters, and can only use the default EQ operator.

For example, the following request creates a computer group based on the CPU Details sensor returning endpoints with 4 total cores and an Intel CPU:

Copy
mutation createComputerGroup4CoreIntel($name: String!, $sensorName: String, $sensorColumn1: String, $sensorValue1: String, $sensorColumn2: String, $sensorValue2: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {sensor: {name: $sensorName}, filters: [{sensor: {column: $sensorColumn1}, value: $sensorValue1}, {sensor: {column: $sensorColumn2}, value: $sensorValue2}]}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "name": "Example computer group 4 core Intel",
  "sensorName": "CPU Details",
  "sensorColumn1": "CPU",
  "sensorValue1": "Intel",
  "sensorColumn2": "Total Cores",
  "sensorValue2": "4",
  "mrEnabled": false
}

In this form, the sensor is identified in the top filter and the columns are identified in the child filters. You can only use a single level of child filters, and can only use the default EQ operator.

The following request creates an action that targets endpoints based on the CPU Details sensor returning endpoints with 4 total cores and an Intel CPU:

Copy
mutation createActionTarget4CoreIntel($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $sensorName: String, $sensorColumn1: String, $sensorValue1: String, $sensorColumn2: String, $sensorValue2: String) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {targetGroup: {filter: {sensor: {name: $sensorName}, filters: [{sensor: {column: $sensorColumn1}, value: $sensorValue1}, {sensor: {column: $sensorColumn2}, value: $sensorValue2}]}}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "comment": "Example action 4 core Intel endpoints",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example action Intel endpoints",
  "packageID": 12345,
  "sensorName": "CPU Details",
  "sensorColumn1": "CPU",
  "sensorValue1": "Intel",
  "sensorColumn2": "Total Cores",
  "sensorValue2": "4"
}

Computer group query filter syntax

Computer group queries support the following filter fields:

  • filterEnabled

  • managementRightsEnabled

  • type

For more information on syntax, see computerGroupsFilter in the Documentation Explorer pane of the query explorer.

ClosedManual or standard computer group

You can filter based on whether the computer group is standard (membership is based on the results of a sensor filter expression) or manual (membership is based on a manually entered list of computer names or fully qualified domain names (FQDNs)). To retrieve standard computer groups, define a filter object using the syntax:

{type: STANDARD}

To retrieve manual computer groups, define a filter object using the syntax:

{type: MANUAL}

For example, the following request filters and returns computer groups based on type, with the specific type defined in the variable definition:

Copy
query getGroupsByType($type: ComputerGroupType) {
  computerGroups(filter: {type: $type}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

To retrieve manual computer groups, include the following type variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "type": "MANUAL"
}

To retrieve standard computer groups, include the following type variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "type": "STANDARD"
}

ClosedFilter group

You can filter based on whether the computer group is a filter group. To retrieve filter computer groups, define a filter object using the syntax:

{filterEnabled: true}

For example, the following request filters and returns filter groups:

Copy
query getFilterGroups($filterEnabled: Boolean) {
  computerGroups(filter: {filterEnabled: $filterEnabled}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the filter enabled variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{  
  "filterEnabled": true
}

ClosedManagement rights group

You can filter based on whether the computer group is a management rights group. To retrieve management rights computer groups, define a filter object using the syntax:

{managementRightsEnabled: true}

For example, the following request filters and returns management rights groups:

Copy
query getMRGroups($mrEnabled: Boolean) {
  computerGroups(filter: {managementRightsEnabled: $mrEnabled}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the filter enabled variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{  
  "mrEnabled": true
}

Comply query filter syntax

Endpoint queries that request Comply-related information using complianceFindings or cveFindings support the path and value filter fields.

For more information on syntax, see FieldFilter in the Documentation Explorer pane of the query explorer.

ClosedSingle column

You can filter on field values. Define a filter object using one of the following syntaxes:

complianceFindings (filter: 
  {
    path: "field-path",
    op: "operator-value",
    value: "field-value
  }
)

cveFindings (filter: 
  {
    path: "field-path",
    op: "operator-value",
    value: "field-value
  }
)

Use dot notation for sub-fields not at the root level. You can filter the endpoints returned and filter the endpoints based on Comply information in a single request.

For example, the following query retrieves the first endpoint with a compliance finding category of Error and returns that endpoint's associated compliance findings:

Copy
query filterComplianceFindings ($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          complianceFindings (filter: {
            path: "category"
            value: "Error"
          }) {
            category
            id
            profile
            profileVersion
            rule
            ruleId
            standard
            standardVersion
            state
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

ClosedMultiple columns

You can filter on multiple Comply-related columns. Define a filter object using one of the following syntaxes:

complianceFindings (filter: 
  {any: boolean,
    filters: [
      {path: "field-path-1", op: "operator-1", value: "filter-value-1"},
      {path: "field-path-2", op: "operator-2", value: "filter-value-2"},
      {path: "field-path-n", op: "operator-n", value: "filter-value-n"}
    ]
  }
)

cveFindings (filter: 
  {any: boolean,
    filters: [
      {path: "field-path-1", op: "operator-1", value: "filter-value-1"},
      {path: "field-path-2", op: "operator-2", value: "filter-value-2"},
      {path: "field-path-n", op: "operator-n", value: "filter-value-n"}
    ]
  }
)

Use dot notation for sub-fields not at the root level. You can filter the endpoints returned and filter the endpoints based on Comply information in a single request.

For example, the following query retrieves the first endpoint that is a member of the All Mac computer group, with a vulnerability finding cveYear of 2020 and cvssScore value of 5, and returns that endpoint's associated vulnerability findings:

Copy
query filterMacOSEndpointVulnerability($first: Int!) {
  endpoints(first: $first, filter: {memberOf: {name: "All Mac"}}) {
    edges {
      node {
        name
        ipAddress
        compliance {
          cveFindings(
            filter: {any: false, filters: [{path: "cveYear", value: "2020"}, {path: "cvssScore", value: "5"}]}
          ) {
            cveId
            cveYear
            cvssScoreV3
            firstFound
            lastFound
            severityV3
            summary
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Endpoint query filter syntax

Endpoint queries support the following filter fields:

  • memberOf

  • path and value

  • sensor and value

Endpoint queries with sensorReadings support the column and value filter fields to filter based on sensor results.

For more information on syntax, see endpointFieldFilter and SensorValueFilter in the Documentation Explorer pane of the query explorer.

ClosedGeneral Fields

You can filter on field values. Unless otherwise specified, define a filter object using the syntax:

{path: "field-path", value: "field-value"}

Use dot notation for sub-fields not at the root level.

For example, the following request filters and returns only endpoints whose primary user email address is [email protected]:

Copy
query getEndpointsByEmail ($path:String, $value:String){
  endpoints(filter: {path: $path, value: $value}) {
    edges {
      node {
        id
        primaryUser {
          email
        }
      }
    }
  }
}

Include the path and value variables in the QUERY VARIABLES panel:

Copy
{
  "path": "primaryUser.email",
  "value": "[email protected]"
}

ClosedComputer group membership

You can filter on membership in named computer groups, referencing computer group name or ID. To filter by computer group name, define a filter object using the syntax:

{memberOf: {name: "computer-group-name"}}

To filter by computer group ID, define a filter object using the syntax:

{memberOf: {id: "computer-group-id"}}

For example, the following request filters and returns only endpoints that are members of the All Linux computer group, based on name:

Copy
query getLinuxEndpoints ($cgname: String){
  endpoints(filter: {memberOf: {name: $cgname}}) {
    edges {
      node {
        id
      }
    }
  }
}

Include the computer group name variable in the QUERY VARIABLES panel:

Copy
{
  "cgname": "All Linux"
}

The following request filters and returns only endpoints that are members of the computer group with the ID of 123:

Copy
query filterEndpointsComputerGroupID ($id: ID){
  endpoints(filter: {memberOf: {id: $id}}) {
    edges {
      node {
        computerID
        name
        ipAddress
      }
    }
  }
}

Include the computer group ID variable in the QUERY VARIABLES panel:

Copy
{
  "id": 123
}

ClosedSensors

Endpoint queries can filter on readings of arbitrary named sensors. Define a filter object using the syntax:

{sensor: {name: "sensor-name", value: "filter-value"}}

For example, the following request filters based on the Total Memory sensor returning a value of 16384 MB for endpoints, and returns only those endpoints:

Copy
query get16GBMemEndpoints($sensor: String, $value: String) {
  endpoints(filter: {sensor: {name: $sensor}, value: $value}) {
    edges {
      node {
        id
      }
    }
  }
}

Include the sensor name and value variables in the QUERY VARIABLES panel:

Copy
{
  "sensor": "Total Memory",
  "value": "16384 MB"
}

ClosedSensor values updated after a given date

Endpoint queries can filter on sensor values updated after a given date. Define a filter object using the syntax:

{sensor: {name: "sensor-name", op: UPDATED_AFTER, value: "rfc-3339-timestamp"}}

For example, the following request filters based on whether any endpoints had their Total Memory sensor value updated after January 1, 2022:

Copy
query get16GBMemEndpoints($sensor: String, $value: Time) {
  endpoints(filter: {sensor: {name: $sensor}, op: UPDATED_AFTER, value: $value}) {
    edges {
      node {
        id
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel:

Copy
{
  "sensor": "Total Memory",
  "value": "2022-01-01T00:00:00.000Z"
}

ClosedParameterized sensors

You can also filter on parameterized sensors. Define a filter object using the syntax:

{sensor:
  {name: "sensor-name",
  params:[
    {name: "parameter-1-name", value: "parameter-1-value"},
    {name: "parameter-2-name", value: "parameter-2-value"},
    {name: "parameter-n-name", value: "parameter-n-value"}
  ]
},
  value: "filter-value"
}

Add a params name/value object for every parameter.

For example, the following request filters based on the Custom Tag Exists sensor, returning endpoints tagged with the custom tag the-tag, and returns only those endpoints:

Copy
query getEndpointsWithCustomTag($sensorName: String, $sensorValue: String, $paramName: String!, $paramValue: String!) {
  endpoints(
    filter: {sensor: {name: $sensorName, params: [{name: $paramName, value: $paramValue}]}, value: $sensorValue}
  ) {
    edges {
      node {
        id
      }
    }
  }
}

Include the sensor name, value, and parameter variables in the QUERY VARIABLES panel:

Copy
{
  "sensorName": "Custom Tag Exists",
  "sensorValue": "true",
  "paramName": "tag",
  "paramValue": "the-tag"
}

ClosedSingle column from multi-column sensors

You can filter a column from multi-column sensors by specifying the column name. Define a filter object using the syntax:

{sensor: {
  name: "sensor-name",
  column: "sensor-column-name"},
  value: "filter-value"}
}

For example, the following request filters based on the CPU Details sensor returning endpoints with an Intel CPU, and returns only those endpoints:

Copy
query getIntelCPUEndpoints($sensorName: String, $sensorColumn: String, $sensorValue: String) {
  endpoints(
    filter: {sensor: {name: $sensorName, column: $sensorColumn}, value: $sensorValue}
  ) {
    edges {
      node {
        id
      }
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "sensorName": "CPU Details",
  "sensorColumn": "CPU",
  "sensorValue": "Intel"
}

ClosedMultiple columns from multi-column sensors

If you want to select across multiple columns of each row of a multi-column sensor, define a filter.filters list, then define a list element for each column filter, using the following syntax:

filters: [
  {sensor: {column: "column-1-name"}, value: "column-1-value"},
  {sensor: {column: "column-2-name"}, value: "column-2-value"},
  {sensor: {column: "column-n-name"}, value: "column-n-value"}
]

You can only use a single level of child filters, and can only use the default EQ operator.

For example, the following request filters based on the CPU Details sensor returning endpoints with 4 total cores and an Intel CPU, and returns only those endpoints:

Copy
query get4CoreIntelCPUEndpoints($sensorName: String, $sensorColumn1: String, $sensorValue1: String, $sensorColumn2: String, $sensorValue2: String) {
  endpoints(
    filter: {sensor: {name: $sensorName}, filters: [{sensor: {column: $sensorColumn1}, value: $sensorValue1}, {sensor: {column: $sensorColumn2}, value: $sensorValue2}]}
  ) {
    edges {
      node {
        id
      }
    }
  }
}

Include the sensor name, column, and value variables in the QUERY VARIABLES panel:

Copy
{
  "sensorName": "CPU Details",
  "sensorColumn1": "CPU",
  "sensorValue1": "Intel",
  "sensorColumn2": "Total Cores",
  "sensorValue2": "4"
}

In this form, the sensor is identified in the top filter and the columns are identified in the child filters. You can only use a single level of child filters, and can only use the default EQ operator.

ClosedSensor readings

After you filter endpoints, you can filter your results to return data from additional sensors. As a child of the node object, define the sensor reading filter using the following syntax:

sensorReadings
  (sensors: [{name: "sensor-name"}], includeHiddenColumns: boolean) {
    columns {
      sensor {
        name
      }
      name
      values
    }

For example, the following request first filters endpoints and only returns endpoints with Firefox as an installed application, then for each endpoint, returns the results of the Is Linux sensor:

Copy
query GetLinuxFirefoxEndpoints($sensorName1: String, $sensorColumn1: String, $sensorOp1: FieldFilterOp!, $sensorValue1: String, $sensorName2: String!) {
  endpoints(
    filter: {sensor: {name: $sensorName1, column: $sensorColumn1}, op: $sensorOp1, value: $sensorValue1}
  ) {
    edges {
      node {
        name
        ipAddress
        sensorReadings(sensors: [{name: $sensorName2}]) {
          columns {
            sensor {
              name
            }
            name
            values
          }
        }
      }
    }
  }
}

Include the sensor name, column, operator, and value variables in the QUERY VARIABLES panel:

Copy
{
  "sensorName1": "Installed Applications",
  "sensorColumn1": "Name",
  "sensorOp1": "CONTAINS",
  "sensorValue1": "Firefox",
  "sensorName2": "Is Linux"
}

ClosedSingle column from multi-column sensor readings

You can filter a column from sensor readings for multi-column sensors by specifying the column name. Define a filter object using the syntax:

sensorReadings
  (sensors: [{name: "sensor-name", filter: {column: "column-name", op: "operator-value", value: "column-value", restrictOwner: "boolean-value"}}}], includeHiddenColumns: boolean) {
    columns {
      sensor {
        name
      }
      name
      values
    }
  }

You can filter the set of endpoints returned and filter based on the sensor readings in a single request.

For example, the following request retrieves endpoints, then filters based on the Installed Applications sensor returning endpoints with the tar application installed, and is limited to the returned field values, then returns only those endpoints:

Copy
query getEndpointsInstalledTar ($first: Int) {
  endpoints (first: $first){
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", filter: {column: "Name", op: EQ, value: "tar", restrictOwner: false}}]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

ClosedMultiple columns from multi-column sensor readings

If you want to select across multiple columns of each row of multi-column sensor readings, define a filter.filters list, then define a list element for each column filter, using the following syntax:

sensorReadings(
  sensors: [
    {
      name: "sensor-name", 
      filter: { 
       restrictOwner: "boolean-value",
        filters: [
         {column: "column-name-1", op: "operator-value-1", value: "column-value-1"},
         {column: "column-name-2", op: "operator-value-2", value: "column-value-2"},
         {column: "column-name-n", op: "operator-value-n", value: "column-value-n"}]
      }
    }
  ], includeHiddenColumns: boolean
) {
    columns {
      sensor {
        name
      }
      name
      values
    }
  }

You can only use a single level of child filters. You can filter the set of endpoints returned and filter based on the sensor readings in a single request.

For example, the following query retrieves the first 2 endpoints that are members of the All Linux computer group, and returns the application Name and Version columns for only the endpoints that have the tar application version 1.30 installed, based on the results from the Installed Applications sensor.

Copy
query getLinuxEndpointsInstalledTar130 ($first: Int){
  endpoints(first: $first, filter: {memberOf: {name: "All Linux"}}) {
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", 
            filter: { 
              restrictOwner: false,
              filters: [
              {column: "Name", op: EQ, value: "Tar"},
              {column: "Version" op: EQ, value: "1.30"}]
          }
            }]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Package spec query filter syntax

Package spec queries support the path and value filter fields.

For more information on syntax, see FieldFilter in the Documentation Explorer pane of the query explorer.

ClosedSingle filter field

You can filter on a single field value. Unless otherwise specified, define a filter object using the syntax:

{path: "field-path", negated: "boolean", op: "operator", value: "filter-value"}

For example, the following request filters and returns only package spec objects whose name does not contain production:

Copy
query getPackageSpecsFiltered($path: String, $negated: Boolean!, $op: FieldFilterOp!, $value: String) {
  packageSpecs(filter: {path: $path, negated: $negated, op: $op, value: $value}) {
    edges {
      node {
        id
        name
        contentSetName
        command
        commandTimeoutSeconds
        expireSeconds
        params {
          key
          label
          defaultValue
        }
        sensorSourcedParams {
          name
        }
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path": "name",
  "negated": true,
  "op": "CONTAINS",
  "value": "production"
}

ClosedMultiple filter fields

You can filter on multiple field values. Define a filter object using the syntax:

{any: boolean,
  filters: [
    {path: "field-path-1", negated: "boolean-1", op: "operator-1", value: "filter-value-1"},
    {path: "field-path-2", negated: "boolean-2", op: "operator-2", value: "filter-value-2"},
    {path: "field-path-n", negated: "boolean-n", op: "operator-n", value: "filter-value-n"}
  ]

For example, the following request filters and returns only package spec objects whose name does not contain production, and whose content set name contains test:

Copy
query packageSpecsMultipleFilters($path1: String, $negated1: Boolean!, $op1: FieldFilterOp!, $value1: String, $path2: String, $negated2: Boolean!, $op2: FieldFilterOp!, $value2: String) {
  packageSpecs(
    filter: {any: false, filters: [{path: $path1, negated: $negated1, op: $op1, value: $value1}, {path: $path2, negated: $negated2, op: $op2, value: $value2}]}
  ) {
    edges {
      node {
        id
        name
        contentSetName
        command
        commandTimeoutSeconds
        expireSeconds
        params {
          key
          label
          defaultValue
        }
        sensorSourcedParams {
          name
        }
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path1": "name",
  "negated1": true,
  "op1": "CONTAINS",
  "value1": "production",
  "path2": "contentSetName",
  "negated2": false,
  "op2": "CONTAINS",
  "value2": "test"
}

Reporting query filter syntax

Reporting queries support the following filter fields:

  • authorNames
  • contentSetNames
  • createdAfter
  • createdBefore
  • labels
  • moduleNames
  • text

For more information on syntax, see reportFieldFilter in the Documentation Explorer pane of the query explorer.

ClosedReport author

You can filter reports based on the author name. Define a filter object using the syntax:

{authorNames: [name-1, name-2, name-...n]}

For example, the following request filters and returns only report definitions whose author is either testadmin-1 or testadmin-2:

Copy
query getReportsByAuthor ($author1: String!, $author2: String!) {
  reports (filter: {authorNames: [$author1, $author2]}) {
    edges {
      node {
        id 
      }
    }
  }

Include the count and time variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "author1": "testadmin-1",
  "author2": "testadmin-2"
}

ClosedContent set membership

You can filter reports based on the report content set membership. Define a filter object using the syntax:

{contentSetNames: [content-set-name-1, content-set-name-2, content-set-name-...n]}

If you define multiple solutions, a report only needs to match one of the content sets to pass the filter.

For example, the following request filters and returns only report definitions belonging to the Base or Default content sets:

Copy
query getReportsByContentSet ($contentSet1: String!, $acontentSet2: String!) {
  reports (filter: {contentSetNames: [$contentSet1, $contentSet2]}) {
    edges {
      node {
        id 
      }
    }
  }

Include the content set variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "contentSet1": "Base",
  "contentSet2": "Default"
}

ClosedCreation time

You can filter reports based on the report creation time, either before or after a specified time. To filter reports created before a specified time, define a filter object using the syntax:

{createdBefore: rfc-3339-time}

For example, the following request filters and returns only report definitions created before 2022-01-01T00:00:00Z:

Copy
query getReportsBefore ($timeBefore: Time) {
  reports (filter: {createdBefore: $timeBefore}) {
    edges {
      node {
        id 
      }
    }
  }

Include the timestamp variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "timeBefore": "2022-01-01T00:00:00Z"
}

To filter reports created after a specified time, define a filter object using the syntax:

{createdAfter: rfc-3339-time}

For example, the following request filters and returns only report definitions created after 2022-01-01T00:00:00Z:

Copy
query getReportsAfter ($timeAfter: Time) {
  reports (filter: {createdAfter: $timeAfter}) {
    edges {
      node {
        id 
      }
    }
  }

Include the timestamp variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "timeAfter": "2022-01-01T00:00:00Z"
}

ClosedReport labels

You can filter reports based on the associated labels. Define a filter object using the syntax:

{labels: [label-1label-1, label-2, label-...n]}

If you define multiple labels, a report only needs to match one of the labels to pass the filter.

For example, the following request filters and returns only report definitions with a label of testlabel-1 or testlabel-2:

Copy
query getReportsByLabel ($label1: String!, $label2: String!) {
  reports (filter: {labels: [$label1, $label2]}) {
    edges {
      node {
        id 
      }
    }
  }

Include the label variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "label1": "testlabel-1",
  "label2": "testlabel-2"
}

ClosedAssociated Tanium solution

You can filter reports based on the associated Tanium solution. Define a filter object using the syntax:

{moduleNames: [solution-1, solution-2, solution-...n]}

If you define multiple solutions, a report only needs to match one of the solutions to pass the filter.

For example, the following request filters and returns only report definitions associated with Tanium Interact or Tanium Trends:

Copy
query getReportsBySolution ($solution1: String!, $solution2: String!) {
  reports (filter: {moduleNames: [$solution1, $solution2]}) {
    edges {
      node {
        id 
      }
    }
  }

Include the solution name variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "solution1": "Tanium Interact",
  "solution2": "Tanium Trends"
}

ClosedName or description text

You can filter reports based on text in the report name or report description. . Define a filter object using the syntax:

{text: text-string}

For example, the following request filters and returns only report definitions that have test-string either in the name or the definition:

Copy
query getReportsByText ($text: String) {
  reports (filter: {text: $text}) {
    edges {
      node {
        id 
      }
    }
  }

Include the text variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "text": "test-string"
}

Scheduled actions query filter syntax

Scheduled actions queries (query.scheduledActions) support the path and value filter fields.

For more information on syntax, see FieldFilter in the Documentation Explorer pane of the query explorer.

ClosedSingle filter field

You can filter on a single field value. Unless otherwise specified, define a filter object using the syntax:

{path: "field-path", negated: "boolean", op: "operator", value: "filter-value"}

For example, the following request filters and returns only scheduled actions whose name does not contain production:

Copy
query getScheduledActionsFiltered($path: String, $negated: Boolean!, $op: FieldFilterOp!, $value: String) {
  scheduledActions(
    filter: {path: $path, negated: $negated, op: $op, value: $value}
  ) {
    edges {
      node {
        comment
        id
        name
        nextStartTime
        package {
          id
          name
          params
          sensorSourcedParams {
            name
            value
          }
        }
        targets {
          actionGroup {
            id
            name
          }
          targetGroup {
            id
            name
          }
        }
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path": "name",
  "negated": true,
  "op": "CONTAINS",
  "value": "production"
}

ClosedMultiple filter fields

You can filter on multiple field values. Define a filter object using the syntax:

{any: boolean,
  filters: [
    {path: "field-path-1", negated: "boolean-1", op: "operator-1", value: "filter-value-1"},
    {path: "field-path-2", negated: "boolean-2", op: "operator-2", value: "filter-value-2"},
    {path: "field-path-n", negated: "boolean-n", op: "operator-n", value: "filter-value-n"}
  ]

For example, the following request filters and returns only scheduled actions whose name does not contain production, and whose comment contains test:

Copy
query scheduledActionsMultipleFilter($path1: String, $negated1: Boolean!, $op1: FieldFilterOp!, $value1: String, $path2: String, $negated2: Boolean!, $op2: FieldFilterOp!, $value2: String) {
  scheduledActions(
    filter: {any: false, filters: [{path: $path1, negated: $negated1, op: $op1, value: $value1}, {path: $path2, negated: $negated2, op: $op2, value: $value2}]}
  ) {
    edges {
      node {
        comment
        id
        name
        nextStartTime
        package {
          id
          name
          params
          sensorSourcedParams {
            name
            value
          }
        }
        targets {
          actionGroup {
            id
            name
          }
          targetGroup {
            id
            name
          }
        }
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path1": "name",
  "negated1": true,
  "op1": "CONTAINS",
  "value1": "production",
  "path2": "comment",
  "negated2": false,
  "op2": "CONTAINS",
  "value2": "test"
}

Sensor query filter syntax

Sensor queries support the path and value filter fields.

For more information on syntax, see FieldFilter in the Documentation Explorer pane of the query explorer.

ClosedSingle filter field

You can filter on a single field value. Unless otherwise specified, define a filter object using the syntax:

{path: "field-path", negated: "boolean", op: "operator", value: "filter-value"}

For example, the following request filters and returns only sensors whose name does not contain production:

Copy
query getSensorsFiltered($path: String, $negated: Boolean!, $op: FieldFilterOp!, $value: String) {
  sensors(filter: {path: $path, negated: $negated, op: $op, value: $value}) {
    edges {
      node {
        category
        description
        name
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path": "name",
  "negated": true,
  "op": "CONTAINS",
  "value": "production"
}

ClosedMultiple filter fields

You can filter on multiple field values. Define a filter object using the syntax:

{any: boolean,
  filters: [
    {path: "field-path-1", negated: "boolean-1", op: "operator-1", value: "filter-value-1"},
    {path: "field-path-2", negated: "boolean-2", op: "operator-2", value: "filter-value-2"},
    {path: "field-path-n", negated: "boolean-n", op: "operator-n", value: "filter-value-n"}
  ]

For example, the following request filters and returns only sensors whose name does not contain production, and whose description contains test:

Copy
query sensorMultipleFilter($path1: String, $negated1: Boolean!, $op1: FieldFilterOp!, $value1: String, $path2: String, $negated2: Boolean!, $op2: FieldFilterOp!, $value2: String) {
  sensors(
    filter: {any: false, filters: [{path: $path1, negated: $negated1, op: $op1, value: $value1}, {path: $path2, negated: $negated2, op: $op2, value: $value2}]}
  ) {
    edges {
      node {
        category
        description
        name
      }
    }
  }
}

Include the filter-related variables in the QUERY VARIABLES panel:

Copy
{
  "path1": "name",
  "negated1": true,
  "op1": "CONTAINS",
  "value1": "production",
  "path2": "description",
  "negated2": false,
  "op2": "CONTAINS",
  "value2": "test"
}