EMF-IncQuery Query Language 0.4

This page is relevant for EMF-IncQuery version 0.4 and before! For the current version, go here!

Language concepts

For the query language, we reuse the concepts of graph patterns (which is a key concept in many graph transformation tools) as a concise and easy way to specify complex structural model queries. These graph-based queries can capture interrelated constellations of EMF objects, with the following benefits:

  • the language is expressive and provides powerful features such as negation or counting,
  • graph patterns are composable and reusable,
  • queries can be evaluated with great freedom, i.e. input and output parameters can be selected at run-time,
  • some frequently encountered shortcomings of EMF’s interfaces are addressed:
    • easy and efficient enumeration of all instances of a class regardless of location,
    • simple backwards navigation along all kinds of references (even without eOpposite)
    • finding objects based on attribute value.

Basic documentation

The current version of the graph pattern language is the VTCL syntax inherited from the model transformation framework VIATRA2. The complete VTCL language is described in the (slightly outdated) VIATRA2 documentation, as well as the VIATRA2 wiki. A VTCL language dialect specifically tailored for the context of EMF and the puposes of EMF-IncQuery is currently under development (and will be easier to use when it ships).

EMF-specific restrictions of the VIATRA2 syntax

  1. Patterns involving two or more attribute variables should be declared shareable (add injectivity constraints manually if needed). It is not easy to predict what equality semantics can be maintained between attribute values in context of the VPM modelspace or an EMF resource; valid matches with two attributes having the same native value could be erroneously filtered as a consequence. Therefore please avoid asserting injectivity between variables referring to attributes.
  2. Patterns should not expose relations in their parameters, as this is not translatable to EMF - you cannot capture structural feature instances as individual objects in general. In fact, even inside the pattern, don't use variables representing a relation, apart from declaring them.
  3. Only permitted type declarations are (the Viatra representation of) EClasses and ERelations and EAttributes. The data types should be also fine. Do not use other types.
    1. An entity constraint for an  EClass called MyClass in EPackage my.own.ePackage looks like this:
      nemf.packages.my.own.ePackage.MyClass(MyEntityVariable);
    2. A relation constraint for the EReference MyReference in said class looks like this:
      nemf.packages.my.own.ePackage.MyClass.MyReference(R, MyEntityVariable, TheReferencedEntity);
    3. A relation constraint for an EAttribute looks exactly the same:
      nemf.packages.my.own.ePackage.MyClass.MyAttribute(R, MyEntityVariable, TheAttributeVariable);
    4. EDatatype type constraints can be applied on attribute values, with a syntax similar to that used for entities:
      nemf.packages.my.own.ePackage.MyDatatype(MyAttributeVariable);
      or for the built-in datatypes:
      nemf.ecore.datatypes.EString(MyAttributeVariable);
    5. In practice, all of these look much simpler thanks to namespace import. E.g. with
      import nemf.packages.my.own.ePackage;
      in the header, the entity constraint will look like this:
      MyClass(MyEntityVariable);
    6. Finally, entity constraints can be suffixed with in OtherEntityVariable or with below OtherEntityVariable in the usual way. These extra pattern constraints will translate to direct or transitive containment, respectively, along EMF's containment hierarchy. Note that using in can be less efficient than navigating along the edges with known types. Furthermore, using even a single below constraint in a single pattern in a single EMF-IncQuery project can be especially detrimental to scalability of memory consumption and execution speed under certain conditions (your mileage may vary).  
  4. Generics (instanceOf, supertypeOf) will not currently work. Maybe one day this will (partially) change.
  5. Check() expressions cannot use native functions or ASMFunctions. They can use attribute values wrapped in value() and converted to the native type using toInteger() and co (these steps are required over VPM, and AFAIK ignored over EMF), so as to hide that they are represented as string-valued model elements in VPM. Keep in mind that fqn() is off limits, and usually name() doesn't work either (though there may be some limited heuristic support for the latter).
  6. Do no use derived references or attributes, please substitute them with the actual underlying features. Better yet, reimplement the derived feature using a helper pattern that is reused (called) throughout your VTCL code. Derived features are not supported in patterns as they can have arbitrary Java implementations and EMF-IncQuery is unable to predict when their value will change.

See advanced issues for additional topics, such as attribute handling.

User login