| <?xml version="1.0" encoding="UTF-8"?> |
| <cheatsheet |
| title="Creating and Executing VIATRA Queries"> |
| <intro href="https://wiki.eclipse.org/VIATRA/Query/UserDocumentation/QueryLanguage"> |
| <description> |
| Queries return a set of EMF instance model objects that match the criteria specified in a query pattern. |
| To learn more about the graph pattern-based query language, open the related help. |
| </description> |
| </intro> |
| |
| |
| <item title="Creating a new query definition"> |
| <description> |
| The VIATRA Query Definition should be located inside a <b>package</b>. You can specify the target package on the first page of the wizard. Make sure that the filename ends with the <b>.vql</b> extension and that it is locally unique. Inside .vql files, the query definition patterns are identified by their names (analogously to Java classes -- the notable exception is that an .vql file may contain multiple query definition patterns). Make sure that the patterns have unique names too.<br/><br/> |
| You need to specify the EMF domain (Ecore) models that contain the types that your queries will use. These Ecore models will be referenced by your VIATRA Query project. VIATRA Query can make use of EPackages that have been registered in the global Ecore registry (either by code or by plugin.xml), or you can also directly reference Ecore domains by using <b>generator.vqgen</b> files. It is highly recommended that the EMF model code is generated prior to defining model queries with VIATRA Query and that you check the generated plugin.xml for correctness.<br/><br/> |
| Query definition patterns can have <b>header parameters</b> that specify the input/output variables of a query. Each header parameter should have a type assigned, and it can serves both as input and output depending on the <b>parameter binding</b>. Parameter bindings may be later provided using the Details/Filters panel (right side) in the Query Explorer, or using the Java API. A binding may specify that a header parameter should correspond to a pre-determined value, e.g. a model object or a scalar value.<br/> |
| </description> |
| <subitem label="Issue: File | New | Other | VIATRA Query | VIATRA Query Query Definition"> |
| <command required="false" serialization="org.eclipse.ui.newWizard(newWizardId=org.eclipse.viatra.query.tooling.ui.newvqlfile)"/> |
| </subitem> |
| <subitem skip="true" label="On the second wizard page, give your pattern a unique name."></subitem> |
| <subitem skip="true" label="Specify packages to import."></subitem> |
| <subitem skip="true" label="Specify the header parameters of the pattern."></subitem> |
| </item> |
| |
| <item |
| title="Writing query patterns"> |
| <description> |
| In the context of the School example, we now define a query pattern that matches connected pairs of Teachers and Schools. Inside the newly created <b>.vql</b> file, paste the following code:<br/><br/> |
| |
| pattern TeachersOfSchool(T:Teacher, Sch:School) = {<br/> |
| School.teachers(Sch,T);<br/> |
| }<br/> |
| <br/> |
| This pattern includes a simple <b>edge constraint</b> of type School.teachers, specifying that T-Sch pairs in the match set (the result of a query) should be Teacher-School instance pairs that are actually connected by a reference of this type. |
| </description> |
| </item> |
| |
| <item title="Executing queries on instance models with the Query Explorer"> |
| <description> |
| To execute queries (i.e. invoke pattern matching) with VIATRA Query's development tools, the <b>Query Explorer view</b> is the tool to use. Query Explorer features a three-panel layout where the middle section shows actual query results (i.e. match sets against instance models), the collapsible left panel shows the <b>Pattern Registry</b> (a collection of registered and validated query pattern definitions, specified either in the workspace ("Runtime") or plug-ins already loaded in your Eclipse instance ("Plug-in"). <br/><br/> |
| The (also collapsible) right panel in the Query Explorer (<b>Details/Filters</b>) may be used to inspect a detailed view of output parameter values, as well as provide input bindings using cell editors and picker dialogs. VIATRA Query allows the user and the programmer to determine which parameters are used as input and which are output when a query is actually being issued (instantiated), therefore the same pattern can be used to: <br/> |
| (a) list the Teachers of a given School (with School as an input parameter), <br/> |
| (b) or to find the School that is associated to a given Teacher (Teacher is the input parameter), <br/> |
| (c) or to list all Schools with their Teachers (both are output parameters), <br/> |
| (d) or to simply verify whether a given object is a Teacher, the other one is a School, and that the Teacher is indeed associated to the School instance (both are input parameters).<br/><br/> |
| |
| Make sure that you are experimenting with the Query Explorer in the same Eclipse instance where the school.queries project is located (and which already contains school, school.edit and school.editor as plug-ins). |
| </description> |
| <subitem skip="true" label="Open the Query Explorer view, if not already open."> |
| <command required="true" serialization="org.eclipse.ui.views.showView(org.eclipse.viatra.query.tooling.ui.queryexplorer.QueryExplorer)"></command> |
| </subitem> |
| <subitem skip="false" label="Import your query definition patterns by putting the Query Definition Editor in focus, and then pushing the green button in the top right corner of the Query Explorer."></subitem> |
| <subitem skip="false" label="Apply the query patterns on an instance model, by opening an instance model in the School Editor, and then pushing the green button again."></subitem> |
| <subitem skip="true" label="Experiment with providing input bindings to the TeachersOfSchool pattern, by selecting the pattern in the middle section, then opening the Details/Filters panel, and then providing an appropriate Teacher instance as the value for the second parameter in the Filter column."></subitem> |
| </item> |
| |
| </cheatsheet> |
