Filter Syntax

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

Full Text Search

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.

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

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

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.

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

CIDR Filters

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

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.

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

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

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.

Sorting

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

Limiting Results

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