Collection Functions

Overview

These functions return information about the collection or checks for the presence of a specified element.

Create a collection by declaring the elements inline, enclosed in square brackets:

['john.doe@example.org', 'mary.jones@example.org']

Alternatively, load a collection using the collection() function or another lookup function.

collection('oncall-emails')

Reference

collection

collection(string s) [string]

Returns an array of strings contained in collection s.

Named collections are listed on the Data > Named Collections page.

To access the size of the array, use the .size() method.

To access the n-th element in a collection, use square brackets like with the [index] or get(index) method. Index begins with 0 on the first element.

author = (authors.size() == 0) ? 'n/a' : authors[0]

IN

string s IN (string a[, string b[...]]) boolean

Returns true if s is contained in the collection of strings enclosed in round brackets.

Examples:

entity IN ('nurswgvml007', 'nurswgvml008')
tags.location IN ('NUR', 'SVL')

LIKE

string s LIKE (string a[, string b[...]]) boolean

Returns true if s matches any pattern in the collection of strings enclosed in round brackets. The pattern supports ? and * wildcards. The collection can contain string literals and variables.

Examples:

entity LIKE ('nurswgvml*', 'nurswghbs*')
tags.version LIKE ('1.2.*', '1.3.?')
tags.location LIKE ('NUR*', entity.tags.location)

likeAny

likeAny(string s, [string] c) boolean

Returns true if string s matches any element in the string collection c.

Load collection c from a named collection or initialize collection c from an array of strings. The elements of the collection can include patterns with ? and * wildcards.

Examples:

likeAny(tags.request_ip, ['192.0.2.1', '192.0.2.2'])
likeAny(tags.location, ['NUR', 'SVL*'])
likeAny(tags.request_ip, collection('ip_white_list'))

matchList

matchList(string s, string c) boolean

Returns true if s is contained in collection c.

Collection c can include patterns with ? and * wildcards.

Example:

matchList(tags.request_ip, 'ip_white_list')

matches

matches(string p, [string] c) boolean

Returns true if one of the elements in collection c matches the specified pattern p.

The pattern supports ? and * wildcards.

Example:

matches('*atsd*', property_values('docker.container::image'))

contains

[string].contains(string s) boolean

Returns true if s is contained in the specified collection.

Example:

collection('ip_white_list').contains(tags.request_ip)

size

[].size() integer

Returns the number of elements in the collection.

Apply this function to any type of collection (string, number) as well as maps such as entity.tags.

Examples:

collection('ip_white_list').size()
entity.tags.size()

isEmpty

[].isEmpty() boolean

Returns true if the number of elements in the collection is zero.

Apply this function to any type of collection (string, number) as well as maps such as entity.tags.

Example:

collection('ip_white_list').isEmpty()

replacementTable

replacementTable(string s) map

Retrieves the replacement table identified by name s as a key-value map.

If the table is not found, the function returns an empty map.

// .keySet() returns a collection of keys in the replacement table
replacementTable('oncall-emails').keySet()
// .values() returns a collection of values in the replacement table
replacementTable('oncall-emails').values()
// returns a random value in the replacement table
randomItem(replacementTable('oncall-emails').values())
// returns a random key-value object from the replacement table
randomItem(replacementTable('oncall-emails'))

excludeKeys

excludeKeys([] m, [] c) map

Returns a copy of the input map m without the keys specified in collection c.

The keys in collection c can contain wildcards ? and * to remove multiple matching keys from the map.

Examples:

excludeKeys(replacementTable('oncall-emails'),['jack.smith@example.org', 'mary.jones@example.org'])
/* Returns ["b1": "w1", "b2": "w2"] */
excludeKeys(["a1": "v1", "a2": "v2", "b1": "w1", "b2": "w2", "c1": "z1"], ['a*', 'c1'])