TigerGraph Docs : TigerGraph GraphStudio UI Guide

Version 1.0

Document updated

Copyright © 2015-2017 TigerGraph, Redwood City, California. All Rights Reserved.
For technical support on this topic, contact support@tigergraph.com with a subject line starting with "Graphstudio"


Chapters

Detailed Table of Contents

Introduction

The TigerGraph GraphStudio™ UI (User Interface) provides an intuitive, browser-based interface that helps users get started quickly with common 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 September 2017 , the GraphStudio UI is certified for the Google Chrome browser. 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.

GraphStudio On-Premise

For on-premise deployment, the system by default is listening to port 44240. Any machine connected to the server can access GraphStudio from a browser with the following address:

http://<your_tigergraph_server_ip_address>:<your_tigergraph_server_port>

If the GraphStudio UI does not show, the visualization service might be off. To verify, in a linux shell of the server, type

$ gadmin status vis

If it is off, turn it on:

$ gadmin start vis 

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.

Home Page

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: . Clicking the logo on the banner will take you back to the home page. The question mark on the top right corner links to this documentation. If you are using GraphStudio in the cloud, there is an exit button on the top right corner, which will log you out of your session and navigate back to the cloud portal login page.

Design Schema

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.

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 row 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 type sand 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 button to 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 button to 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 button to 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 button to 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.

Publish Schema

Once you are satisfied with the graph schema, click the publish schema button to publish the schema to the TigerGraph system. Publishing may take up to 2 minutes.

WARNING: Publish Schema is a critical operation. It will clear everything in the system first, which means your previous graph schema, data mapping procedure, and installed queries will be erased. Your loaded graph storage will also be cleared. If you want to save your previously developed work, export the solution first (see details at Import and Export solution). If you want to save the graph storage, refer to the TigerGraph system management documentation about how to back up graph data.

back to top


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

  1. Add data source(s)
  2. Map data source(s) to vertex/edge types
  3. Map data source columns to vertex/edge fields
  4. 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 button to 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.

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 separator is comma ",", the end of line character is "\n", 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, separator, or end of line. The file will immediately be re-parsed when you change a setting.


Figure: same source file with the Has Header option on.

Once you are satisfied with the file parsing configuration, click the add button to add the data source into left working panel. The data source will be shown as a file icon on the working panel:

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

Auto Mapping

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.

Delete Options

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 button to publish the data loading procedure to the TigerGraph system. It takes about 2 to 3 seconds for publishing each data source mapping.

Expand Panels

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.

back to top


Load Data

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.
  • Graph Statistics
    • Displays the numbers of vertices and edges in total, and the specific number of each type.
    • Shows the total number of vertices and edges loaded over time.

Start Loading

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.

For multiple data source loading, please keep the browser open until all loading jobs are done. Otherwise, the jobs which have not started will not be run.

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" button on 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" button on the toolbar.

Stop Loading

After loading starts, the "start loading" button will 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" button on 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.

back to top


Explore Graph

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.
  • 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 change to 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 for 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.

Expand

After setting the conditions for each expansion step, click on the "Expand" button to 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.

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

    Person Caral
  2. If the vertex you want is already displayed in the Graph Exploration Panel, a more convenient way is the following:
    1. Click on the input box.
    2. 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:

  1. One shortest path: search for and highlight a shortest path between the two vertices.
  2. All shortest paths: search for and highlight all shortest paths between the two vertices.
  3. 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.

Find Paths

After selecting the endpoint vertices and setting the search conditions, click on the "Find Paths" button to 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:

  1. 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.
  2. 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.

Find Connections

After selecting the vertices and setting the search conditions, click on the "Find Connection Paths" button to 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.

Change Layout

Click the Change Layout button to 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 feature searches 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 button to 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 button to 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 buttons to 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 button to 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 button to 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.


Edit Attributes

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.

Save Screenshot

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.

Change Settings

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.

back to top


Write Queries

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:

  1. Query Editing Panel
  2. 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" button at 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" button in the toolbar.

Install Query

If you saved a query, the "install query" button will be enabled. Click it to install the query.

The installation process may take about 1 minute.

Run Query

A query has to be installed before you can run it.

To run the query, click on the "run" button in 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" button at 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.

Delete Query

Choose the query you want to delete and click on the "delete" button . The query will be deleted permanantly.

Result Panel

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:

  • Expand/Collapse: Expand or collapse the Result panel.

  • Visual Result: Show the visual result of the last run query.

  • JSON Result: Show the raw text result in JSON format of the last run query.

  • Query Log: Show the log for the last run query.

Visual Result

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.

JSON Result

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.

Query Log

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:

Expand Panels

If you just want to focus on developing your query, or want to have more space to view your result, click the Expand button in 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:

Whent the panel is expanded, the Expand button becomes the Collapse button . Clicking it will return the display to the split panel view.

back to top


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.

Export

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.

Note

  1. The graph data and data files will not be exported.
  2. 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.

Import

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.

Known Issues

GraphStudio is not perfect, like any other software. The following issues are known and will be fixed in the future.

Sometimes the data mapping from data source to the edge is not rendered, like this screenshot:

Workaround : drag the cursor around the panel, especially where the links should be. The links will appear.

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 rerun the layout. Everything will be back.

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 sometimes.
Workaround : click a blank place in the working panel. The edge response areas will not overlap anymore.

Report Bugs To Us

If you find any bugs, please report them to support@tigergraph.com. We really appreciate it!

What's Next

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