Filtering Entity Queries

When you perform an entityQuery you can filter the response based on the value of fields using the QueryFilter object .

When building the QueryFilter object you provide a field name (which must be a field on the entityType you are looking for) on which to filter. The operator field is an ENUM with the below values that can be used when creating a filter:

• EQ equal to
• NEQ not equal to
• LT less than
• LTE less than or equal to
• GT greater than
• GTE greater than or equal to
• CONTAINS case sensitive check for the provided string within the field value
• STARTSWITH case sensitive check if the field value starts with the provided string
• ENDSWITH case sensitive check if the field value ends with the provided string
• ISNULL field is null
• ISNOTNULL field is not null

The value is provided for the comparison operators, except the ISNULL and ISNOTNULL operators.

Find a VM with a “Name” tag of value “VM1”

A basic example of filtering is to look for any AWS EC2 instances and Azure Virtual Machines that are tagged with Name=VM 1. The query below uses the field tag.Name (the dot notation allows you to access nested field names) and the operator EQ, and looks for the value VM 1. Note that the values field is an array, so it can hold multiple values.

 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 {
  entityQuery {
    queryEntities(
      entityType: ["AWS.EC2.instance", "VMW.VC.VM"]
      filter: { 
        field: "tag.Name",
        operator: EQ,
        values: [
          "VM 1"
        ]
      }
    ) {
      totalCount
      entities {
        entityName
        entityType
        tags {
          key
          value
        }
      }
    }
  }
}

Find VMs that have a “Name” tag defined

The query below uses the field tag.Name and the operator ISNOTNULL to filter AWS EC2 instances and Azure Virtual Machines that have a Name tag.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

query {
  entityQuery {
    queryEntities(
        entityType: ["AWS.EC2.instance", "Azure.Compute.VirtualMachine"],
        filter: {
          field: "tag.Name",
          operator: ISNOTNULL
        }
      ) {
      entities {
        entityId
        namespaces {
          name
          id
        }
      }
    }
  }
}

Multiple filters

The QueryFilter object also supports and, or and not logical operators to use multiple filters or to negate a filter, for example the query below will return AWS EC2 instances and Azure Virtual Machines that are tagged with Name=VM 1, Name=VM2 OR Tier=Web. When using and, or, or not the value must be an array of QueryFilter objects.

If the below query were to be changed to an and operator, the query would return AWS EC2 instances and Azure Virtual Machines that are tagged with either Name=VM 1, Name=VM2 AND Tier=Web

 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 {
  entityQuery {
    queryEntities(
        entityType: ["AWS.EC2.instance", "Azure.Compute.VirtualMachine"],
        filter: {
          or: [
            {
              field: "tag.Name",
              operator: EQ,
              values: [
                "VM1",
                "VM2"
              ]
            },
            {
              field: "tag.Tier",
              operator: EQ,
              values: [
                "Web"
              ]
            }
          ]
        }
      ) {
      entities {
        entityId
        namespaces {
          name
          id
        }
      }
    }
  }
}

Share this post