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:

• • Value manipulation
  • Node manipulation
  • History functions
  • System interaction
  • Link functions

Value manipulation

The following functions operate on normal attribute values.

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
• formatQuantity(value, format) 
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

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:

gives results like

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

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 True, False, 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:

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:

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

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

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.

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:

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

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:

Gives results:

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.

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:

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:

•  
•  
•  
•  
•  
•  
•  
•  
• NODECOUNT and NODES

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. 

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.

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:

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, only single-hop relationships are supported. 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.

System interaction

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

• fullFoundationName(username)
•  

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:

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.