Visual Query Builder Overview

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

The pattern list panel contains three sections:

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:

‌

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 expand the Filter section, you can add/edit/delete filters for the selected vertex or edge pattern:

Click besides the filter expression and enter editing mode of the filter:

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:

If you expand the Aggregation section, you can add/edit/delete aggregations for the selected vertex pattern (aggregation on edge patterns is not supported):

Click beside one aggregation and enter editing mode for the aggregation. You can edit both the aggregation expression and aggregation name:

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:

Consider we have the following matching result:

We have the following aggregation result table for city vertex san jose:

If you expand the Order section, you can add/edit/delete ordering for the selected vertex pattern (ordering on edge patterns is not supported):

Click beside the ordering and enter editing mode for the ordering. You can edit both the ordering expression and whether results are in ascending or descending order:

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

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:

Viewing graph schema makes it more convenient for developers to refer to the schema topology logic and easier to construct the visual pattern.

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.

You can see the JSON response of running the visual pattern from this tab:

If the visual pattern contains errors, you can see them here and debug:

Click , then click two vertex patterns of the same vertex type:

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.