Introduction to Model Query Language (MQL)¶
MQL Expression¶
Similar to algebraic expression, MQL expression describes operations performed against the targeted model objects. At run time, the MQL engine inside the Tool evaluates the MQL expression and returns the values or the selected objects. MQL expressions can be used to define Views or construct validation rules. They can also be extended to form an independent query. The resulting is called MQL Query Expression.
Naming Conventions¶
In addition to the CIM full naming convention, MQL also supports a simplified naming convention to facilitate construction of query strings.
A MQL query string based on the full CIM naming convention uses the exact class and property tags in a CIM/XML document to specify the class and the property. The following illustrates a MQL query string based on full CIM naming convention
cim:BaseVoltage/[cim:BaseVoltage.nominalVoltage]>110
In a simplified form, first, the namespace can be omitted, such as
BaseVoltage/[BaseVoltage.nominalVoltage]>110
Secondly, the class name before the property can also be omitted. Therefore, the above query string can be further simplified as
BaseVoltage/[nominalVoltage]>110
In the case that the ambiguity is resulted from use of the simplified class and property names, the MQL parser will alert users to provide more specific information. This, however, rarely happens thanks to the existing CIM naming conventions.
MQL query string is case-insensitive and whitespace-ignorant. The following query string will be equivalent to the above query strings
basevoltage / [ nominalvoltage ] > 110
Constructs of MQL Expression¶
Fundamentally, an MQL expression is made of literals of variables, constants, and operators.
Property Variables¶
A property variable represents a specific attribute/association of an object or related to an object. A property variable could be a numeric or a string. MQL parser uses the context information (i.e. the operator type) to infer the data type of a property variable.
A property variable must be enclosed by a pair of square brackets, i.e. []. There are two types of property variables: direct property variables and indirect property variables. The direct property variables represent the attributes/associations of the objects, for example
[IdentifiedObject.name] (attribute of the object)
[ConductingEquipment.BaseVoltage] (association of the object)
While the direct property variables provide a simple way to select/filter the objects based on one or more or object attributes/associations, there are many cases you want to select/filter the objects using attributes/associations of other associated objects, for example, finding ACLineSegments whose associated BaseVoltages have a nominalVoltage value greater than 110 kV. The indirect property variables represent the attributes/associations of the associated objects. To specify the indirect property variables, one must provide the navigation path from the original object to the associated objects, using “->”. For example, the following indirect property specify attribute nominalVoltage of the associated BaseVoltage object which can be accessed by navigating using association ConductingEquipment.BaseVoltage
[ConductingEquipment.BaseVoltage->nominalVoltage]
In a more general form, the indirect property variable can be represented as follows
[navigation_path->property]
The navigation path can be made of unlimited number of navigation steps linked with “->”. The following indirect property variable contains a multi-step navigation path highlighted in red,
[``VoltageLevel.Substation->Substation.Region->SubGeographicalRegion.Region``->IdentifiedObject.name]
Constants¶
MQL supports the following types of constants:
| Type of Constant | Description | Examples |
|---|---|---|
| Numeric | An integer or float number represented in either ordinary or scientific notation | 10, 3.14159, 1.2e-5 |
| String | A sequence of characters, either double quoted or not. A string constant doesn’t have to be double quoted. However, if the string constant contains the special characters, such as blank space, operator symbol, it must be double quoted. It is strongly recommended to double quote the string constant. As a special case, if the string constant contains the double quote character i.e. “, the double quote character must be encoded (or escaped) as ‘"’. | XFMR1 true “Area 1” ST"1 (i.e. ST”1) |
| Wild card | A wild card constant is a special string constant that matches anything. It is typically used to evaluate whether a property exists or not in the object. | * |
Operators¶
Operators are functionalities and can be represented by symbols such as ‘+’. MQL supports the following operators:
| Operator | Operator Name | Syntax | Input Data Type | Output Data Type | Priority | Description |
|---|---|---|---|---|---|---|
| * | Multiplication | a*b | Numeric | Numeric | 5 | Multiplies two numeric literals/expressions |
| / | Division | a/b | Numeric | Numeric | 5 | Divides the first numeric literal/expression by the second one. |
| + | Addition | a+b | Numeric String | Numeric String | 4 | Adds two numeric literals/expressions or concatenate two strings. This operator is depreciated for string. Use ‘&’ for string concatenation. |
| - | Subtraction | a-b | Numeric | Numeric | 4 | Subtracts the second numeric literal /expression from the first one. |
| & | Concatenation | a&b | String | String | 4 | Concatenate two strings. |
| == | Exactly equal to | a==b | Numeric String | Boolean | 3 | Performs a comparison to determine if two numeric/string literals/expressions are EXACTLY equal. |
| = | Partially equal to | a=b | String | Boolean | 3 | Performs a comparison to determine if the second string literals/expressions is a sub-string of the first one. |
| > | Greater than | a>b | Numeric | Boolean | 3 | Performs a comparison to determine if the first literal/expression is greater than the second one. |
| >= | Greater than or Equal to | a>=b | Numeric | Boolean | 3 | Performs a comparison to determine if the first literal/expression is greater than or equal to the second one. |
| < | Less than | a<b | Numeric | Boolean | 3 | Performs a comparison to determine if the first literal/expression is less than the second one. |
| <= | Less than or Equal to | a<=b | Numeric | Boolean | 3 | Performs a comparison to determine if the first literal/expression is less than or equal to the second one. |
| ! | Logical negation (NOT) | !a | Boolean | Boolean | 3 | Negates the (Boolean) result of a logical expression. |
| && | Logical AND | a&&b | Boolean | Boolean | 2 | Performs a logical AND operation for the (Boolean) results of two logical expressions. |
| || | Logical OR | a||b | Boolean | Boolean | 1 | Performs a logical OR operation for the (Boolean) results of two logical expressions. |
| ? : | Ternary conditional | a ? b : c | Boolean | Any | 6 | Condition a is evaluated true or false as a Boolean expression. On the basis of the evaluation of the Boolean condition, the entire expression returns value b (if true) or c (if false). |
| | | Trial and Error | a | b |… | Any | Any | 6 | The property expression is evaluated sequentially till an evaluation is successful. If the evaluation of Expression a succeeds, the evaluation result will be returned. Otherwise, the next one, i.e. Expression b will be evaluated and so on. |
Note
if an MQL query string is declared in an XML file, some of the above operators shall be encoded. For example, Operator ‘&&’ shall be encoded as ‘\&\&’. The following table lists five commonly used XML reserved characters and the corresponding character references.
| Character | Reference |
|---|---|
| < | \< |
| > | \> |
| & | \& |
| ' | \' |
| " | \" |
Property Expression¶
A property expression is an infix-style notation of property operations. At least one property variable and one operator will be included in a property expression.
The priority of the operators determines the sequence of the operations. For example, in expression a+b*c, the operation sequence is 1) b*c = d; 2) a + d =e. This is because operator * has higher priority than operator +.
Parentheses, however, can be used to change evaluation order of expressions. Expressions enclosed in parentheses have the highest evaluation precedence. Nested expressions enclosed in parentheses are evaluated in inner-to-outer order. This is quite similar to the arithmetic expression. In the above example, if we want to add a and b first, the expression will become (a+b)*c.
Logical Property Expression¶
Logical property expression is special type of property expression. It provides a mechanism to find objects that matches a specific filtering condition. MQL logical property expression is quite like any logical expressions in a programming language, such as C/C++ or Java. It is made of literals of variables, constants, and operators. The evaluation of the logical expression must return a Boolean value: true or false.
Simple Logical Property Expression¶
A simple logical property expression is composed of property variables, operators (except logical operators: !, && and ||), and optionally constants. The evaluation result of a simple logical property expression must be a Boolean value, i.e. true or false. The followings are some of the examples of a simple logical property expression:
[BaseVoltage.nominalVoltage]>110.0
[ConductingEquipment.BaseVoltage->nominalVoltage] == 110.0
[ACLineSegment.x]/[ACLineSegment.r] >= 100
[SubGeographicalRegion.Region->IdentifiedObject.name] = “AREA 1”
[TapChanger.highStep] <= [TapChanger.lowStep]
The following examples are valid property expressions, but not logical property expressions, because the outputs of these expressions are not Boolean values.
[IdentifiedObject.name]
[BaseVoltage.nominalVoltage] / 110
[TapChanger.highStep] * [TapChanger.stepVoltageIncrement]
Composite Logical Property Expression¶
A composite logical property expression is composed of one or more simple logical property expressions and the logical operators, i.e. NOT (!), AND (&&) and OR(||). The following are some of the examples of a composite logical property expression:
[BaseVoltage->nominalVoltage]>110 && [EquipmentContainer->Region->Region->name] == “AREA 1”
!([SynchronousMachine.type]==”SynchronousMachineType.generator”)
([EquipmentContainer->Substation->name]=ST1) || ([EquipmentContainer->name]=ST1)
MQL Query Expression¶
MQL query expression consists of two elements: a class name and a logical property expression, separated by a slash, as shown below
Class_Name/Logical_Property_Expression
Class name in a MQL query expression is the first matching criterion. It specifies what kind of objects to find. The class name must be the valid name of a standard or extended CIM class, or a wild card. The wild card, i.e. ‘*’, means “any classes”. For example, the following query string can be used find any objects whose names are “1”, regardless of their types (classes).
*/[IdentifiedObject.name]==”1”
At run time, the MQL engine inside the tool evaluates the logical property expression for each of the objects of the specified class and returns those objects whose evaluated values are ‘true’. For example, the following MQL query string is used to find all of the BaseVoltage objects whose attribute nominalVoltage is greater than 110 kV.
BaseVoltage/[nominalVoltage]>110
More Examples¶
See Learning MQL by Examples (1).