Query Language Functions
Another option for manipulating attributes is to apply functions to them. Functions are applied using the familiar parenthesis syntax:
The following topics are covered in this section:
The following functions operate on normal attribute values.
- bin(value, bins [, legend])
- booleanLabel(value, true_label, false_label, other_label)
- duration(start_time, end_time)
- defaultNumber(value, default_value)
- extract(value, pattern [, substitution ])
- fmt(format, ...)
- fmt_map(format, items)
- formatNumber(value, singular, plural, other)
- formatQuantity(value, format)
- formatTime(time_value, format)
- formatUTCTime(time_value, format)
- get(item, attribute [, default ])
- int(value [, default])
- join(value, separator)
- replace(value, old, new)
- split(value [, separator ])
- toNumber(value [, base ])
- toText(value [, base [, width ] ])
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
Less than 64
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:
1G to 4G
512M to 1G
64M to 512M
Less than 64M
More than 4G
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
Calculates the amount of time elapsed between the two dates and returns the result as a string of the form 'days.hours:minutes:seconds'.
Returns the number of 100 nanosecond intervals since 15 October 1582. This example query returns the hosts created in the last 7 days:
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
\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" .
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:
Whereas the following expression can only be done with
fmt() because it calls the
The following example shows the
fmt() function used to show the results of floating point arithmetic:
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.
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:
The following example shows applying friendly formatting the raw capacity of a StoragePool:
Total Raw Capacity
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:
15 January 2009
12 January 2009
13 January 2009
formatTime, except that it does not perform timezone conversion.
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.
Converts the internal time format into a human readable string, without converting the time to account for time zones and daylight saving times.
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.
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.
Build a string out of a list by concatenating all the list elements with the provided separator between them.
Returns the value with white space stripped from the start.
Returns the length of a string or list.
Returns a lower-case version of a string.
Converts a date/time string into the internal format, without time zone conversion.
Converts a date/time string into the internal format. Identical to
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.
Converts a recurrence object to a human readable string.
Returns the value with white space stripped from the end.
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.
Returns the size of a list or string. A synonym for
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.
Converts its argument to a string.
Removes white space at the start and end of the value.
Sums a list of values. For example, to total the count attributes of the Software Instances related to each Host:
Marks a number to indicate that it is a time. The values returned by functions such as
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
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.
Returns a list containing the unique values from the provided list.
Returns an upper-case version of a string.
Returns item unchanged. This is only useful to bind a non-function result to a name, as described in Name binding.
Converts the internal time format to something easily readable, like '1 hour ago', '2 weeks ago', and so on.
These functions must be passed nodes with key expressions, often just a single # to represent the current 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.)
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.
DEPRECATED function to return a node id in string form. Use
#id to return a node's id.
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.
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.
Returns the node's label, as defined in the taxonomy. Works on lists of nodes as well, returning a list of labels.
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
NODES keywords, defined in Traversals, behave like functions in some respects.
The following history-related functions are currently available.
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.
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:
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_type, os_version, and hosted SoftwareInstances for a collections of Hosts:
See also the post-processing function
displayHistory in Results after processing.
These functions allow access to other aspects of the BMC Discovery system.
Returns the full name of the user with the given user name or None if no such user exists.
Returns the value of the system option key.
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:
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:
link is a search query to execute; value is the value to display in the UI and to be used in exports.