Learning MQL by Examples (1)¶
In this tutorial, we will use 6 examples to demonstrate how to formulate MQL query strings for different purposes. These examples are based on a test model that comes with the installation package. The test model is called test.xml under the \TestModels folder. Users are encouraged to load this model file into the tool and try each example to gain some hand-on experience. For syntax of MQL, please refer to Introduction of Model Query Language (MQL).
Example 1: Low Voltage Lines¶
This example demonstrates how MQL can be generally used to filter the objects. The objective is to find all of the ACLineSegments that are of 138 kV or below. It is a little more complicated than the typical attribute-based filtering. The nominal voltage information is not directly defined in class ACLineSegment. Instead it is specified in the associated BaseVoltage object. Therefore, the query becomes: “finding all of the ACLineSegment objects whose associated BaseVoltages are less than or equal to 138 kV”. The corresponding MQL query string can be expressed as follows:
ACLineSegment/[ConductingEquipment.BaseVoltage->BaseVoltage.nominalVoltage]<=138
or in a simplified form
ACLineSegment/[BaseVoltage->nominalVoltage]<=138
In the above example, the property variable contains one-step navigation, i.e. from ACLineSegment to BaseVoltage via association ConductingEquipment.BaseVoltage.
Example 2: High X/R Ratios¶
This example demonstrates how multiple attributes can be combined or manipulated to filter the objects. The goal of this query is to find all of the ACLineSegments that have X/R ratio larger then 20. The corresponding MQL string can be expressed as follows:
ACLineSegment/[ACLineSegment.x]/[ACLineSegment.r]>20
or in a simplified form:
ACLineSegment/[x]/[r]>20
The above query string shows that the arithmetic operation, i.e. division, is first used to find the ratio of X/R and then the computed ratio is compared with 20. Any ACLineSegments with an X/R ratio of above 20 will meet the above filtering criterion.
Example 3: MW Analogs of SynchronousMachine¶
This example demonstrates how multiple filtering criteria can be combined to filter the objects. The query is to find all of the MW Analogs that are associated with any SynchronousMachines. There are two filtering criteria identified:
- The PowerSystemResources associated with the Analog must be a SynchronousMachine.
- The measurementType of the Analog must be “ThreePhaseActivePower”
A MQL string can be formulated to combining the above two filtering criteria, as shown below
Analog/[PowerSystemResource->SynchronousMachine.type]=* && [measurementType]=ThreePhaseActivePower
To find whether the associated PowerSystemResource is a SynchronousMachine, we navigate to the associated PowerSystemResource and test whether a required attribute of SynchronousMachine is available. Note a wild card (i.e. *) which can be matched with any values is used to find whether the specified attribute is available. The measureType condition can be easily specified based on the value of the attribute. Finally two filtering criteria can be combined using the logical AND operation (i.e. &&). The query result shall include all of the Analogs meeting two logical conditions.
Example 4: Fixed ShuntCompensators¶
This example demonstrates how to use wild card to find objects that contain or miss a specified property. Wild card matches any values. Therefore, we can use wild card to filter whether a specified property exists or not. In this example, we will try to find all of the ShuntCompensators that are not used to regulate the kV/MW, the so-called fixed shunts. The following MQL string can be formulated to find these fixed shunts.
ShuntCompensator/!([ RegulatingCondEq.RegulatingControl]=*)
In this example, the wild card is used to test whether an association from ShuntCompensator to RegulatingControl is available. Note the formulated logical expression must be negated (using operator NOT or !) in order to find those that do not contain the association.
Example 5: Normally Open Switches¶
This example demonstrates how to find the objects that share the same properties regardless of their types or classes. CIM is an object-oriented model. Many of the attributes and associations are defined at the base class level and inherited by all of the concrete classes derived from the base class. For example, attribute Switch.normalOpen is defined at the base class Switch. This attribute is inherited by all of the concrete classes derived from class Switch, including Breaker and Disconnector. In this example, we will try to formulate a MQL query string that can be used to find all of the Switches (Breakers or Disconnectors) that are normally open.
*/[Switch.normalOpen]==”true”
In this example, the wild card is used to represent any classes. The query results may include Breakers or Disconnectors or any other type of Switches that are normally open.
Note
this kind of query can only be used to find the objects, not to filter the objects, because the returned objects are not of the same type.
Example 6: Equipments Contained in a Substation¶
In this example, we will try to find all of the Equipments that are contained in a Substation. The challenge of this example is that Equipments contained in a Substation may have different containership hierarchy. For example, a SynchronousMachine has a containership hierarchy of Equipment→VoltageLevel→Substation, while a PowerTransformer is directly contained in a Substation, i.e. Equipment→Substation. The following MQL query string can be used to find all of the Equipments that are contained in Substation PARKHILL.
*/([EquipmentContainer->Substation->name]=PARKHILL) || ([EquipmentContainer->name]=PARKHILL)
In this example, the wild card is used to represent any classes. The query results may include any Equipments that are indirectly contained by a Substation or directly contained in a Substation. More specifically, the first part of the query is to find Equipments that are indirectly contained through the child VoltageLevels, such as SynchronousMachines, ShuntCompensators, Breakers. The second part of the query is used to find Equipments that are directly contained in the Substation, such as PowerTransformers. The logical OR (i.e. ||) operator is used to find the objects that meet either of the two conditions.
As an exercise, let’s expand this query to allow for the Bay class. Some of the switching devices, such as Breakers and Disconnectors, may be grouped under Bay objects which are contained by VoltageLevels. For these Equipments, the containership path to a Substation is Equipment→Bay→VoltageLevel→Substation. How should we expand the above MQL query string to allow for this situtatin?