Query Language Functions

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

SEARCH Host SHOW len(name) 

The following topics are covered in this section:

Value manipulation

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.

extract(value, pattern [, substitution ])

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 and applies user friendly formatting, putting the values into bits, bytes, 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

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.

Node manipulation

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

SEARCH Host SHOW name, keys(#)
// Use the time() function to tell the UI that the result is a time.
SEARCH Host SHOW name, time(modified(#))

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 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.

History functions

The following history-related functions are currently available.

creationTime(node)

Returns the number of 100 nanosecond intervals between 15 October 1582 and the time the node was created. Also works on lists of nodes.

createdDuring(node, start, end)

Returns true if the node was created during the time range specified with start and end. For example, to find all the application instances created between 1st July and 10th July 2008.

SEARCH BusinessApplicationInstance
WHERE createdDuring(#, parseTime("2008-07-01"), parseTime("2008-07-10"))

destroyedDuring(node, start, end)

Returns true if the node was destroyed during the time range specified with start and end. To find all the application instances destroyed between 1st July and 10th July 2008:

SEARCH FLAGS (include_destroyed, exclude_current) BusinessApplicationInstance
WHERE destroyedDuring(#, parseTime("2008-07-01"),
                          parseTime("2008-07-10"))

destructionTime(node)

Returns the time the node was destroyed in the internal time format. If the node is not destroyed, returns 0. Works on lists of nodes as well, returning a list of destruction times.

eventOccurred(node, start, end)

Takes a node and two times in the internal format. Returns True if the node was modified between the specified times; False if not. Works on lists of nodes as well. Returns [invalid time] if the times are invalid.

Specialist history functions

The following history functions can be used for specialist purposes:

newInAttr(node, attr, timeA, timeB)

Retrieves the node's specified attribute at the two times. The attribute is expected to contain a list. Returns a list containing all items that were present in the list at timeB that were not present at timeA.

attrSpread(node, attr, timeA, timeB)

Returns a list containing all unique values that the attribute has had between the two times.

newInAttrSpread(node, attr, timeA, timeB, timeC)

A cross between newInAttr and attrSpread. Returns a list of values for the attribute that existed at any time between timeB and timeC, but which did not exist at any time between timeA and timeB.

historySubset(nh, timeA, timeB, attrs, rels)

Reports on a subset of the node history between the two times. attrs is a list of attribute names to report; rels is a list of colon-separated relationship specifications to report. For example, the following query will show changes to os_typeos_version, and hosted SoftwareInstances for a collections of Hosts:

SEARCH Host SHOW
  name,
  historySubset(#, 0, currentTime(),
     ["os_version", "os_type"],
     ["Host:HostedSoftware:RunningSoftware:SoftwareInstance"])

See also the post-processing function displayHistory in Results after processing.

System interaction

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

fullFoundationName(username)

Returns the full name of the user with the given user name or None if no such user exists.

getOption(key)

Returns the value of the system option key.

Link functions

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:

nodeLink(link, value)

link is a node id or node reference, for example the result of a key expression; value is the value to display in the UI and to be used in exports. For example, to create a table listing Software Instances and their Hosts, with links from the host names to the Host nodes:

SEARCH SoftwareInstance SHOW
  name AS "Software Instance",
  nodeLink(#RunningSoftware:HostedSoftware:Host:Host, #RunningSoftware:HostedSoftware:Host:Host.name) AS "Host"

queryLink(link, value)

link is a search query to execute; value is the value to display in the UI and to be used in exports.

Was this page helpful? Yes No Submitting... Thank you

Comments