Filter

Filters limit an operation to a subset of resources. You can use filters to make operations more precise, remove unneeded items from a payload, and reduce the need for secondary processing.

To use a filter, specify it in the operation’s argument. Most fields in an object can serve as a filter.

Filter by property

The following sections show some common scalar filters, filters that work on string, dateTime, and numeric values. These filters return only the resources that have some specified property or property range.

between dates

The between property returns items within time ranges for a specific property. This query returns job responses that started between January 01, 2023 and January 05, 2023.

query {
  queryJobResponse(
    filter: {
      effectiveStart: { between: { min: "2023-01-01", max: "2023-01-05" } }
    }
  ) {
    id
    effectiveStart
  }
}

has property

The has keyword returns results only if an item has the specified field. For example, this query returns only equipment items that have been modified at least once.

query QueryEquipment {
  queryEquipment(filter: {has: _modifiedOn}) {
    id
    _createdOn
    _modifiedOn
  }
}

{
  "data": {
    "queryEquipment": [
      {
        "id": "AN-19670-Equipment-1",
        "_createdOn": "2023-12-24T16:50:45Z",
        "_modifiedOn": "2024-01-23T20:06:30Z"
      },
      {
        "id": "AN-19670-Equipment-2",
        "_createdOn": "2023-12-24T18:16:35Z",
        "_modifiedOn": "2024-01-23T20:06:35Z"
      },
      // more items
      ]
    }
 }

To filter for items that have multiple properties, include the fields in an array. This query returns equipment objects that both have been modified and have next versions:

query QueryEquipment {
  queryEquipment(filter: {has: [_modifiedOn, nextVersion]}) {
    nextVersion
    _modifiedOn
  }
}

in this subset

The in keyword filters for objects that have properties with specified values. For example, this query returns material lots that have material definitions that are either dough or cookie_unit.

query{
  queryMaterialLot @cascade {
    id
    materialDefinition(filter: {id: {in: ["dough", "cookie_unit"]}}) {
      id
    }
    }
  }
}

regexp

The regexp keyword searches for matches using the RE2 regular expression engine.

For example, this query uses a regular expression in its variables to filter for items that begin with either Kitchen_ or Cooling_ (case insensitive):

query getEquipment($filter: EquipmentFilter) {
  aggregateEquipment(filter: $filter) {
    count
  }
  queryEquipment(filter: $filter) {
    id
  }
}

{
  "EquipmentFilter": {
    "id": {
      "regexp": "/|Kitchen_.*|Cooling_.*/i"
    }
  },
}

Combine filters with and, or, not

To filter by multiple properties, use the and, or, and not, operators. GraphQL syntax uses infix notation, so: “a and b” is a, and: { b }, “a or b or c” is a, or: { b, or: c }, and “not” is a prefix (not:).

this and that property

The and operator filters for objects that include all specified properties.

For example, this query returns equipment objects that match two properties:

• The effectiveStart must be the 1st and the 10th of January, 2024.
• It must have a non-null nextVersion.

The and function is implicit unless you are searching on the same field. So this filter has an implied and:

query{
  queryEquipment(filter: {
      effectiveStart: {
        between: {min: "2024-01-01", max: "2024-01-10"}
        
      }
      has: nextVersion
    
    }
  )
  {
    effectiveStart
    id
    nextVersion
  }
}

One or more properties

The or operator filters for objects that have at least one of the specified properties. For example, you can take the preceding query and modify it so that it returns objects that have an effective start between the specified range or a nextVersion property (inclusive).

queryEquipment(filter: {
      effectiveStart: {
        between: {min: "2024-01-01", max: "2024-01-10"}
        
      }
      or: {has: nextVersion}
    
    }
  )

not these properties

The not operator filters for objects that do not contain the specified property. For example, you can take the preceding query and modify it so that it returns objects that have an effective start between the specified range and do not have a nextVersion property:

queryEquipment(filter: {
      effectiveStart: {
        between: {min: "2024-01-01", max: "2024-01-10"}
        
      }
      not: {has: nextVersion}
    
    }
  )

To modify this to include both objects within the range and objects that do not have a nextVersion, use or with not:

or: { not: {has: nextVersion} }

This list of filters

The and and or operators accept lists of filters. For example, this query filters for equipment objects whose id matches A, B, or C:

queryEquipment (filter: {
    or: [
    { id: { eq: "A" } }, 
    { id: { eq: "B" } },
    { id: { eq: "C" } }, 
  ]
  })

Use directives

Rhize offers query directives, special instructions about how to look up and return values in a query. These directives can extend your filtering to look at nested properties or to conditionally display a field.

All directives begin with the @ sign.

Cascade

The @cascade directive filters for certain nodes within a query. Use it to filter requested resources by a nested sub-property, similar to a WHERE clause in SQL.

For example, this query filters for job responses with an ID of 12341, and then filters that set for only the items that have a data.properyLabel field with a value of INSTANCE ID.

query QueryJobResponse($filter: JobResponseFilter, $propertyLabel: String) {
  queryJobResponse(filter: $filter)  @cascade(fields:["data"]){
    id
    iid
    data(filter: { label: { anyoftext: $propertyLabel } }) {
      id
      iid
      label
      value
    }
  }
}

{
    "filter": {
        "id": {
            "alloftext": "12341"
        }
    },
    "propertyLabel": "INSTANCE ID"
}

Avoid using @cascade with the order argument

The order argument returns only the first 1000 records of the query. If a record matches the @cascade filter but comes after these first 1000 records, the API does not return it.

For example, this query logic works as follows:

1. Return the first 1000 records of equipment as ordered by effectiveStart.
2. From these 1000 records, return only the equipment items that are part of parentEquipment1.

query($filter: EquipmentFilter){
  queryEquipment (filter: { order: {desc:effectiveStart}) @cascade{
    id
    isPartOf (filter: {id:{eq:"parentEquipment1"}}) {
      id
    }
  }
}

This behavior can be surprising and undesirable, so avoid @cascade with the order argument.

Include

The @include directive returns a field only if its variable is true.

For example, when includeIf is true, this query omits specified values for versions.

query($includeIf: Boolean!) {
  queryEquipment {
    id
    versions @include(if: $includeIf) {
      id
    }
  }
}

{
  "includeIf": false
}