published on in Entertainment

Query Language Functions - Documentation for BMC Helix Discovery

Another option for manipulating attributes is to apply functions to them. Functions are applied using the familiar parenthesis syntax:

The following functions operate on normal attribute values.

abs(value)

Returns the absolute value of an integer.

bin(value, bins [, legend])

Separates numeric values into 'bins', based on a list of values providing the bin boundaries, for example, a search like this:

SEARCH Host SHOW name, ram, bin(ram, [64, 512, 1024, 4096])

gives results like

rs6000

1888

1024-4096

jpl64app

896

512-1024

sol10x86

288

64-512

linux-mandr-9-1

32

Less than 64

lonvmserv02

12288

4096 and more

The optional legend parameter allows the bins to be named. The list must have one more item than the bins list. For example:

SEARCH Host SHOW name, ram, bin(ram, [64, 512, 1024, 4096], ["Less than 64M", "64M to 512M", "512M to 1G", "1G to 4G", "More than 4G"])

rs6000

1888

1G to 4G

jpl64app

896

512M to 1G

sol10x86

288

64M to 512M

linux-mandr-9-1

32

Less than 64M

lonvmserv02

12288

More than 4G

boolToString(value)

Interprets its argument as a Boolean and returns "Yes" or "No".

booleanLabel(value, true_label, false_label, other_label)

A more advanced version of boolToString, which lets you choose which label to use for the TrueFalse, and None cases.

duration(start_time, end_time)

Calculates the amount of time elapsed between the two dates and returns the result as a string of the form 'days.hours:minutes:seconds'.

currentTime()

Returns the number of 100 nanosecond intervals since 15 October 1582. This example query returns the hosts created in the last 7 days:

search Host where creationTime(#) > (currentTime() - 7*24*3600*10000000) show name, time(creationTime(#)) as CreateTime

defaultNumber(value, default_value)

Attempts to convert the value into a number and if it is not possible returns the default value.

Performs a regular expression extraction. The value is matched against the pattern. If no substitution is given, returns the part of the value that matched the pattern. If substitution is given, it specifies a string including group references of the form \1\2, and so on, that are filled in with the corresponding groups in the pattern. If the value does not match the pattern, returns an empty string. Strings containing backslashes must be specified with a regex qualifier, for example, regex "\1" .

flatten(value)

Converts a list of nested lists into a flat list. Each list item can be any data structure that is not a list. If the received value is not a list, returns a list that holds only that value.

fmt(format, ...)

The first argument is a Python format string, the remaining arguments are values to interpolate into it. The result is equivalent to a key expression of the form #"format"(...), except that the arguments to the fmt() function can be the results of other functions. That is, these two expressions are equivalent:

SEARCH Host SHOW #"%s: %s"(name,ram) SEARCH Host SHOW fmt("%s: %s",name,ram) 

Whereas the following expression can only be done with fmt() because it calls the len() function:

SEARCH Host SHOW fmt("%s: %d",name,len(name)) 

The following example shows the fmt() function used to show the results of floating point arithmetic:

fmt( "%.4f", float(size)/1048576) as 'Size GB' 

fmt_map(format, items)

Applies a format string to all items in a list. The format argument must be a python format string with only one variable. items is the list of items to interpolate into the string. Returns a list of strings as a result.

formatNumber(value, singular, plural, other)

If value is 1, returns singular, if value is a number other than one, return plural with the value inserted at the mandatory %d inside it, and if value is not a number return other. e.g.

SEARCH Host SHOW name, patch_count, formatNumber(patch_count, "One patch", "%d patches", "Unknown patches") 

formatQuantity(value, format) 

Takes a value (bits or bytes) and applies user friendly formatting, putting the values into KiB, Mb, and so on. The value, an int or a float is formatted according to a number of fixed format parameters. Format parameters are all literal strings. If non-numeric values such as strings or None are passed then they are returned unmodified.

The format parameters and examples are shown in the following table:

Value

Format parameter

Result

1000

"1000"

1 k

1000000

"1000"

1 M

1000

"1024"

1000

1000000

"1024"

976.6 Ki

1000

"B1000"

1 kB

1000000

"B1000"

1 MB

1000

"B1024"

1000 bytes

1000000

"B1024"

976.6 KiB

1000

"b1000"

1 kb

1000000

"b1000"

1 Mb

1000

"b1024"

1000 bits

1000000

"b1024"

976.6 Kib

1000

"bitrate"

1 kbit/s

1000000

"bitrate"

1 Mbit/s

1000

"byterate"

1 kB/s

1000000

"byterate"

1 MB/s

In the taxonomy, the attributes are not always mentioned in bits or bytes. For example: In FileSystem nodes, the unit of the size attribute is kB. Use formatQuantity(size*1024, 'B1024') in this case.


The following example shows applying friendly formatting the raw capacity of a StoragePool:

SEARCH StoragePool SHOW name, total_raw_capacity, formatQuantity( total_raw_capacity, "1000") as 'Size 1000', formatQuantity( total_raw_capacity, "B1024") as 'Size B1024'

Name

Total Raw Capacity

Size 1000

Size B1024

Pool 1

1435374714880

1.4 T

1.3 TiB

Pool 2

27686186726640

27.7 T

25.2 TiB

Pool 3

384832081920

384.8 G

358.4 GiB

Pool 4

0

0

0 bytes

formatTime(time_value, format)

Converts the internal time format to a string, based on the format specification, and converting into the appliance's time zone. The format is specified using Python's strftime format. For example, a search like this:

SEARCH Host SHOW name, formatTime(last_update_success, "%d %B %Y") 

Gives results:

lonvmserv03

15 January 2009

rs6000

12 January 2009

sol10x86

13 January 2009

formatUTCTime(time_value, format)

Identical to formatTime, except that it does not perform timezone conversion.

friendlyTime(time_value)

Converts the internal time format into a human readable string, taking into account time zones and daylight saving times, based on the time zone of the appliance.

friendlyUTCTime(time_value)

Converts the internal time format into a human readable string, without converting the time to account for time zones and daylight saving times.

friendly_duration(duration)

Takes a duration (that is, one time minus another) and returns a human readable string of the result, such as '3 days' or '1 month' or '30 seconds'. The result is not intended to be precise, but to be quickly understood by a person.

get(item, attribute [, default ])

Retrieve attribute from item. If the item does not have the specified attribute, returns default if it is specified, or None if not.

hash(value)

Returns the MD5 hash of the specified value.

int(value [, default])

Converts a string form of an integer to an integer. Works on lists. Optionally supports a second argument, which if present will be used if the string cannot be converted.

join(value, separator)

Build a string out of a list by concatenating all the list elements with the provided separator between them.

leftStrip(value)

Returns the value with white space stripped from the start.

len(value)

Returns the length of a string or list.

lower(string_value)

Returns a lower-case version of a string.

parseTime(time_string)

Converts a date/time string into the internal format, without time zone conversion.

parseUTCTime(time_string)

Converts a date/time string into the internal format. Identical to parseTime.

parseLocalTime(time_string)

Converts a date/time string into the internal format, taking into account time zones and daylight saving times, based on the time zone of the appliance.

replace(value, old, new)

Modifies value, replacing all non-overlapping instances of the string old with new.

recurrenceDescription(recurrence)

Converts a recurrence object to a human readable string.

rightStrip(value)

Returns the value with white space stripped from the end.

single(value)

If value is a list, return just the first item of it; otherwise return the value unchanged. This is useful when following key expressions that usually return a single item, but occasionally return multiple. e.g.

search Host show name, single(#InferredElement:Inference:Primary:HostInfo.uptimeSeconds) 

size(value)

Returns the size of a list or string. A synonym for len().

sorted(values)

Returns the sorted form of the given list.

split(value [, separator ])

Split a string into a list of strings. Splits on white space by default, or uses the specified separator.

str(value)

Converts its argument to a string.

strip(value)

Removes white space at the start and end of the value.

sumValues(values)

Sums a list of values. For example, to total the count attributes of the Software Instances related to each Host:

search Host show name, sumValues(#Host:HostedSoftware:RunningSoftware:SoftwareInstance.count) 

time(time_val)

Marks a number to indicate that it is a time. The values returned by functions such as currentTime and parseTime are large numbers (representing the number of 100 nanosecond intervals since 15 October 1582), which can be manipulated by other functions and compared to each other. To return them in results in a way that the UI knows that they are times, they must be annotated as times using the time function.

toNumber(value [, base ])

Converts a string into a number. If base is given, uses the specified base for the conversion, instead of the default base 10.

toText(value [, base [, width ] ])

Converts a number to a string. If base is given, the conversion uses the specified base. Only bases 8, 10 and 16 are valid. If width is given, the string is padded so that it contains at least width characters, padding with spaces on the left.

unique(values)

Returns a list containing the unique values from the provided list.

upper(string_value)

Returns an upper-case version of a string.

value(item)

Returns item unchanged. This is only useful to bind a non-function result to a name, as described in Name binding.

whenWasThat()

Converts the internal time format to something easily readable, like '1 hour ago', '2 weeks ago', and so on.

The following function operates on IP addresses.

These functions must be passed nodes with key expressions, often just a single # to represent the current node:

destroyed(node)

Returns True if the node has been destroyed, False if not. Returns [invalid node] if the argument is not a node. Works on lists of nodes as well, returning a list of boolean values. (See the section on Search Flags and limits that permit searching destroyed nodes.)

hasRelationship(node, spec)

Takes a node and a traversal specification. Returns True if the node has at least one relationship matching the specification; False if not. Works on lists of nodes as well.

id(node)

DEPRECATED function to return a node id in string form. Use #id to return a node's id.

keys(node)

Returns a list of the keys set on the node. Returns [invalid node] if the argument is not a node. Works on lists of nodes as well, returning a list of lists of keys.

kind(node)

Returns the kind of the node. Returns [invalid node] if the argument is not a node. Works on lists of nodes as well, returning a list of kinds.

label(node)

Returns the node's label, as defined in the taxonomy. Works on lists of nodes as well, returning a list of labels.

modified(node)

Returns the node's last modified time in the internal numeric format, this includes any modification, including relationships to the node. The modified() function works on lists of nodes as well, returning a list of times. 

Modification times and host nodes

At the end of each discovery run, the automatic grouping feature considers all the Hosts, and builds a new set of automatic grouping relationships. It commits one big transaction that adjusts all the relationships to all Hosts, so every Host node usually has the same modification time.

provenance(node, attribute [, show_attribute])

Follows provenance relationships from the node, finding the evidence node that provided the specified attribute. If the show_attribute is given, returns the specified attribute of the evidence node; if not, returns a handle to the node itself.

NODECOUNT and NODES

In addition to the functions described in the previous section, the NODECOUNT and NODES keywords, defined in Traversals, behave like functions in some respects.

The following history-related functions are currently available.

These functions allow access to other aspects of the BMC Discovery system.

When search results are shown in the UI, each cell in the result table is usually a link to the node corresponding to the result row. These functions allow other links to be specified:

ncG1vNJzZmicn5jAb67MnGWcp51ksbCv0miboquTpMOmvthom5qZo2S%2BtrHRsmSlmZ6cwqKzxGadrqaTqbawutJmb2xwZWqDen2XZ5%2BtpZw%3D