Design Schema

GraphStudio supports modifying multiple graphs within one TigerGraph instance. Read more about this architecture, called MultiGraph, at MultiGraph - An Overview.

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 the subsequent steps depend on the graph schema.

Only certain roles have the privilege to modify a graph schema.

Only the superuser and globaldesigner roles can modify the global graph schema, including creating local graphs.
Only the superuser, globaldesigner, and designer roles can modify a local graph schema.

The main page visualizes the graph schema, showing user interface hints if no graph schema exists.

Each circle represents a vertex type, and each link represents an edge type. You can drag the circles to change their positions and zoom in or out by scrolling.

A graph schema is a description or plan for a graph rather than the graph itself. For example, a simple graph of cities and highways might only have one vertex type (City) and one edge type (Highway). Data for thousands of cities and tens of thousands of individual highway connections could then be loaded into that graph.

After the Design Schema step, the next two steps, Map Data To Graph and Load Data, are for loading data into the graph.

Global View vs. Graph View

Global View allows you to see all global vertex and edge types. Global types are available for use in any graph. In contrast, Graph View only allows you to see vertex and edge types that are local to one specific graph.

The superuser and globaldesigner roles can modify global vertex and edge types under Global View. Under global view, the toolbar area only contains "Publish schema", "Add a vertex type", "Add an edge type", "Edit", "Delete", "Undo" and "Redo" buttons.

If under global view, other pages except Home and Design Schema will be disabled.
Users other than superuser and globaldesigner cannot access global view.

Users can modify a graph schema under graph view (viewing a specific graph rather than a global view of all vertices and edges). In graph view, there is one more icon in the toolbar area - "View global vertex and edge types". This adds a small globe icon next to any global vertex and edge types used in a graph.

It is important to stay aware of which data types are global and which are local, because data loaded to a global type is accessible from any graph using that type.

Add a vertex type

Click the add vertex type button to add a vertex type. The working space will enter Add Vertex mode and open the add vertex type panel to the right:

In this window you specify a vertex type name and primary id name.

In the Style section, you can change the color of your vertex icon from the default chosen by GraphStudio. You can also replace the default circle using a file that you upload or choose from our icon library.

Vertex attributes

If you want to have a vertex or edge type’s primary ID as an attribute, check the "AS ATTRIBUTE" box. This will allow you to use the vertex or edge’s primary ID like any other attribute of the vertex or edge type in features such as filter, attachment and order.

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

For some types of attributes (INT, UINT, STRING, STRING COMPRESS, DATETIME), you can add an index, which will improve query performance when accessing these attributes.

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 checkmark button at the top to add the vertex type. A new vertex appears in the working panel, where you can arrange it visually however you prefer.

PRIMARY KEY and composite keys are not supported in GraphStudio. If you define a vertex type using the PRIMARY KEY syntax or with composite key, you will not be able to operate on the graph with that vertex type or the global schema in GraphStudio.

Add an edge type

Click the add edge type button to enter Add Edge mode and add an edge type.

Each edge type has one or many source vertex types and target vertex types. First, click the source vertex type. A hint will appear on the vertex type circle:

Click the target vertex type. The add edge type panel will appear to the right:

The edge type name cannot be left blank.

By default, the edge type is undirected. To make the edge type directed, mark the Directed checkbox, which will bring up 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.

The source and target vertex types are selected based on the vertices you clicked, but you can change that by choosing another vertex type in the dropdown list. Click the green plus sign at the right of the source and target vertex types section to add more source and target vertex types.

Unselect the reverse edge checkbox ONLY IF your machine memory is very limited, because if there is no reverse edge, queries will not be able to traverse backwards along this directed edge type from the target vertex to the source vertex.

Once you are satisfied with the edge type settings, click the checkmark button at the top to add the edge type, which will instantly appear in the working panel.

Edge attributes

Add an attribute to your edge in the Attributes panel. Edge attributes work just like vertex attributes.

The Discriminator checkbox allows you to enable multiple edges with the same type to exist between the same vertex pair, as long as the discriminator attributes are unique.

You cannot change an edge type to or from a Discriminator or non-Discriminator type if it is used in another graph.

Non-Discriminator attributes can be added and dropped at will. However, modifying Discriminator attributes performs the same actions in the backend as dropping and recreating an edge. Therefore, data loaded to edges with Discriminator attributes will be lost upon attribute modification.

Attribute values must be unique if multiple edges of the same type exist between the same vertex pair. TigerGraph does not support multiple identical edges between the same vertex pair because there would be no way to tell them apart.

Edit Vertex Or Edge Type

You can edit the vertex types or edge types at any time after you add them. Click one vertex type circle or one edge link, then click the edit button or double-click on the selected vertex or edge. working space will enter Edit mode, allowing you to use the Edit Attributes panel to make the same kinds of changes as in the Add panel.

After making your changes, click the checkmark button at the top to confirm your changes and update the graph.

In graph mode, you can only edit the style of a global vertex or edge type:

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 select multiple items.

Note that user cannot delete a global vertex or edge type using the delete button in a graph.

Undo and redo

You can undo and redo your changes with the undo and redo buttons: . history since the time you entered the Design Schema page is recorded.

View global vertex and edge types

Click the view global vertex and edge types button to assign global vertex and edge types to a graph, or drop them from a graph. The working space will enter View Global Vertex and Edge Types mode. The add vertex type panel will appear to the right:

Only a superuser or globaldesigner can modify global types in a graph. The view global vertex and edge types button will be disabled for other users.

Publish schema

Once you are satisfied with the graph schema, click the publish schema button to publish the schema to the TigerGraph system. If you are publishing a brand new schema, a progress bar will appear:

Change or edit an existing schema

If a schema already exists, Publish Schema will modify the existing schema.

If you have already loaded data into or created queries for an existing graph, Publish Schema will only retain your existing data in some circumstances.

If the change to a vertex or edge type is to add or remove attributes or attribute indexes, GraphStudio will employ a GSQL SCHEMA_CHANGE job and retain any graph data you already loaded.

For all other types of changes, including:

renaming a vertex or edge type
changing attribute name or data type
changing edge direction
adding or removing a reverse edge

GraphStudio will remove the old vertex or edge type and add the new one with your desired configurations. In that case, the loaded data to that vertex or edge type will be erased.

If a vertex type will be removed in order to change the schema, all edge types connected to that vertex type will also be removed.

When you are editing a graph schema, a warning message in the top-left side of the working panel will show which old vertex and edge types will be removed. Make sure to check the message periodically to make sure it is as you expect:

Finally, when you click publish schema button , a pop up window will summarize your changes to the schema. The vertex and edge types that will be removed are highlighted. Make sure you confirm the changes before continue:

Click continue button, and GraphStudio will start changing your schema:

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:
1. Rename vertex types and edge types
2. Remove mappings to deleted vertex types and edge types.
3. Remove mappings to deleted or modified attributes.
4. New vertex types, edge types and new attributes won’t be mapped.
5. 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 have published some data mapping through GraphStudio, then after schema is changed successfully, a pop up window will guide you to go to the Map Data To Graph page to confirm and publish the migrated data mapping: