Graphical Editing of Queries

This section introduces the graphical query editor included in VIATRA 2.1 (released with Eclipse 2018-12). The goal of this editor is to support creating model queries in a graphical syntax, while maintaining compatibility with the existing infrastructure of VIATRA, including both the runtime and query development environment.

Requirements and Installation

The current version of the editor is based on Sirius 6.0 (and thus transitively requires Eclipse Oxygen as well). Furthermore, it requires a current version of VIATRA 2.1 IDE installed as well. To download that version, use the following p2 repository: http://download.eclipse.org/viatra/updates/release/latest

vgql install

Graphical Query Projects

Graphical query projects are specialized VIATRA query projects where graphical query definitions are stored in one source folder, and another source folders contain the textual equivalents of the graphical queries and the generated Java source code to integrate the queries into existing applications.

The following figure describes the default graphical query project structure: a source folder src (presented in red) contains vgql files describing graphical queries, and in a source folder vgql-gen (depicted in blue) contains vql files generated from the graphical query definitions. Each generated vql file represent a vgql file with the same filename, and both are stored in corresponding Java packages. Finally, a src-gen folder (depicted in green) is used to store the generated Java code from the vql files.

vgql project

Getting Started with Graphical Query Editing

A Graphical Query Project can be initialized with an appropriate project wizard. All source folders and builders are correctly set up, meaning the environment is ready to draw graph patterns and then get the appropriate generated code from it.

Initializing a New Diagram

  1. Create Graphical Query Project new vgql project

Graphical query models can be created with the Graphical Query Definition wizard, selecting a source folder (within a Graphical Query Project), a package and a file name.

  1. Create Graphical Query Definition new vgql file

After the wizard finishes, a new diagram is opened for the created file, where the pattern definitions can be edited using the usual tools.

Creating the First Pattern

Before editing, the required ecore metamodels are to be added to the diagram in the Properties view.

  1. Add an Ecore Metamodel vgql add metamodel

Note
 The editor tries to add the required plug-in dependencies automatically to the project. In rare case this may fail, causing the generated vql files will be erroneous. In such cases the generated vql files have a quick fix to add this dependency to the project.

  1. Metamodel dependency dependency quick fix

Our first pattern will be used to enumerate all members of the EClass HostInstance. For this, we need a pattern with a single, typed parameter.

  1. First pattern vgql first pattern

In order to ensure the created patterns are well-formed VIATRA queries, the queries can be validated using the default Sirius-based validators: select Validate Diagram from the pop-up menu of the diagram.

Note
 In case of errors in the specification, the generated VQL files will be erroneous. In such cases it is recommended to re-validate the diagram and look at the provided error reports to fix the issues.

Evaluating Query Results

When everything works, an error-free vql file is generated from the graphical patterns automatically. At this point, the patterns can be loaded to the Query Results view using the standard components.

  1. Using the Query Results View vgql query results

Note
 This integration assumes that the vql file is generated, so it requires the query definitions to be saved, and a short delay may be necessary after save for the view to see the latest changes. When in doubt, wait until the Eclipse build job has finished.

Missing Feature and Known Issues

The graphical pattern editor in VIATRA 2.1.0 is considered experimental, and there are a few known issues that are planned to be addressed in a later release. These issues are maintained in Bugzilla.