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.
Asset query filter syntax
Filter Asset queries when retrieving Asset products (query.assetProducts) or endpoints (query.assetProductEndpoints).
Asset product queries (assetProducts) support the following filter fields:
For more information on syntax, see assetProductsFilter in the Documentation Explorer pane of the query explorer.
Endpoint queries using assetProductEndpoints support the following filter fields:
- name
- vendor
- version
- usage
For more information on syntax, see assetProductEndpointsFilter in the Documentation Explorer pane of the query explorer.
You can retrieve Asset products and filter based on product metadata. Define a filter object using the syntax:
filter {
vendors: [
"vendor-name-1",
"vendor-name-2",
"vendor-name-n..."
],
search: "search-string",
states: [Cataloged | Ignored | Tracked]
}
For example, the following request retrieves only Asset products with a vendor name of Example vendor, an Asset state of Cataloged, and the search string Product in either the vendor name or product name:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
query getAssetProductsFiltered($first: Int, $vendor: String!, $search: String, $states: AssetProductState!) {
assetProducts(
first: $first, filter: {
vendors: [$vendor],
search: $search,
states: [$states]
}
) {
edges {
node {
vendor
name
installation {
installedCount
usedCount
unusedCount
pendingUsage
}
usage {
usageNotDetected
notInstalled
baselining
limited
normal
high
}
tracking {
state
reportingPeriodDays
normalMinutesUsedPerDay
highMinutesUsedPerDay
baselinePeriodDays
}
versions {
version
installs
}
}
}
}
}
Include the filter variables in the QUERY VARIABLES panel:
Copy
1
2
3
4
5
6
{
"first": 2,
"vendor": "Example vendor",
"search": "Product",
"states": "Cataloged"
}
You can retrieve endpoints and filter the returned endpoints based on Asset product information. Define a filter object using the syntax:
filter {
vendors: [
"vendor-name-1",
"vendor-name-2",
"vendor-name-n..."
],
name: "name-string",
version: "version-string"
}
For example, the following request retrieves only endpoints that have installed the Example name product, with a vendor of Example vendor and version of 1.2.3:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
query getEndpointsAssetProduct($first: Int, $vendor: String, $name: String, $version: String) {
assetProductEndpoints(
first: $first
filter: {vendor: $vendor, name: $name, version: $version usage: Normal}
) {
edges {
node {
id
eid
computerName
computerId
serialNumber
osPlatform
operatingSystem
servicePack
manufacturer
ipAddress
userName
createdAt
updatedAt
}
}
}
}
Include the filter variables in the QUERY VARIABLES panel:
Copy
1
2
3
4
5
6
{
"first": 2,
"vendor": "Example vendor",
"name": "Example name",
"version": "1.2.3"
}
Comply query filter syntax
Endpoint queries that request Comply-related information using complianceFindings or cveFindings support the path and value filter fields. Comply 2.16.97 or later is required to submit a request that filters specific System Vulnerability and System Compliance risk vector fields.
For more information on syntax, see FieldFilter in the Documentation Explorer pane of the query explorer.
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 findings category of Error and returns that endpoint's associated compliance findings:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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:
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 findings cveYear of 2020 and cvssScore value of 5, and returns that endpoint's associated vulnerability findings:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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:
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.
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
{
"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"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
11
{
"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"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
1
2
3
{
"type": "MANUAL"
}
To retrieve standard computer groups, include the following type variable in the QUERY VARIABLES panel or in your variables dictionary:
Copy
1
2
3
{
"type": "STANDARD"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
1
2
3
{
"filterEnabled": true
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
1
2
3
{
"mrEnabled": true
}
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.
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
1
2
3
4
5
6
7
8
9
10
11
12
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:
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
1
2
3
4
5
6
7
8
9
query getLinuxEndpoints ($cgname: String){
endpoints(filter: {memberOf: {name: $cgname}}) {
edges {
node {
id
}
}
}
}
Include the computer group name variable in the QUERY VARIABLES panel:
Copy
1
2
3
{
"cgname": "All Linux"
}
The following request filters and returns only endpoints that are members of the computer group with the ID of 123:
Copy
1
2
3
4
5
6
7
8
9
10
11
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:
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"sensor": "Total Memory",
"value": "16384 MB"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"sensor": "Total Memory",
"value": "2022-01-01T00:00:00.000Z"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
{
"sensorName": "Custom Tag Exists",
"sensorValue": "true",
"paramName": "tag",
"paramValue": "the-tag"
}
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
1
2
3
4
5
6
7
8
9
10
11
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
1
2
3
4
5
{
"sensorName": "CPU Details",
"sensorColumn": "CPU",
"sensorValue": "Intel"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
7
{
"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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
1
2
3
4
5
6
7
{
"sensorName1": "Installed Applications",
"sensorColumn1": "Name",
"sensorOp1": "CONTAINS",
"sensorValue1": "Firefox",
"sensorName2": "Is Linux"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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:
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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:
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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
1
2
3
4
5
6
{
"path": "name",
"negated": true,
"op": "CONTAINS",
"value": "production"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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
1
2
3
4
5
6
7
8
9
10
{
"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.
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"author1": "testadmin-1",
"author2": "testadmin-2"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"contentSet1": "Base",
"contentSet2": "Default"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
{
"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
1
2
3
4
5
6
7
8
9
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
1
2
3
{
"timeAfter": "2022-01-01T00:00:00Z"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"label1": "testlabel-1",
"label2": "testlabel-2"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
4
{
"solution1": "Tanium Interact",
"solution2": "Tanium Trends"
}
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
1
2
3
4
5
6
7
8
9
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
1
2
3
{
"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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
1
2
3
4
5
6
{
"path": "name",
"negated": true,
"op": "CONTAINS",
"value": "production"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
1
2
3
4
5
6
7
8
9
10
{
"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.
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
1
2
3
4
5
6
7
8
9
10
11
12
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
1
2
3
4
5
6
{
"path": "name",
"negated": true,
"op": "CONTAINS",
"value": "production"
}
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
1
2
3
4
5
6
7
8
9
10
11
12
13
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
1
2
3
4
5
6
7
8
9
10
{
"path1": "name",
"negated1": true,
"op1": "CONTAINS",
"value1": "production",
"path2": "description",
"negated2": false,
"op2": "CONTAINS",
"value2": "test"
}
Asset products