Visual Query Builder Overview
Visual Query Builder
In TigerGraph 3.0, we are proudly introducing Visual Query Builder -- a visual way of building your graph business logic. In the Build Graph Patterns page, you can create visual patterns in drag-and-drop fashion, which intuitively represent the questions you want to ask. For these cases, you don't need to write GSQL anymore!
By adding the Visual Query Builder component, GraphStudio becomes a complete visual SDK for users to build graph applications from end to end without writing a single line of code!
Currently, Visual Query Builder is still in beta phase. Please expect lots of improvements and changes coming in the future!
Basic Concepts
A visual pattern is a declarative way of describing a template subgraph structure, and all the subgraph structures that the visual pattern is homomorphic with are valid matching results.
Visual patterns are constructed by vertex patterns, edge patterns and widgets.
This is a basic vertex pattern within a visual pattern:
This is a vertex pattern with 2 filters, 1 aggregation, 2 ordering, and limit:
This is a vertex pattern that will be output in the pattern execution result. You can see the glow around the border and the highlight at the label:
This is a basic edge pattern:
This is an edge pattern with 1 filter:
This is an edge pattern that will be output in the pattern execution result:
This is a union widget:
A widget has input vertex patterns and output vertex patterns:
This is the visual pattern matching all the people who are younger than 30 years old in the year 2019. The filter ((2019 - birthYear) < 30) on the person vertex pattern provides the matching condition:
This is the visual pattern matching all the departments having at least one male employee:
This is the visual pattern that matches the hometown of the most people having the programming skill. The aggregation COUNT(DISTINCT p) as cnt annotates the number of people born in each city that have the programming skill. Then we order the city vertices by their descending cnt value, and choose the top 1 city:
This is the visual pattern matching all such three persons A, B and C, where A is B's friend, and A is C's friend, and B is C's manager:
This visual pattern matches all the people that born in Redwood City and attended Stanford university, but didn't work for Google:
Now you have a first sight about how the visual patterns look like. Let's walk through all the concepts in depth.
Working Panel
Working panel is the central component (both visually and logically) of Visual Query Builder. Your visual patterns are rendered here.
Like other pages in GraphStudio, you can zoom-in, zoom-out and drag the visual pattern. If you have unsaved changes to the pattern, or containing errors in the pattern, some warning messages will show at the top left corner of working panel:
If you click the message indicating errors, the Console will switch to Problems tab:
You can click the error messages. For some errors, the vertex patterns, edge patterns and widgets involved in the error will be marked red to facilitate your debugging:
Pattern List
The pattern list panel contains three sections:
Graph patterns
Description
Other than the visual view of the graph pattern, you can optionally add a description for the pattern. This can help other users to understand what problem you are trying to solve.
After changing the description, don't forget to confirm the change:
Changing description is considered as a change to the visual pattern, don't forget to save the pattern in the end.
Pattern parameters
If you added some parameters in your visual pattern, you need to provide the values to the parameters when running the pattern.
Toolbar
The toolbar options, from left to right, are the following:
toolbar option | functionality |
Save the graph pattern. | |
Save as GSQL query: show the GSQL query generated from the pattern and save. See more information here. | |
Console: open/close the console panel. | |
Configuration panel: open/close the config panel. By default the config panel is closed. You can either open the panel by clicking this button, or double click a vertex pattern or edge pattern in the visual pattern to open the config panel. | |
Render pattern options: config how much detail is shown on the pattern. See more information here. | |
Run: run the visual pattern. If the pattern doesn't have any parameters, it will run directly, otherwise the Pattern parameters section will expand for you to provide the parameter values. | |
Undo and redo: undo and redo the changes on the visual pattern. The whole editing history of each visual pattern since entering Build Graph Patterns page is preserved. | |
Edit: edit the selected vertex pattern or edge pattern. This is same as double-clicking one vertex or edge pattern. | |
Delete: delete selected vertex patterns, edge patterns and widgets. You can hold the Shift key to select multiple elements to delete. | |
Add a vertex pattern: add a new vertex pattern into the current visual pattern. See more information here. | |
Add an edge pattern: add a new edge pattern into the current visual pattern. See more information here. | |
Pick: a shortcut for adding vertex patterns and edge patterns into the visual pattern. See more information here. | |
Merge: select multiple vertex patterns, and click this button to merge them together. This is a fast way to connect multiple shorter patterns into a longer one. See more information here. | |
Widget: see more information here. | |
Filter: click this button then click a vertex pattern or edge pattern, and the config panel will enter editing mode for the selected vertex or edge pattern, with the Filter section expanded. | |
Aggregation: click this button then click a vertex pattern, and the config panel will enter editing mode for the selected vertex pattern, with the Aggregation section expanded. | |
Order by: click this button then click a vertex pattern, and the config panel will enter editing mode for the selected vertex pattern, with the Order section expanded. | |
Limit: click this button then click a vertex pattern, and the config panel will enter editing mode for the selected vertex pattern, with the Limit section expanded. | |
Output: click this button, then click vertex patterns and edge patterns of the visual pattern to toggle whether to output them or not. You can see the output glow of the selected vertices or edges turning on and off. |
Configuration Panel
You can edit vertex patterns and edge patterns from config panel.
Basic Info for vertex pattern
If you enter editing mode of a vertex pattern and expand the Basic Info section, you can edit its name, decide whether or not to put it into result, change its vertex type, provide optional matching conditions by giving a list of ids, or provide a parameter name.
You can add/drop id in the list:
Or add an input parameter:
Basic Info for edge pattern
If you enter editing mode of an edge pattern and expand the Basic Info section, you can edit its name, decide whether or not to put it into result, or change its edge type. You can also specify this edge pattern as a regex match by providing Repeat as least (a non-negative integer) and Repeat at most (a positive integer). Due to current GSQL limitations, if you decide to change these numbers, you cannot give the edge pattern a name or put it into result.
When finished editing, you need to confirm the change. You can also cancel the change if you made a mistake:
If you want another vertex pattern or edge pattern to refer to current selected vertex or edge pattern's attributes, you need to give it a name.
Filter
If you expand the Filter section, you can add/edit/delete filters for the selected vertex or edge pattern:
You can add multiple filters for each vertex and edge pattern, and they are AND relationship when executing the pattern. Building the filter is similar with building attribute filter in Explore Graph page. One thing special here is that you can refer to attributes on other vertex patterns and edge patterns. Choose Attribute of vertex or edge as expression type, then choose the name of the vertex or edge pattern whose attribute you want to refer to (see above why we need give a name to vertex or edge patterns), then choose the attribute you want to refer to.
When finished editing, you need confirm or cancel the change:
Aggregation
If you expand the Aggregation section, you can add/edit/delete aggregations for the selected vertex pattern (aggregation on edge patterns is not supported):
When finished editing, you need to confirm or cancel the change:
When talking about aggregation, it is actually grouping all the matching results by the vertex entity which match the vertex pattern, and then aggregated based on the expression. Take this example:
In the city vertex pattern, we have created 8 different aggregations:
name | aggregation expression | explanation |
countP | COUNT(DISTINCT p) | Count number of distinct person vertices matched to each city vertex. |
countMatched | COUNT(*) | Count number of matches each city vertex involves in. |
sumPHeight | SUM(p.height) | Sum the height attribute of all person vertices matched to each city vertex. |
minPBirthyear | MIN(p.birthYear) | Get the minimal height attribute of all person vertices matched to each city vertex. |
maxPBirthyear | MAX(p.birthYear) | Get the maximal height attribute of all person vertices matched to each city vertex. |
avgPBirthyear | AVG(p.birthYear) | Get the average value of height attribute of all person vertices matched to each city vertex. |
collectP | p | Collect all person vertices matched to each city vertex. |
collectPName | p.name | Collect all person vertices' name matched to each city vertex. |
Consider we have the following matching result:
We have the following aggregation result table for city vertex san jose:
city vertex | aggregation result | explanation |
san jose | countP = 2 | Kevin and Emily |
san jose | countMatched = 4 | (san jose)<-[born_in]-(Kevin)-[person_has_skill]->(programming) (san jose)<-[born_in]-(Kevin)-[person_has_skill]->(public speech) (san jose)<-[born_in]-(Emily)-[person_has_skill]->(human resource) (san jose)<-[born_in]-(Emily)-[person_has_skill]->(programming) |
san jose | sumPHeight = 676 | Kevin.height + Kevin.height + Emily.height + Emily.height = 173 + 173 + 165 + 165 |
san jose | minPBirthyear = 1991 | Min(Kevin.birthYear, Kevin.birthYear, Emily.birthYear, Emily.birthYear) |
san jose | maxPBirthyear = 1992 | Max(Kevin.birthYear, Kevin.birthYear, Emily.birthYear, Emily.birthYear) |
san jose | avgPBirthyear = 1991.5 | (Kevin.birthYear + Kevin.birthYear + Emily.birthYear + Emily.birthYear) / 4 |
san jose | collectP = [Kevin, Kevin, Emily, Emily] | |
san jose | collectPName = ["Kevin", "Kevin", "Emily", "Emily"] |
Order
If you expand the Order section, you can add/edit/delete ordering for the selected vertex pattern (ordering on edge patterns is not supported):
When finished editing, you need to confirm the change:
You can refer to aggregations in ordering expression. You can add multiple orderings, which follow the multi-key ordering rule (upper ordering dominates).
Limit
If you only want a subset of your matching result, you can use limit. Only the top limit results will be returned based on your ordering settings. If you don't have orderings, the result will be randomly picked from all matchings.
If you expand the Limit section, you can add/edit/delete limit for the selected vertex pattern (limit on edge patterns is not supported):
Toggle use limit checkbox to enable/disable limit. You can also edit the limit number:
When finished editing, you need confirm or cancel the change:
Console
The Console panel shows the graph schema, the result of the last pattern execution result, and errors the visual pattern has. Each execution of a pattern generates two types of results: a visualized graph and JSON text. On the left is a toolbar with buttons for switching between the tabs. The buttons, from top to bottom, are the following:
menu option | functionality |
Expand/Collapse: expand or collapse the Console panel. | |
Graph schema: show the graph schema. | |
Visualize graph result: show the visual result of the last run pattern. | |
View JSON result: show the raw text result in JSON format of the last run pattern. | |
Problems: show the errors in the visual pattern. |
Graph schema
Viewing graph schema makes it more convenient for developers to refer to the schema topology logic and easier to construct the visual pattern.
Visualize graph result
If the pattern execution result contains a graph structure, the result will be visualized in this panel as a graph. The panel is the same as the Explore Graph panel. The only difference is that each time you run a pattern, the previous result will be erased. In Explore Graph, the results are added incrementally.
You can switch to the JSON Result panel to see the result in JSON format.
View JSON result
You can see the JSON response of running the visual pattern from this tab:
Problems
If the visual pattern contains errors, you can see them here and debug:
Save as GSQL query
You can view the GSQL query generated from your visual pattern and save it. Then you can access this query from Write Queries page, modify your query, interpret it, install it and run it.
Render pattern options
There are three different rendering options.
By default, Pattern detail and Output glow are checked. All the filters, aggregations, ordering conditions and limits are rendered, and the vertex and edge patterns that will be in result will be highlighted with glow:
If Pattern detail is not checked, add-on marks will indicate that there are filters, aggregations, ordering conditions and limits on corresponding vertex patterns and edge patterns:
If Pattern add-on is not checked, the add-ons will be hidden:
If Output glow is not checked, the output indicating glow is hidden:
Add a vertex pattern
Add an edge pattern
Then click the target vertex pattern of the edge pattern. A new edge pattern will be added to the visual pattern. You are in the editing mode of the newly added edge pattern:
Pick
Pick is a fast way to build your visual pattern. You can pick from either graph schema or visual result.
A vertex pattern will be added to the visual pattern:
An edge pattern together with two vertex patterns will be added to the visual pattern:
A vertex pattern will be added to the visual pattern. Note that the vertex pattern contains an id condition because it is picked from an actual vertex entity from the graph:
Merge
You can merge multiple vertex patterns of the same vertex type into one vertex pattern.
Hold Shift key to select multiple vertex patterns:
Use pick and merge together and you can create a complicated visual pattern quickly.
Widget
As described in the Basic Concepts, a visual pattern represents a graph pattern matching problem. In graph theory, graph pattern matching is declarative. However, graph pattern matching is not the full story. In a lot of cases you need to represent procedural computation flow. That's why we are introducing widgets.
Intersect
And an intersection widget is added to the visual pattern:
The output vertex pattern means matching all company vertices located at redwood city, and belongs to big data industry.
The output company vertex pattern can be part of another larger pattern. You can think of the input vertex patterns of the widget as constraints of the output vertex pattern.
Union
The output vertex pattern means matching all company vertices located at redwood city, or belongs to big data industry.
Subtract
The output vertex pattern means matching all company vertices located at redwood city, but not belong to big data industry.
Next Step
Now you have a basic idea about all different functionalities of Visual Query Builder. Let's go to the next page to walk through how to build some visual patterns to solve your business questions!
Last updated
