# Graphical Query Editor

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`

## 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.

## 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

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

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

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

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

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

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.