Copyright © 2015-2018 TigerGraph, Redwood City, California. All Rights Reserved.
For technical support on this topic, contact email@example.com with a subject line starting with "Graphstudio"
Detailed Table of Contents
- GraphStudio License
- User Access Management
- Design Schema
Map Data To Graph
- Add Data Source
- Map Data Source To Vertex Type Or Edge Type
- Map Data Columns To Vertex Or Edge Attributes
- Map A Constant Value To An Attribute Or Token Function Input
- Add Data Filter
- Delete Options
- Undo And Redo
- Publish Data Mapping
- Expand Panels
- Load Data
- Search Vertices In Graph
- Expand From Vertices
- Find Paths Between Two Vertices
- Find Connections Between Multiple Vertices
- Graph Exploration Panel Options
- Write Queries
- Export And Import Solution
- Known Issues
- What's Next
The TigerGraph GraphStudio™ UI (User Interface) provides an intuitive, browser-based interface that helps users get started quickly with graph-based application development tasks: designing a graph schema, creating a schema mapping, loading data, exploring the graph, and writing GSQL queries. This guide serves as an introduction and quick-start manual for the GraphStudio UI.
As of June 2018, the GraphStudio UI is certified on following browsers:
Not all features are guaranteed to work on other browsers.
GraphStudio In The Cloud
If you are using GraphStudio in the TigerGraph cloud environment, you can directly access GraphStudio via a browser.
For on-premise deployment, the system by default is listening to port 14240. Any machine connected to the server can access GraphStudio from a browser with the following address:
In v1.2, the default TCP/IP port for GraphStudio has changed from 44240 to 14240, to avoid possible port conflicts with Zookeeper.
If the GraphStudio UI does not show, the visualization service might be off. To verify, in a linux shell of the server, type
If it is off, turn it on:
The home page of GraphStudio contains links to each of the five steps of solving a business problem: Design Schema, Map Data To Graph, Load Data, Explore Graph, and Write Queries. Users can also navigate to each step from the buttons in the left menu bar. Each of these major steps has its own page. To hide/show the left menu bar, click the top-left menu button: TigerGraph Admin Portal UI Guide ).. Clicking the logo on the banner will take you back to the home page. You can click to go to the Admin Portal (read more at
GraphStudio Online Test Drive
Visit TigerGraph Test Drive demos at: http://testdrive.tigergraph.com/
The GraphStudio online Test Drive features several instances of the TigerGraph system, each one targeting a different use case. Each copy of TigerGraph has a GraphStudio interface and is preloaded with application-specific queries and synthetic data. These demo applications are provided in a read-only mode. Users can explore and play with pre-installed queries. Users on these demo systems cannot save changes to the graph schema, the loading job, or queries. The corresponding buttons are disabled.
GraphStudio operation requires a valid license. The GraphStudio license is independent from the TigerGraph database license; some TigerGraph product editions come with a GraphStudio license pre-installed. The GraphStudio license expiration date might be different from that of the TigerGraph license.
Clicking the GraphStudio Information iconwill show the current GraphStudio license status. If a GraphStudio license key has not been installed, the license status will look like the following:
Without a license, it is not possible to navigate to the Design Schema, Map Data To Graph, Load Data, Explore Graph or Write Queries pages.
Applying a GraphStudio License Key
Click thelink on the bottom of the license status to be redirected to Admin Portal configuration page to apply a GraphStudio license key:
Enter the license key in the Update License text box, and click update. Clickat the top-right corner to go back to GraphStudio. If you click the Info icon again, you should see the updated license. Now you can start to use GraphStudio.
The Developer Edition package includes a pre-installed license. Please note that Developer Edition may not be used for commercial use.
User Access Management
GraphStudio follows TigerGraph user authentication and role-based access control model. Read more in the document Managing User Privileges and Authentication v2.1 .
If user authentication is not enabled, then no user login is needed for GraphStudio. If user authentication has been enabled, then users must provide credentials (e.g., username and password) to enter GraphStudio. In addition, your system administrator can integrate TigerGraph with other user access management systems (e.g., LDAP, Active Directory, or SAML-based Single Sign On). See the TigerGraph System Administrators Guide v2.1 for how to set up LDAP or SSO.
After login, the user is assigned to one of the graphs for which they have access. The user can switch to a different graph (see Select A Graph below).
To logout, click the User clickand then the Sign Out icon.
Role- and Graph- Based Access Control
TigerGraph uses role-based access control with several pre-defined roles. Each role is a logical collection of data access privileges, such as querywriter or admin. Each user is assigned one or more roles by a graph admin user or by a superuser. Roles are also graph-specific. For example, user Pat could be an admin on graph G1 but a querywriter on graph G2.
Currently, role assignments can only be made in the GSQL shell. In the future Admin Portal will support user management functionality.
When a user logs in and/or selects a graph, GraphStudio will disable certain actions based on the user's role on that graph. On each working panel, a warning note will alert the user to features which are disabled. For example, in the current version of GraphStudio, users with querywriter, queryreader, or observer role will see the following warnings on the Design Schema working panel:
The table below summarizes the built-in roles and of their key privileges on GraphStudio:
Create a new
GSQL - yes;
GraphStudio - not yet supported
GSQL - yes;
GraphStudio - not yet supported
|Create a data mapping||YES||YES||YES||
|View a data mapping||YES||YES||YES||YES||YES||YES|
|Explore a graph||YES||YES||YES||YES||YES||
|Write a query||YES||YES||YES||YES||
|Run a query||YES||YES||YES||YES||YES||
Select A Graph
Beginning with Version 1.2, the TigerGraph system can support multiple graphs within one TigerGraph instance. Read more at MultiGraph - An Overview v2.1 . If you have access to more than one graph, at the top of the Menu Bar a graph dropdown list will appear. Use the dropdown list to select a graph.
|"MyGraph" is the current graph||The graph dropdown list is expanded.|
Currently, not all of the TigerGraph capabilities for creating and using multiple graphs are available through GraphStudio; some operations can only be performed from the GSQL shell. Below is the list of current MultiGraph-related limitations.
Creating a New Graph Schema:
- A superuser can create a graph schema only if no graphs currently exist.
- Admin and designer users cannot create a graph schema in GraphStudio.
Modifying a Graph Schema:
- A superuser can modify a graph schema if and only if exactly one graph exists.
- Admin and designer users cannot modify a graph schema in GraphStudio.
- Only superusers can modify visual styling of schemas – color , vertex icons, and layout. Visual styling is supported even when there are multiple graphs.
A graph admin user or superuser grants each user access to particular graphs. Currently, granting and revoking privileges must be done as gsql commands; user roles cannot be managed in GraphStudio yet.
Designing the graph schema is the first and most important step of solving a business problem. The graph schema is the model of the problem, and all of the subsequent steps depend on the graph schema. If you are not already in Design Schema mode, click "Design Schema" on the left side menu bar.
- Only users with superuser privilege can use Design Schema to modify a graph schema.
- If there is already more than one graph, then the superuser can only modify the visual style of the graphs.
When there is no graph schema in the system, this page will show some hints:
Otherwise this page will visualize the schema:
Each circle represents a vertex type, and each link represents an edge type. You can drag the circles to change their positions. There are two ways to zoom in and out. If you have a touchpad, two-finger moving up zooms out; two-finger moving down zooms in. Simliarly, if your mouse has a scroll wheel, spinning forward zooms out; spinning backward zooms in.
Note: The relationship between a vertex type and a vertex instance of a graph is like the relationship between a table and one record of a table in the relational database world. The relationship between an edge type and an edge instance is similar. In the Design Schema step, the user defines vertex types and edge types to model the data schema. After the schema has been created, the next two steps, Map Data To Graph and Load Data, are for loading data into the graph.
Add A Vertex Type
Click the add vertex type buttonto add a vertex type. The add vertex type window will pop up:
In this window you specify a vertex type name, primary id name, and its type. GraphStudio will automatically select a color for your vertex type icon. You can change the vertex type color by clicking the value under the "Color hex" label. A color palette window will pop up allowing you to choose a new color:
Once you are satisfied with the color, click anywhere outside of the color palette window to set the color.
You can also choose an icon for the vertex type by clicking the Select Icon button. Then a Select Icon window will pop up. Select an icon that fits the vertex type semantic best. You can type in keywords to help filter the icons and find the best match faster.
Adding and Deleting Attributes
To add an attribute, click the green plus sign at the right of the Attributes section:
Provide a name and data type for your new attribute. Optionally, you can specify a default value for the attribute. (If you do not specify, every data type has a system default value. For example, the default value for an integer is 0.)
To delete an attribute, click the red minus sign to the right of the attribute to delete an existing attribute.
Once you are satisfied with the vertex type settings, click the Add buttonto add the vertex type. A new circle will appear in the working panel. You can drag the circle to any desired position.
Add An Edge Type
Click the add edge type buttonto add an edge type. The working space will enter Add Edge mode and the button color will change to green . Click the button again to exit Add Edge mode.
Each edge type has a source vertex type and a target vertex type. First, click the source vertex type. A hint will appear on the vertex type circle:
Then click the target vertex type. The add edge type window will pop up:
You must specify an edge type name. The source vertex type and target vertex type are selected based on your clicking action. However, you can change that by choosing another vertex type in the dropdown list.
By default, the edge type is undirected. To make the edge type directed, mark the Directed checkbox:
If Directed is checked, another checkbox will appear for you to choose whether the edge type should include reverse edges. Including reverse edges provides more flexibility when designing queries. Unselect the Reverse edge checkbox ONLY IF your machine memory is very tight, because if there is no reverse edge, queries will not be be able to traverse backwards along this directed edge type, from the target vertex to the source vertex.
Editing edge type attributes is the same as editing vertex type attributes.
Once you are satisfied with the edge type settings, click the Add buttonto add the edge type. A new link between the selected source vertex type circle and target vertex type circle will appear in the working panel.
You can add multiple edge types between the same source vertex type and target vertex type pair. Moreover, an edge can use the same vertex type for both its source vertex type and its target vertex type, e.g., a Friendship edge from Person vertex to Person vertex.
Edit Vertex Or Edge Type
You can edit the vertex types or edge types at any time after you add them. Just click one vertex type circle or one edge link, and then click the edit button(double clicking on the selected vertex/edge will have the same effect), to make the Edit Attributes window pop up:
Once you are satisfied with the change, click the Update button.
Delete Vertex Or Edge Type
You can delete a vertex type or an edge type by first choosing the vertex type circles or edge type links, then clicking the delete button. In order to delete multiple vertex types and edge types, hold down the "Shift" key while you click, to select multiple items.
Redo And Undo
You can redo and undo your changes by clicking the two buttons:. The whole history since the time you entered Design Schema page is recorded.
Once you are satisfied with the graph schema, click the publish schema buttonto publish the schema to the TigerGraph system. Publishing may take up to 2 minutes.
The current implementation of Publish Schema operates by deleting the previous graph and creating a new one. All previously loaded graph data will be erased.
Currently, if you want to modify a graph schema and also save data, you should perform the schema change in GSQL rather than in GraphStudio. If you perform a SCHEMA_CHANGE JOB in the GSQL shell instead of using GraphStudio to modify the schema, the graph data will be preserved (as much as is consistent with your intended schema changes.)
If you have already created a data mapping and written queries, GraphStudio will try its best to preserve your work when you publish your modified schema:
- All your queries will be saved as query drafts, so you can install the queries again after you change your schema. If a query has a conflict with the new schema (e.g., referring to a vertex type that is deleted), you need to fix it before installing the query.
GraphStudio will migrate your data mapping based on your changes to the schema. Since GraphStudio records your whole operation history, the migration is smart enough to cover most cases. The basic migration rules are the following:
- Rename vertex types and edge types
- Remove mappings to deleted vertex types and edge types.
- Remove mappings to deleted or modified attributes.
- New vertex types, edge types and new attributes won't be mapped.
- After the schema is successfully published, GraphStudio will instruct you to go to the Map Data To Graph page to verify and publish the revised data mapping. If any mapping is not correct, you can fix it. You must publish the migrated data mapping; otherwise, it will be lost.
If you want to save your previously developed work, export the Solution first (see details at Export and Import Solution ).
Map Data To Graph
After you have created a graph schema, the next major step is to map your data to the schema. Click "Map Data To Graph" on the left side menu bar. The working panel is split into a left panel and a right panel. Initially when there is no data mapping yet, the left panel will display only the graph schema.
The main steps are
- Add data source(s)
- Map data source(s) to vertex/edge types
- Map data source columns to vertex/edge fields
- Publish data mapping
Add Data Source
In this step, you inform GraphStudio about your data source files. A data source is a file containing structured data to be loaded into the graph, creating vertex and/or edge instances. The first step for data mapping is to specify your data sources. Click the Add Data Source buttonto add data sources. The Add Data Source window will pop up:
Initially, there are no data files in the server data folder.
Upload File To Server
Click the Upload File button. A file selection window will appear. Choose the data file you want to use. The file will be uploaded to the server data folder:
There is a limit of 500MB on file size. If you are using on-premise deployment, you can bypass this limit by directly putting the data files or their softlinks in the server data folder, located at <TigerGraph_root_dir>/loadingData.
Once the file is uploaded to the server, it will appear in the "Files on server" list on the left side of the Add Data Sources window.
Data Sources must be .csv files
The Add Data Source box will only upload files which end in ".csv". If you manually place files in the <TigerGraph_root_dir>/loadingData folder, please don't put any files into subfolders because they will be ignored.
Configure the File Parser
In this step, you tell GraphStudio how to parse your data source file. If your data source file is in tabular format, the parser will split each line is split into a series of tokens . Click on one file from the file list to choose it. The TigerGraph backend will parse the file, using default settings, and show the parsing result as a preview table on the right side:
By default, the column delimiter is comma ",", the end of line character is "\n", the enclosing character is not used, and the first row of data is not treated as header. Click on the down arrow in a table column to choose a different option for file format, delimiter, or end of line. The file will immediately be re-parsed when you change a setting. The enclosing character is used to mark the boundaries of a token, overriding the delimiter character. For example, if your delimiter is comma (,), but you have commas in some strings, then you can define either double quotes (") or single quotes (') as the enclosing character to mark the endpoints of your string tokens. It is not necessary for every token to have enclosing characters; the parser will use enclosing characters when it encounters them.
Figure: same source file with the Has Header option on.
Once you are satisfied with the file parsing configuration, click the add buttonto add the data source into left working panel. The data source will be shown as a file icon on the working panel:
Once you think a file is no longer needed, you can remove it from server by clicking the delete buttonto the left of each file. Please note that you also need to manually remove data mapping using this file as data source, otherwise when you load data later, a file not found error will be triggered.
Map Data Source To Vertex Type Or Edge Type
In this step, you link (map) a data source file to a target vertex type or edge type. The mapping can be many-to-many, which means one data source can map to multiple vertex and edge types, and multiple data sources can map to the same vertex or edge type. Click the map data source to vertex or edge buttonto enter map data source to vertex or edge mode. When you are finished mapping data sources, clicki the button again to exit this mode.
Then, click the data source file icon. A hint will appear over the icon:
Next, click the target vertex type circle or edge type link. A dashed link will appear between the data source and the target vertex or edge type:
A red hint will appear if the target type has not yet received a mapping for its primary id(s).
Map Data Columns To Vertex Or Edge Attributes
In the step, you link particular columns of a data source to particular ids or attributes of a vertex type or edge type. First, choose one data mapping from one data source to one vertex or edge type (represented as a dashed green link on the left working panel). When selected, the dashed line becomes orange (active), and the right working panel will show two tables. The left table shows the data source columns along with the first row's tokens as sample data. The right table shows the fields of the target vertex or edge. For a vertex, its fields are primary id and attributes. For an edge, its fields are source vertex, target vertex, and attributes.
In order to a column in the data source to a vertex or edge field, first click the row representing the data column in the left side data source table:
Then, click the row representing the target field in the right side table. A green arrow appears to show the mapping. Repeat as needed to create all the mappings for this table-to-vertex/edge pair. Since many-to-one mapping is allowed, it is not necessary for one table to provide a mapping for every field in the target vertex/edge.
Using a Token Function
GraphStudio provides a set of built-in functions to preprocess data source tokens before loading them in to the graph. For example, you can concatenate two columns in the data source and load them as an attribute. This section describes how to use these token functions.
First click the add token function button. The Add Token Function window will pop up. Click the down arrow to see the list of available token functions and select one. For some functions, you may also specify the number of input parameters. (Most token functions have a fixed number of input parameters; gsql_concat can accept any positive number of inputs). Click Add.
A token function table will be added to the attribute mapping panel. You can drag the tables to rearrange them. Token functions act as an intermediate step in the mapping. Create mappings from the data source table to the token function table, and then from the token function table to the vertex/attribute table The final result looks like below:
If the data source columns and the vertex/edge attributes have very similar names (only capitalization and hyphen differences), you can click the auto mapping button. All similar columns will be mapped automatically.
Map A Constant Value To An Attribute Or Token Function Input
Sometimes, a user may need to load a constant value to an id or attribute. Here we show how to do this in GraphStudio.
Loading A Constant to An Attribute
In the right working panel, double-click on the target id or attribute (in the left column of the right table). In the example below, the attribute "label" has been double-clicked:
This will cause the Load Constant window to pop up. Type in the constant value, and click the Add button to apply the mapping.
After adding the constant value, the attribute's label will change to id/attribute = "(your valid input value)" .
To modify or remove a constant mapping, double-click the id/attribute again. In the Load Constant window, enter the new value, or erase the value if you want to remove the mapping. Click the Add button to apply.
Use A Constant Input for a Token Function
First add the token function. Then double-click on the target input (in the left column of the token function table). In the example below, "Input 0" has been double-clicked.
This will cause the Load Constant window to pop up. Type in the constant value and click the Add button to apply the mapping.
After adding the constant value, the input's label will change to Input = "(your input value)" .
The constant value can be modified or removed by double-clicking the label and editing the value in the Load Constant window.
Add Data Filter
You can add a data filter to a data mapping so that only data records which meet conditions that you specify will be loaded into the graph. This is equivalent to the WHERE clause in a GSQL load statement.
You can add one data filter for each data mapping from a data source to a vertex type or edge type, and the data filter only applies to that one mapping. Consider the following data mapping:
By default, there is no data filter. Click the Data Filter button to start creating a data filter. The Add Data Filter window will appear. The window contains three parts:
- The top section shows one row of sample data from your file, as a handy reference to the file's contents.
- The middle sections shows what the data filter looks like when it is converted a to GSQL WHERE clause. For more details, see the WHERE Clause section in the GSQL Language Reference Part 1 - Defining Graphs and Loading Data
- The bottom section is where you define your data filter. The data filter will be converted to a GSQL WHERE clause and shown in real time.
A data filter condition is a Boolean expression, which can be a nested set of conditions. GraphStudio evaluates the condition for each line in your input file. If the condition evaluates to true, then the line is loaded.
First, click the Build Data Filter chooser (with default value "None"). A menu will appear, with many Boolean expression templates. Choose one of the options. If you plan to build a nested condition, start with your top level. The first several options are for comparison expressions:
After this are several more options, using operators such as AND, OR, NOT, IN, BETWEEN...AND, IS NUMERIC, and IS EMPTY.
Note that each of these expressions calls for 1, 2, 3, or a list of operands, and the operands themselves can be expressions. When you select an expression, additional choosers will appear below, for you to specify the operand expressions. The operand choices are context-sensitive, but typically they include
- a Data Column from the input file
- A constant value
- If the operator is AND, OR, or NOT, then the operand can be another condition. Thus is how conditions can be nested.
Suppose you are loading friendship edges where the input data fields are (person1, person2, friendship_start_date). You want to load only the records where person1 is Tom and the friendship began on or before 2017-06-10. The data filter looks like the following:
After adding the data filter, the right working panel will look like this:
Hovering the mouse over the data filter indicator Data Filter button or double-click the data filter indicator . the Add Data Filter panel will appear.will make the data filter condition appear. If you want to modify the data filter, click the
To remove a data filter, select "None" at the top level dropdown of Build Data Filter section and then click Add. The data filter will be deleted.
In the Map Data To Graph page, you can delete anything that you added. Choose what you want to delete, then click the delete button. Press the "Shift" key to select multiple icons you want to delete. Note that you cannot delete vertex or edge types in this page.
Delete Data Source
Select the data source file icon(s), then click the delete button.
Delete Data Source To Vertex Or Edge Mapping
Select the dashed green link(s) between data source and mapped vertex/edge type, then click the delete button.
Delete Data Column To Vertex Or Edge Attribute Mapping
Select the green arrow(s) between data source table and vertex/edge attributes table, then click the delete button.
Delete Token Functions
Select the token function table(s), then click the delete button.
Undo And Redo
You can undo or redo changes by clicking the Back or Forward buttons, respectively:. The whole history since the time you entered the Map Data To Graph page is recorded.
Publish Data Mapping
Once you are satisfied with the data loading procedure, click the publish schema buttonto publish the data loading procedure to the TigerGraph system. It takes about 2 to 3 seconds for publishing each data source mapping.
The following three buttons allow you to select the relative sizing of the left and right working panels:
By default, the two windows have equal widths. Click the left button to widen the left working panel, or click the right button to widen the right working panel.
After mapping data sources to the graph schema, you can start loading data. Click "Load Data" on the left side menu bar to go to the Load Data panel.
The "Load Data" interface is vertically separated into two parts:
Data Mapping Overview and Manipulation
- Provides a general view of the graph and the data mapping.
- Shows the loading progress of each data source.
- Enables the user to manage data with buttons in the control panel.
- Displays the current total numbers of vertices and edges, and the specific number of each type.
- Shows the total number of vertices and edges loaded over time in 5-second intervals.
To display real-time statistics, this page checks the number of vertices and edges every 5 seconds, which adds overhead. To maximize loading performance, move to a different page after starting loading, and only come back here occasionally to check on progress.
GraphStudio provides two types of loading:
- Partial Loading: load a sample of the data sources which the user selects.
- Complete Loading: load all of the data sources completely.
Load Some Data Sources
Select one or more data sources (holding down the "shift" key to select multiple sources), and click on the "start loading" buttonon the toolbar.
Load All Data Sources
Click on a blank space in the data mapping overview panel to unselect the data sources, and click on the "start loading" buttonon the toolbar.
After loading starts, the "start loading" buttonwill become the "stop loading" button . You can click on it to stop the current loading job. At the same time, the loading status of the data source will become "terminated". All pending loading jobs are also cancelled.
Clear Graph Data
Click on the "clear graph data" buttonon the toolbar to clear the graph data. This operation will take approximately 1 minute or more, depending on the size of your graph and the hardware.
After the clear operation, the graph vertex and edge number statistics will both drop to 0.
After data has been loaded, you can go to the Explore Graph or Write Queries pages.
After data has been loaded, the Explore Graph page allows you to search for vertices in a graph, to discover nearby vertices which satisfy conditions of your choice, and to find the paths between vertices.
Below is an example of an exploration result:
The Explore Graph page is vertically divided into three parts, from left to right:
The Explore Graph Menu (narrow panel with black background)
The menu options, from top to bottom, are the following:
Search vertices: select specific vertices with conditions.
Expand from vertices: find neighborhood of the specified vertices.
Find paths: find paths between the selected source vertex and target vertex.
- Find connections: find connecting paths between a set of vertices.
- Search vertices: select specific vertices with conditions.
The Parameter Panel
- Set filters, conditions and other parameters for the selected option from the Explorer Menu Bar.
The Graph Exploration Panel
- The exploration result is displayed in this panel.
Adjust the results display, take a snapshot of the display, and modify selected data objects in the result.
The menu buttons, from left to right, are the following:
- Change layout : Arrange the vertices according to one of the built-in layout patterns, such as sphere, tree, circle, or force.
- Locate vertices in result : Search the exploration result by vertex id or attribute value.
- Only show selections : First select one or more objects. Clicking the button will hide all the objects which are not selected.
- Hide : First select one or more objects. Clicking the button will hide the selected vertices and edges (or all if none is selected).
- Undo : Undo the last changeto the visualization result set (that is, changes to which objects are included in the result set).
Redo : Redo the most recent undone change to the visualization result set (that is, changes to which objects are included in the result set).
Database changes (adding or deleting vertices/edges, editing attributes) cannot be undone with the Undo feature.
Also, Undo/Redo do not include layout and display change (e.g., positioning of objects and display of attributes).
- Add new vertex : Add a new vertex into the visualization result as well as to the graph database .
- Add new edge : Add a new edge into the visualization result as well as to the graph database .
- Edit attributes : Change the attributes of the selected object in the visualization result as well as the graph database .
- Delete selected elements : Delete the selected elements from the visualization result as well as the graph database .
- Save screenshot : Save the current visualization result as a png file.
- Change settings : Select which attribute values to display with each vertex or edge type. Enable/disable popup display of all attributes when the cursor hovers over a vertex or edge.
The Parameter Panel can be hidden by clicking its corresponding button in the Explore Graph Menu.
Search Vertices In Graph
The first button in the Explore Graph Menu is the "search vertices" option. This option lets you select an initial set of vertices for your exploration. It is also the default option when you first enter the Explore Graph page. Clicking the button again will hide the Parameter Panel to increase space for the Graph Exploration Panel.
The Configuration section in the Parameter Panel specifies which types of vertices you want to include in your selection. By default, all vertex types are selected. Uncheck some boxes if you want to narrow your selection.
Search Vertices By ID
Enter a vertex id in the Parameter Panel, and click on "Search". Any vertex whose id matches exactly will be shown. If your search includes multiple vertex types, there might be multiple matches because vertices of different types can have the same ID.
Let GraphStudio Pick Vertices
If you don't have a particular vertex ID in mind, you can have GraphStudio pick some vertices for you. In the Parameter Panel, enter a number of vertices to pick, and click on "Pick Vertices". The explorer will pick this number of vertices
each vertex type
inclued in your search.
NOTE: If you keep exploring the graph in the Explore Graph page, the previous exploration result won't be automatically erased. Instead, your new exploration result will be merged together with the previous visualized graph. The objects from the most recent exploration action will be selected (highlighted with a thick gray border) to distinguish them from the previous visualized graph.
Expand From Vertices
The second button in the Explore Graph Menu is the "Expand from vertices" option. "Expand" in this context means find 1-step or multi-step neighbors of the selected vertices. Clicking the button again will hide the Parameter Panel to increase space for the Graph Exploration Panel. To expand from vertices, you need to have at least one selected vertex in the Graph Exploration Panel. If no vertices are visible, please refer to the previous section "Search Vertices in Graph" to search for some vertices.
Shortcut: double-clicking on a vertex with expand to all neighbors of that vertex, up to a maximum of 200 vertices.
Choose Vertices To Expand
There may already be some selected vertices from the previous action. A vertex that is selected has a thick gray border around it. The standard click and shift-click behaviors for selecting one or multiple objects applies:
- Click on a vertex to select it. Any previously selected objects are unselected.
- Shift-click on an unselected object to add it to the selection set.
- Shift-click on a selected object to remove it from the selection set.
To unselect all vertices, click on a blank area of the panel.
Set Expansion Conditions
GraphStudio lets you expand multiple steps from the target vertices, as long as the resulting number of vertices and edges does not exceed the limit for visualization (default limit is 2500 edges). The conditions for each expanstion step are specified independently.
In the Parameter Panel, set the conditions for each expansion step:
- Maximum number of edges include for each vertex. The effect is that vertices which have more neighbors than this limit will not have all their neighbors included in the expansion.
- Edge types to include.
- Target vertex types to include.
Initially, the expansion conditions panel for only one expansion step is shown. Click "Add Expansion Step" to add more expansion steps.
Similarly, you can remove expansion steps by clicking the "Remove Expansion Step" button.
After setting the conditions for each expansion step, click on the "Expand" buttonto perform the expansion. The Graph Exploration Panel will be updated to include the expansion result. The expansion starting vertices will be highlighted with a white border. Here is a sample two-step expansion starting from 2 vertices:
Find Paths Between Two Vertices
The third button in the Explore Graph Menu is the "Find paths" option. This option find paths between two vertices with your specified conditions. Clicking the button again will hide the Parameter Panel.
Choose Starting Vertex And Destination Vertex
The top section of the Parameter Panel asks for your desired starting vertex and destination vertex.
There are two ways to provide this information. Each of the two vertices can be selected by either method.
If you know the ID and vertex type for a vertex, you can type in the infomation. The vertex does not need to be currently displayed in the Graph Exploration Panel. Enter the vertex type, followed by a space, followed by the vertex id. For example, if you want to use a Person vertex whose ID is "Caral", type the following in the input box:
If the vertex you want is already displayed in the Graph Exploration Panel, a more convenient way is the following:
- Click on the input box.
- Click on the desired vertex in the Graph Exploration Panel. Then, GraphStudio will automatically generate the value for you.
You can click the swap icon (two green arrows) at right to switch the starting vertex and the destination vertex.
Set Conditions For Paths
GraphStudio provide three types of path searches:
- One shortest path: search for and highlight a shortest path between the two vertices.
- All shortest paths: search for and highlight all shortest paths between the two vertices.
- All paths: search for and highlight all valid paths between the two vertices.
Since path-finding queries may have high computational cost if the graph is very large, a parameter is available to limit the path length.
In addition to the search type and the maximal length, you can also specify the valid vertex types and edge types which may be included in the paths.
After selecting the endpoint vertices and setting the search conditions, click on the "Find Paths" buttonto start the search.
Find Connections Between Multiple Vertices
The fourth button in the Explore Graph Menu is the "Find connections" option. Given a set of starting vertices, this feature finds a "connection community" which is defined as follows:
- For each pair of vertices in the vertex set, if there is a shortest path no longer than the maximum path length parameter, include that path in the result.
- The final result is the union of all of these shortest paths (one path per vertex pair).
This feature is equivalent to running the "Show One Shortest Path" option for each pair of vertices in the selected set.
Choose Vertices for Finding Connections
Click on a vertex to select it. Use shift-click to select more than one object. Each time you select another vertex, it will be added to the list in the Parameter Panel.
Set Conditions For Connection Finding
Since this query may have high computational cost if the graph is very large, a parameter is available to limit the path length.
You can also specify the valid vertex types and edge types which may be included in the connections.
After selecting the vertices and setting the search conditions, click on the "Find Connection Paths" buttonto start the search.
Graph Exploration Panel Options
After you have a subgraph displayed in the Graph Exploration Panel, you can use the buttons in the Explorer View Menu to customize the display. You can even make modifications to the graph database itself.
Click the Change Layout buttonto select one of the built-in layout styles for systematic arrangement of the vertices. The Change Layout popup menu shows a sample of each layout style, for a dummy graph.
Locate Vertex In Result
The Locate Vertex In Result featuresearches for and then zooms in on vertices which match the given value for ID and/or attribute. For example, if you type "Mary" in the Locate Vertices in Result popup window, and have both of the checkboxes selected, then this feature will look for any vertices where "Mary" is an exact match for either the ID or any of the attribute values. Those vertices will be selected (and all other objects will be unselected). The display will zoom in to focus on the selected objects.
The vertices with the matching ID or attributes will be selected:
Show Selected Vertices And Edges
Click the Show Selections buttonto hide all the vertices and edges which are not currently selected. However, if the two endpoints of an edge are selected, the edge will be selected as well. Also, if nothing is selected, nothing will be hidden.
Hide Vertices And Edges
Click the Hide buttonto hide the currently selected vertices and edges. If nothing is selected, all vertices and edges in the Graph Exploration Panel will be hidden.
Undo And Redo
The Explore Graph page records the whole history of the current session's changes to the visualization result set. Click the Undo and the Redo buttonsto go back or forward in the history.
Database changes (adding or deleting vertices/edges, editing attributes) cannot be undone with the Undo feature.
Also, Undo/Redo do not include layout and display changes (e.g., positioning of objects and display of attributes).
Add New Vertex
Click the Add New Vertex buttonto add a new vertex to the graph database. The Add New Vertex window will pop up. Choose a vertex type and then fill in values for the ID and the attributes. Click Add and the vertex will be inserted into the TigerGraph database. It will also be shown in the Graph Exploration Panel.
If you provide a vertex ID that is already used, GraphStudio will ask you whether you want to overwrite the existing vertex. If you say no, then it will not add or update anything.
Add New Edge
Click the Add New Edge buttonto add a new edge to the graph database. Next, click the source vertex of the edge in the Graph Exploration Panel, and then click the target vertex of the edge. Then the Add New Edge panel will pop up:
Now choose the edge type from the dropdown menu. Only types that match the two vertices you selected are shown. (It is possible that there are no eligible edge types). Fill in values for attributes and click Add. Your new edge will be inserted into the TigerGraph database. It will also be shown in the Graph Exploration Panel.
If you select an edge type that already exists between the two vertices, GraphStudio will ask if you want to overwrite the existing edge. If you say no, nothing will be added or updated. The current TigerGraph system does not support having multiple edges of the same type between two specific vertices.
To edit the attributes of one vertex or edge, select one object and then click the Edit Attributes button. The edit attributes panel will pop up.
When you finish editing, click the Update button to apply the change.
Delete Vertices And Edges
To delete vertices or edges, select the objects you want to delete, and click the Delete Selected Elements button.
"Delete" permanently removes data from the graph database. Deleted vertices and edges cannot be restored with Undo. To restore them, you must manually add them back.
If you delete a vertex, all of its outgoing and incoming edges will also be deleted.
When you find something interesting during exploration and want to save the result as a picture, you can click the Save Screenshot button. The exploration result will be saved as a PNG picture to your local file system.
To change graph exploration settings by clicking Settings button. Currently you can select what attributes to show for each vertex type and edge type, and set whether to show an object's detailed information in a popup tooltip when the cursor hovers over it. Click Apply and the new settings will take effect.
In the example below, the ID and gender for Person vertices are shown. The ID and the registered_capital attribute for Company vertices are shown.
On the Write Queries page, you can design and run custom queries with TigerGraph's powerful graph query language – GSQL.
The GSQL language reference can be found at the TigerGraph Documentation website: doc.tigergraph.com
The Write Query page is horizontally divided into two parts:
- Query Editing Panel
- Result, Log and Visualization Panel
Query Editing Panel
The Query Editing panel is divided into two subpanels: the left subpanel is used to select a query to edit, and the right, larger subpanel displays the selected query for editing. Here you can edit, save, delete, install and run the query. The query editor features syntax highlighting customized for the GSQL language. Also, the query editor performs real-time semantic checking.
Above the query editing pane is a toolbar, with the following buttons, from left to right:
- Expand/Collapse : Expand or collapse the Query Editing panel to or from full page mode. The icon changes depending on whether the panel is currently expanded or collapsed.
- Save : Save the current query draft.
- Install : Install the query into the database.
- Run : Run the installed query.
- Delete : Delete the selected query.
Add Or Edit Query
To create a new query, simply click on the "New GSQL Query" buttonat the bottom-right corner of the left subpanel, and type in the name of the new query in the popup window:
A query draft will be created with a template:
To edit an existing query, click on the query name in the list in the left subpanel.
Save Query Draft
Once you made some changes to the query code and want to save it as a query draft, click on the "save" buttonin the toolbar.
If you saved a query, the "install query" buttonwill be enabled. Click it to install the query.
The installation process may take about 1 minute.
A query has to be installed before you can run it.
To run the query, click on the "run" buttonin the toolbar. If the query has no parameters, it will run directly and the result will be shown in the Result panel.
If the query requires parameters, the Enter Query Parameters panel will appear. Enter your parameter values and then click the "Run Query" buttonat the bottom of the panel. If there are several parameters, you might need to scroll the panel to the bottom to find the Run Query button.
The query will be executed, and the results will be shown in the Result Panel.
Choose the query you want to delete and click on the "delete" button. The query will be deleted permanantly.
The Result panel shows the result of the last run query. Each query generates up to three types of result: visualized graph, JSON text, or log messages. On the left is a toolbar with buttons for changing the the panel size or for switching to a different type of result. The buttons, from top to bottom, are the following:
If the query 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. Please refer to the previous sections. The only difference is that each time you run a query, 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.
If there is no graph structure in the result, the result will be displayed in this panel as a JSON object.
You can learn about the JSON format in the GSQL Language documentation , and integrate it with your applications. In this fashion, the TigerGraph system can serve as a backend or embedded graph data service.
If a query ran successfully, the Query Log message will be "query ran successfully" or something similar. If there was anything wrong when executing your query, such as invalid parameters or runtime errors, an error message will be shown in the Query Log panel:
If you just want to focus on developing your query, or want to have more space to view your result, click the Expand buttonin either the Query Editing panel or the Result panel.
If you expand the Query Editing panel, it looks like this:
If you expand the Result panel, it looks like this:
When the panel is expanded, the Expand button becomes the Collapse button. Clicking it will return the display to the split panel view.
Export And Import Solution
These two features can be found in the GraphStudio Home page. You can return to the Home page by clicking "Home" the Menu Bar on the left or clicking the "GraphStudio" logo at the top.
Click on the "Export Current Solution" link to export the whole solution and download it as a tarball, including the schema, the loading jobs and the queries.
- The graph data and data files will not be exported.
- If a query has been modified since it was last installed, GraphStudio will export the modified draft instead of the version that have been installed in the TigerGraph engine.
Click on the "Import an Existing Solution" will upload a previously exported tarball of a solution.
Note: In order to optimize the time required for Import, the imported queries will not be installed but saved as drafts. You need to install them manually.
GraphStudio is not perfect, like any other software. The following issues are known and will be fixed in the future.
Graph Exploration Result Disappears
Sometimes when you double-click a vertex, the graph exploration result disappears. This is only a front-end rendering issue. The data is still there.
Workaround : click the change layout button , and choose any layout. Everything will be rendered.
Edge Response Area Is Too Big
When there are edges very close to one another, their click response areas may overlap, making it hard to select the edge you want. This happens after zoom-in / zoom-out or connecting to another screen sometimes.
Workaround : click a blank place in the working panel then zoom-in and zoom-out. The response area will back to normal.
Report Bugs To Us
If you find any bugs, please report them to firstname.lastname@example.org. We really appreciate it!
Want to know more about what TigerGraph can do for you? GraphStudio is just one part of our platform. Learn more about TigerGraph: GSQL Query Language at http://doc.tigergraph.com/ .