Query language details

This section describes the functions and syntax of the Helix IPLM query language, as well as the fields that can be searched for each Helix IPLM object type.

Introduction

One of the base requirements in an IP management system is the ability to filter the list of design objects based on certain criteria. To enable this filtering mechanism Helix provides a sophisticated query engine.

Examples:

Display the latest version of all the IPs in a Library with a name containing the word "cpu"
Grant to a group the read permission on all the IPs with a property "power" greater than 30

The Expression Language (EL) is a simple language used to specify expressions. These expressions can be used in queries, thus providing a powerful and flexible tool to define criteria that can be as complex as necessary.

Syntax

An expression is specified as a Unicode string.

White spaces are ignored, except in literal strings (see Literals).

Value types

All values used in an expression have a type.

A values of a given type can be coerced - i.e. converted - to a value of another type. See the documentation of each type for more details.

Most expressions, when they are evaluated, attempt to coerce the values of their components in order to obtain values they can use. See the documentation of each expression for more details.

Coercing a value to a value of the same type gives the same value. Coercing to null is impossible.

Null

The null type has only one value: null.

Most expressions cannot be evaluated in a meaningful way if one of their components is null, and will therefore simply evaluate to null in that case. See the documentation of each expression for more details.

Literal (case-insensitive):

null

Coercion:

None.

Boolean

The boolean type has two values: true and false.

Literal (case-insensitive):

true, t
false, f

Coercion:

to string: either "true" or "false"
to list: a list containing only the value

Integer

The integer type contains the 64-bit signed integers (-263 to 263 - 1).

Literal:

0
1
+1
-1
123456
-123456

Coercion:

to boolean: false if the value is 0, true otherwise
to float: the float value that is the closest to the integer value
to string: a string that represents the value in decimal base, without any grouping separators
to list: a list containing only the value

Float

The float type contains the 64-bit double-precision floating numbers (2-1074 to (2-2-52)·21023).

Literal (case-insensitive):

0.0
.0
0.
1.0
+1.0
-1.0
123e67
-123.45E67
123.45e-67
-123.45E-67

Coercion:

to boolean: false if the value is 0.0, true otherwise
to integer: the integer value that is the closest to the float value
to string: a string that represents the value, without any grouping separators
to list: a list containing only the value

String

The string type contains sequences of Unicode characters of any length.

String literals can be either single- or double-quoted.

In string literals, a character is escaped by preceding it with a backslash (\). This has the following implications:

The backslash character must always be escaped
In single-quoted string literals, the single quote character (') must be escaped
In double-quoted string literals, the double quote character (") must be escaped

Regardless of these rules, any character may be escaped.

Literal:

''
""
"Hello!"
'Hello "world"!'
"Hello \"world\"!"
"Hello world! It's a beautiful day today!"
'Hello world! It\'s a beautiful day today!'
"爱不是占有,是欣赏"

Coercion:

to boolean: false if the string is empty, true otherwise
to list: a list containing only the value

List

The list type represents sequences of values of mixed types (including other lists).

Literal:

[]
[1]
["Hello!"]
["Hello!", 123, 45.67]
[123, [456, "abc"]]

Coercion:

to boolean: false if the list is empty, true otherwise

Object

The object type represents non-scalar values. Objects are containers of fields that can be of any type (including other objects). See the documentation of field access for more details.

Literal:

None.

Coercion:

to boolean: true
to list: a list containing only the value

Lambda

The lambda type represents expressions.

Lambdas are specified as an expression between curly braces ({ and }).

Literal:

{ 1 + 3 }
{ "Hello!" }
{ now() - days(5) }
{ admin and any(groups, { name = "scientists" }) }

Coercion:

to boolean: true
to list: a list containing only the value

Expressions

An expression is evaluated in a context to produce a value. There are several types of expressions. Most expressions are compositions of other expressions.

The evaluation context contains a root value, typically an object.

Expressions are documented in order of precedence: expressions appearing first below are evaluated first. Parentheses (( and )) can be used to change the evaluation order.

Literals

Literals are the simplest expressions. A literal evaluates to the value it represents.

Notation:

See Value Types.

Examples:

123
"Hello!"
{ 1 + 3 }

Unary operations

Field Access

This expression evaluates to the value of a named field of an object. Its is evaluated as follows:

If its operand is an object, then:
1. If the object has a field with the specified name, the field access evaluates to the value of that field.
2. If the object does not have a field with the specified name, the evaluation gives an error. The choice of giving an error rather than evaluating to null was made to avoid overlooking a typo in the name of the field.
If its operand is a list, the field access is evaluated with each element of that list as operand, and the resulting values are joined as a list. In other words, the field access is mapped on its list operand.
If its operand is not an object nor a list, the field access evaluates to null.

A field access operation without operand uses the root value of the evaluation context. If the name of the field is it, it evaluates to the root value itself. This is particularly useful in lambdas.

A field access may be enclosed in backquotes (`example`). It must be enclosed in backquotes if

It starts with a character that is not a letter or an underscore, e.g. `3xy`
It contains a character that is not a letter, a digit or an underscore, e.g. `total-count`

Notation (case-sensitive):

value.nameOfTheFieldInValue
nameOfTheFieldInRootValue
`3xy`
value.`total-count`

Examples:

user.email is "john.doe@example.com"
group.name is "admin"
name is "chipsets.cpu" (assuming the root value is an object that has a field name)

Function Call

This expression evaluates to the result of the application of a builtin function. All parameters of a function call are expressions and are evaluated first.

If the name of the function is unknown, the evaluation gives an error.

See Functions for more details.

Notation (case-sensitive):

date_time(2017, 10, 10)
days(duration + 5)

Examples:

now() is the current timestamp
days(1) is 86400000

Logical NOT

The prefix unary operator NOT coerces its operand to a boolean value and evaluates to the negation of that value. If its operand cannot be coerced to a boolean, it evaluates to null.

Notation (case-insensitive):

!
not

Examples:

!true is false
!false is true
!0 is true
!1 is false
not -1 is false
not "" is true
not "abc" is false

IS NULL

The postfix unary operator IS NULL evaluates to true if its operand is null, and to false otherwise. It is one of the two only operators that don't evaluate to null when given a null operand.

Notation (case-insensitive):

is null

Examples:

null is null is true
123 IS NULL is false

IS NOT NULL

The postfix unary operator IS NOT NULL evaluates to true if its operand is not null, and to false otherwise. It is one of the two only operators that don't evaluate to null when given a null operand.

Notation (case-insensitive):

is not null

Examples:

null is not null is false
123 IS NOT NULL is true

Multiplication, Division and Modulo

These arithmetic binary operations coerce their operands to number values according to the following rules:

If at least one operand is a float value, both operands are coerced to float values
Otherwise, both operands are coerced to integer values

If at least one operand is null, these operations evaluate to null. Unless specified otherwise, these operations evaluate to a float value if at least one operand is a float value, and to an integer value otherwise.

Multiplication

Arithmetic multiplication.

Notation:

Examples:

3 * 5 is 15
-2*7 is -14

Division

Arithmetic division. This operation always evaluates to a float value.

Notation:

Examples:

3 / 2 is 1.5
4 / 2 is 2.0
-5/2.5 is -2.0

Integer Division

Arithmetic integer division. This operation always evaluates to an integer value.

Notation (case-insensitive):

//
div

Examples:

3 // 2 is 1
4 div 2 is 2
-7 DIV 2.5 is -3

Modulo

Arithmetic modulo. This operation always evaluates to an integer value.

Notation (case-insensitive):

%
mod

Examples:

3 % 2 is 1
4 mod 2 is 0
-5 MOD 3 is -2

Addition and Subtraction

These arithmetic operations follow the same rules as the previous ones.

Addition

Arithmetic addition.

This operation first coerces its operands according to the following rules:

If at least one operand is a list value, both operands are coerced to list values
If at least one operand is a string value, both operands are coerced to string values
Otherwise, the rules defined for previous arithmetic operations apply

The addition of two list values evaluates to the concatenation of these list values. The addition of two string values evaluates to the concatenation of these string values.

Notation:

Examples:

3 + 2 is 5
-4+2.5 is -1.5
"The answer is " + 42 is "The answer is 42"
1 + [2, 3] is [1, 2, 3]

Subtraction

Arithmetic subtraction.

Notation:

Examples:

3 - 2 is 1
-4-2.5 is -6.5

Comparisons

Unless specified otherwise, these operations coerce their operands according to the following rules:

If at least one operand is a list value, both operands are coerced to list values
If at least one operand is a string value, both operands are coerced to string values
If at least one operand is a boolean value, both operands are coerced to boolean values
If both operands are number values:
1. If at least one operand is a float value, both operands are coerced to float values
2. Both operand are coerced to integer values

Equal to

This operation evaluates to true if its operands are equal.

Notation:

=
==

Examples:

1 = 1 is true
1 = "1" is true
1 == 2 is false
"hello" == "hello" is true
"Hello" == "hello" is false
[1, 2] = [1, 2] is true

Not Equal to

This operation evaluates to true if its operands are not equal.

Notation:

!=
<>

Examples:

1 != 1 is false
1 != "1" is false
1 <> 2 is true

Greater than

This operation evaluates to true if its left operand is strictly greater than its right operand.

Notation:

Examples:

1 > 0 is true
1 > 1 is false
"b" > "a" is true
"a" > "A" is true
true > false is true

Greater than or Equal to

This operation evaluates to true if its left operand is equal to, or greater than, its right operand.

Notation:

>=

Examples:

1 >= 0 is true
1 >= 1 is true

Less than

This operation evaluates to true if its left operand is strictly less than its right operand.

Notation:

Examples:

0 < 1 is true
1 < 1 is false

Less than or Equal to

This operation evaluates to true if its left operand is equal to, or less than, its right operand.

Notation:

<=

Examples:

1 <= 0 is false
1 <= 1 is true

Wildcard Matching

The wildcard matching operation coerces its operands to string values. If that coercion is successful, it evaluates to true if its left operand matches its right operand according to the following rules:

The question mark (?) matches any single character
The star (*) matches any sequence of characters of any length, including zero
The backslash (\) escapes the next character (the backslash itself must be escaped, i.e. doubled)
Any other character matches itself case-insensitively

Because of that last rule, wildcard matching can be used for case-insensitive string comparison.

Notation:

*=

Examples:

"abc" *= "abc" is true
"abc" *= "a??" is true
"abc" *= "?b?" is true
"abc" *= "a*" is true
"abc" *= "a\*" is true
"abc" *= "a\\*" is false
"abc" *= "a?" is false
"abc" *= "*a*" is true
"abc" *= "ABC" is true
123 *= "1*" is true
true *= "*R*" is true

Regular Expression Matching

The regular expression (regex) matching operation coerces its operands to strings. If that coercion is possible, it tries to parse its right operand as a regular expression according to the rules of the java.util.regex.Pattern Java class. If that parsing succeeds, it evaluates to true if its left operand matches the regular expression.

Notation:

~=

Examples:

"abc" ~= "abc" is true
"abc" ~= "a.." is true
"abc" ~= "a." is false
"a." ~= "a\\." is true
"ab" ~= "a\\." is false
"ab" ~= "a\." is true

Logical AND

This operation coerces its operands to boolean values and evaluates to the logical conjunction of those values.

Important: If at least one operand is null, it evaluates to null.

Notation (case-insensitive):

&
&&
and

Examples:

false and false is false
true and false is false
false and true is false
true and true is true

Logical OR

This operation coerces its operands to boolean values and evaluates to the logical disjunction of those values.

Important: If at least one operand is null, it evaluates to null.

Notation (case-insensitive):

|
||
or

Examples:

false or false is false
true or false is true
false or true is true
true or true is true

Functions

Time Functions

These functions are useful to work with timestamps in milliseconds.

now()

This function evaluates to the current timestamp.

datetime(year, [month, [day, [hours, [minutes, [seconds]]]]])

This function coerces all its parameters to integer values and evaluates to the timestamp corresponding to the specified date. If any parameter cannot be coerced to an integer value, or has an illegal value, this function evaluates to null.

This function uses the time zone in the evaluation context, which is typically provided under the hood by the client.

Parameters:

year: any integer value
month: 1 to 12, defaults to 1
day: 1 to 31, defaults to 1
hours: 0 to 23, defaults to 0
minutes: 0 to 59, defaults to 0
seconds: 0 to 59, defaults to 0

Examples:

datetime(2017, 10, 12, 14, 37) is the timestamp of the 12th October 2017 at 2:37 PM, in the time zone specified in the evaluation context
datetime(2015) is the timestamp of the 1st January 2015 at midnight, in the time zone specified in the evaluation context

datetime_utc(year, [month, [day, [hours, [minutes, [seconds]]]]])

This function is identical to the date_time function but uses the UTC time zone instead of the one specified in the evaluation context.

Duration Functions

These functions coerce their only parameter to a float value and evaluate to the number of milliseconds in the corresponding duration.

seconds(n)

This function evaluates to the number of milliseconds in n seconds.

minutes(n)

This function evaluates to the number of milliseconds in n minutes.

hours(n)

This function evaluates to the number of milliseconds in n hours.

days(n)

This function evaluates to the number of milliseconds in n days.

weeks(n)

This function evaluates to the number of milliseconds in n weeks.

List Functions

These functions expect two parameters. They coerce the first parameter to a list value and the second to a lambda.

filter(list, lambda)

This function evaluates to a list made of the elements of the given list for which the given lambda evaluates to true.

Examples:

filter([1, 2, 3], { it > 1 }) is [2, 3]

map(list, lambda)

This function evaluates to a list made of the lambda applied to each elements of the given list.

Examples:

map([1, 2, 3], { it * 2 }) is [2, 4, 6]

any(list, lambda)

This function evaluates to true if the lambda evaluates to true for at least one element of the list.

Examples:

any([1, 2, 3], { it >= 3 }) is true
any([1, 2, 3], { it >= 4 }) is false

all(list, lambda)

This function evaluates to true if the lambda evaluates to true for all elements of the list.

Examples:

all([1, 2, 3], { it >= 1 }) is true
all([1, 2, 3], { it >= 2 }) is false

none(list, lambda)

This function evaluates to true if the lambda evaluates to false for all elements of the list.

Examples:

none([1, 2, 3], { it >= 4 }) is true
none([1, 2, 3], { it >= 3 }) is false

contains(list, value)

This function is a shorter form of the any function that does not require a lambda.

The function call contains(list, value) is equivalent to any(list, { it == value })

Examples:

contains([1, 2, 3], 2) is true
contains([1, 2, 3], 4) is false

Queries

Queries use an expression as predicate to determine which of the queried objects must be included in the results. That expression is similar to the WHERE clause in a SQL SELECTstatement.

The specified expression is evaluated for each of the queried object, with that object used as root value of the evaluation context. The value produced by that evaluation is then coerced to a boolean. If the resulting value is true, the object is included in the results. If the resulting value is false or null, the object is skipped.

Domain Model Objects

Alias

creation_timestamp (integer)
creator (user)
fqn (string): the FQN of the alias, e.g. chipsets.gpu123@LATEST
ipl (line)
ipv (IPV): the IPV currently referenced by the alias
line: see ipl
locked (boolean)
name (string): the name of the alias, e.g. LATEST

Attribute

creation_timestamp (integer)
creator (user)
name (string)
value (string)

Group

active (boolean)
builtin (boolean)
description (string)
external (boolean)
name (string)

IP

attributes (list of attributes)
creation_timestamp (integer)
creator (user)
description (string)
dm_type (string)
dmtype: see dm_type
fqn (string): the FQN of the IP, e.g. chipsets.gpu456
hook_post_load (string)
hook_post_release (string)
hook_post_update (string)
hook_pre_release (string)
host (string)
ipls (list of IPLs)
labels (list of labels)
lib: see library
library (library)
lines: see ipls
name (string): the name of the IP, e.g. cpu123
properties (object with custom properties)

Any other field is checked against the custom properties.

IPL

aliases (list of aliases)
attributes (list of attributes)
creation_timestamp (integer)
creator (user)
fqn (string): the FQN of the line, e.g. chipsets.cpu123@.TRUNK
ip (IP)
ipvs (list of IPVs)
labels (list of labels)
name (string): the name of the line, e.g. TRUNK

IPV

aliases (list of aliases): the aliases currently referencing the IPV
all_resources (list of IPV resources)
attributes (list of attributes)
creation_timestamp (integer)
creator (user)
fqn (string): the FQN of the IPV, e.g. chipsets.gpu456@5.TRUNK
ip (IP)
ipl (IPL)
labels (list of labels)
line: see ipl
message: see version_message
old_aliases (list of aliases): the aliases previously referencing the IPV
private_resources (list of IPV resources)
project_props (string)
properties (object with custom properties)
repo_path (string)
resources (list of IPV resources)
version (integer)
version_message (string)

Any other field is checked against the custom properties.

IPV Resource

alias (alias): the alias of the IPV resource, if any

All other fields are the same as the IPV of the IPV resource.

Label

color (string)
creation_timestamp (integer)
creator (user)
name (string)

Library

attributes (list of attributes)
creation_timestamp (integer)
creator (user)
description (string)
fqn (string): the FQN of the Library, e.g. chipsets.
hook_post_load (string)
hook_post_release (string)
hook_post_update (string)
hook_pre_release (string)
ips (list of IPs)
labels (list of labels)
name (string): the name of the Library, e.g. chipsets
vendor (string)

Snapshot

all_resources (list of snapshot resources)
creation_timestamp (integer)
creator (user)
description (string)
fqn (string): the FQN of the snapshot
resources (list of snapshot resources)
top_ipv (snapshot resource)
workspace (workspace)

Snapshot Resource

All fields are the same as the IPV of the IPV resource.

User

active (boolean)
admin (boolean): whether the user is in the admin group
builtin (boolean)
description (string)
email (string)
external (boolean)
fullname: see full_name
full_name (string)
name (string)

Workspace

all_resources (list of workspace resources): all the workspace resources, including the top resource
creation_timestamp (integer)
creator (user)
last_update_timestamp (integer)
last_updater (user)
path (string)
p4_client (string)
resources (list of workspace resources): the workspace resources, excluding the top resource
top_ipv (workspace resource): the top resource

Workspace Resource

alias (alias): the alias of the workspace resource, if any
last_update_timestamp (integer)
last_updater (user)

All other fields are the same as the IPV of the workspace resource.