Filter Syntax

Turbot Guardrails provides a number of ways to filter, sort and limit results of data stored in the Guardrails CMDB.

Full Text SearchGuardrails can use full text search against all the objects in the search scope.
Filtering on Specific PropertiesGuardrails allows searching and filtering on specific properties of an object, such as Text Filters, Numeric Filters, IP/CIDR Filters, Date/Time Filters and Tag Filters etc.
Checking for null or undefinedThe keywords null and undefined can be used in filters to look for missing keys or values.
Standard Guardrails PropertiesThe standard Guardrails metadata properties are searchable.
Hierarchical Filter ScopesGuardrails lists are used to display resources from multiple levels of the resource hierarchy.
SortingMost Guardrails lists support sorting by appropriate fields.
Limiting ResultsWe can limit the number of items that Guardrails returns using the limit keyword.

If no property or attribute is specified in a filter, Guardrails will use full text search against all the objects in the search scope.

  • The filter will search ALL properties of the objects
  • The search is case-insensitive
  • If no sort is specified, it will return the results in ranked order:
    • matches in title and AKA rank higher
    • items are then ranked by frequency of the search term
  • If multiple search terms are specified in the filter, the filtered list will contain only the items that match BOTH terms - whitespace separated items are treated as "AND" conditions.

The search keyword may also be explicitly to specify a full text search. In addition to the full text filtering behavior described previously, search allows you to specify "OR" conditions using a comma separated list of terms

A filter condition can be negated with the ! character.

AimFilter text
Require foofoo
Exclude foo!foo
Require "foo" and "bar"foo bar
Require "foo bar""foo bar"
Exclude "foo bar"!"foo bar"
Require foo or barsearch:foo,bar

Regular Expressions are also supported. Note that unqualified regular expressions will search the title only.

AimFilter text
starts with "foo"/^foo/
contains "foo", case insensitive/foo/i
does not contain "foo", case insensitive!/foo/i

Filtering on Specific Properties

Guardrails supports searching and filtering on specific properties of an object.

  • The general format of a condition is: {property}:{operator}{value}
    • The {property} may be a standard Guardrails property or any field using the $. syntax
    • The {operator} that may be used depends on the data type of the property being searched.
    • The {operator} is optional, and the default behavior depends on the data type of the property being searched.
    • The condition can be negated by preceding the operator with !
    • Multiple {values} can be joined with a comma to specify an "OR" condition
  • Multiple whitespace separated conditions are joined as "AND" conditions

Text Filters

Text filters provide the simplest way to filter lists in Guardrails, with simple string matching against the specified field. Simple text filters on properties behave differently than full text search filters:

  • They only match against a single property
  • They are case-sensitive
  • They must match EXACTLY - title:foo means the title is exactly foo, not that the title contains foo

For more complex string searching, regular expressions may be used.

  • Regular expressions are delimited with '/' characters
  • The standard /i switch is supported to make a regular expression case insensitive
AimFilter text
Title is footitle:foo
Title is foo or bartitle:foo,bar
Title is not footitle:!foo
Title contains footitle:/foo/
Title contains foo, case insensitivetitle:/foo/i
Title does not contain "foo", case insensitivetitle:!/foo/i
Title contains foo or bartitle:/foo/,/bar/
Title contains foo and bartitle:/foo/ title:/bar/
Title start with footitle:/^foo/
Title start with foo and ends with bartitle:/^foo.*bar$/

Numeric Filters

Fields that contain numeric data can be filtered with numeric operators. Guardrails will do automatic type coercion, allowing to look for items less than, greater than, or equal to a given numeric value even if they are stored as strings.

AimFilter text
Iops is exactly 100$.Iops:100
more than 100 Iops$.Iops:>100
Iops greater than or equal to 100$.Iops:>=100
Size is not greater than 30$.Size:!>30
Provisioned Read Capacity is less than 10$.ProvisionedThroughput.ReadCapacityUnits:<10
Size is less than or equal to 30$.Size:<=30
Size is greater than 30 and Iops is greater than 100$.Iops:>100 $.Size:>30
VolumeSize tag is greater than 1024$.turbot.tags.Volumesize:>1024

IP/CIDR Filters

Guardrails can search and filter based on IP addresses and other properties that use CIDR notation. This allows for advanced capabilities such as filtering for instances that reside in a given subnet, or finding subnets within a larger supernet.

IP Address Filters

AimFilter text
Private IP is exactly 172.31.40.226$.PrivateIpAddress:172.31.40.226
Private IP is greater than 172.31.30.35$.PrivateIpAddress:>172.31.30.35
Private IP is less than 172.31.30.35$.PrivateIpAddress:<172.31.30.35
Private is IP in-between 172.31.30.35 and <172.31.36.200$.PrivateIpAddress:>172.31.30.35,<172.31.36.200
Private IP is not 172.31.40.226$.PrivateIpAddress:!172.31.40.226

CIDR Filters

AimFilter text
Private IP is in the 172.31.47.250/8 network$.PrivateIpAddress:172.31.47.250/8
Private IP is not in the 172.31.47.250/8 network$.PrivateIpAddress:!172.31.47.250/8
CidrBlock is contained entirely within 10.0.0.0/24, but not equal to it$.CidrBlock:<10.0.0.0/24
CidrBlock is contained entirely within, or equal to 10.0.0.0/24$.CidrBlock:<=10.0.0.0/24
CidrBlock is outisde the 10.0.0.0/24 address space$.CidrBlock:>10.0.0.0/24

Date/Time Filters

Date/Time filters allow querying Guardrails timestamps and filtering by date range. This allows you to limit search results based on the time the items were created, updated or deleted.

You can specify the time in ISO datetime format, reserved keywords, or a relative datetime expression.

ISO Datetime Formats
  • 2019-03-26T16:12:16.110Z
  • 2019-03-26T16:12:16.110
  • 2019-03-26T16:12:16
  • 2019-03-26T16:12
  • 2019-03-26
Reserved Keywords
  • now
  • yesterday - 24 hours ago
  • tomorrow - 24 hours from now
Relative Datetime Expression
  • Format: T{operator}{n}{units}
  • Operators: plus (+) or minus (-)
  • units:
    • w - weeks
    • d - days
    • h - hours
    • m - minutes
    • s - seconds
    • ms - milliseconds
  • Examples:
    • in 3 days: T+3d
    • 2 weeks ago: T-2w
    • an hour ago: T-1h
AimFilter text
Resources created in the last 24 hourscreateTimestamp:>yesterday
Resources updated within 1 hourupdateTimestamp:<T-1h
Resources deleted on April 20thdeleteTimestamp:>=2019-04-20 deleteTimestamp:<2019-04-21
Resources created, updated, modified, or delete in the last 10 minutestimestamp:<T-10m

Tag Filters

Most resources in Guardrails support applying and searching by tags. Tags can be assigned to native Guardrails resources, such as Files and Folders. Native tagging features for AWS tags, Azure tags, and Google labels are also searchable via the same mechanism. This allows you to filter results based on tag keys or values across ALL your Guardrails resources in a consistent way.

AimFilter text
Has tag foo with value bar (exactly)tags:foo=bar
Has tag foo with value bar (exactly), as a regextags:foo=/^bar$/
Has tag foo with value bar, case insensitivetags:foo=/bar/i
Has tag foo with empty valuetags:foo=''
Has tag foo with any value$.turbot.tags.foo:!undefined or tags:foo=/.*/
Does not have a tag named foo$.turbot.tags.foo:undefined or tags:foo=null
Has tag foo with any value but not null!tags:foo=null

Checking for null or undefined

The reserved keywords null and undefined can be used in filters to look for missing keys or values.

  • undefined: The item does not contain the property at all
  • null: The item either does not contain the property, or the property has a null value
AimFilter text
Has no title property, or title with a null value$.title:null
Has a title property with a defined (non-null) value$.title:!null
Has no title property$.title:undefined
Has no title property with any value, including null$.title:!undefined

Standard Turbot Guardrails Properties

The following standard Guardrails metadata properties are searchable for all types:

  • id - The Guardrails resource id of the resource - eg 208149840507523
  • title - the title of the resource - eg i-09b1336b7d371b655
  • versionId - the current version id for a resource
  • createTimestamp - the time the resource was created in (or discovered by) Turbot and added to the CMDB
  • updateTimestamp - the time the resource was last updated in the Turbot CMDB
  • timestamp - the time the resource was last created or updated
  • processId - the Turbot process id of the last create or update event
  • actorIdentityId - The ID of the profile who last updated or created the resource

Hierarchical Filter Scopes

Many lists in the Guardrails console display resources from multiple levels of the resource hierarchy. For example, it is possible to show all Control alarms for a specific cloud account, or to show all the alarms for itself and its descendants.

  • resourceId - Allows you to specify where in the resource hierarchy the filter should apply. The combination of resource and level performs the initial filtering of the resources. The resource can be specified using the internal Guardrails Id or a full aka. Note that when searching or filtering in the Turbot Guardrails Console, the scope of the search is set implicitly - your search/filter will be scoped in relation to the resource to which you have navigated (as appears at the top of the page).

  • level - Determines the scope of the filter search, in relation to the resource. The default level is level:self,descendant if no level is specified. The level is relative to the resource filter

AimFilter text
Self onlylevel:self
Descendants onlylevel:descendant
Immediate children onlylevel:children
Ancestors onlylevel:ancestor
Self or Descendantslevel:self,descendant
Self or Descendants (alternate)level:all

There are similar scopes that enable you to scope your filter through the type and categories as well. They behave similarly:

  • They have a search base keyword to specify where in the hierarchy the filter should apply. This will be an id or aka. Note that if an aka is specified, the filters will perform a partial match (will match if the aka contains the string specified in the filter)
  • They have a level keyword to determine the scope of the filter search, in relation to the search base. If not specified, this defaults to the same value as resource levels
  • The available scope keywords depend on the type of list query.
KeywordValueExample
resourceaka/id of a Resourceresource:tmod:@turbot/turbot#/
levelstandard level for the Resourcelevel:ancestor,self,descendant
resourceTypeaka/id of a Resource TyperesourceType:'tmod:@turbot/aws-s3#/resource/types/s3Account'
resourceTypeIdaka/id of a Resource TyperesourceTypeId:'tmod:@turbot/aws-s3#/resource/types/bucket'
resourceTypeLevelstandard level for the Resource TyperesourceTypeLevel:self,descendant
resourceCategoryaka/id of a Resource CategoryresourceCategory:'tmod:@turbot/turbot#/resource/categories/compute'
resourceCategoryIdaka/id of a Resource CategoryresourceCategoryId:'tmod:@turbot/turbot#/resource/categories/compute'
resourceCategoryLevelstandard level for the Resource CategoryresourceCategoryLevel:self,descendant
controlTypeaka/id of a Control Type (Approved, Active, etc)controlType:'tmod:@turbot/aws-s3#/control/types/bucketDiscovery'
controlTypeIdaka/id of a Control Type (Approved, Active, etc)controlTypeId:'tmod:@turbot/aws-s3#/control/types/bucketActive'
controlTypeLevelstandard level for the Control TypecontrolTypeLevel:self,descendant
controlCategoryaka/id of a Control CategorycontrolCategory:'tmod:@turbot/turbot#/control/categories/security'
controlCategoryIdaka/id of a Control CategorycontrolCategoryId:'tmod:@turbot/turbot#/control/categories/security'
controlCategoryLevelstandard level for the Control CategorycontrolCategoryLevel:self,descendant
policyTypeaka/id of a Policy TypepolicyType:'tmod:@turbot/aws-s3#/policy/types/bucketApproved'
policyTypeIdaka/id of a Policy TypepolicyTypeId:'tmod:@turbot/aws-s3#/policy/types/bucketEncrytionAtRest'
policyTypeLevelstandard level for the Policy TypepolicyTypeLevel:self,descendant
descendantResourceTypeaka/id of a Resource TypedescendantResourceType:'tmod:@turbot/aws-s3#/resource/types/s3Account'
descendantInterfaceaka/id of a Resource Type InterfacedescendantInterface:'tmod:@turbot/turbot#/resource/interfaces/grants'

Sorting

Most Guardrails lists support sorting by appropriate fields. Common examples would include title, urn, timestamp.

AimFilter text
Sort by field titlesort:title
Reverse sort by field titlesort:-title
Sort by field title then createTimestampsort:title,createTimestamp
Sort by field title, then reverse sort by createTimestampsort:title,-createTimestamp

Limiting Results

You can limit the number of items that Guardrails returns using the limit keyword. The default limit is 20.

AimFilter text
return 10 resultslimit:10
return 100 resultslimit:100