Design Schema

Design Schema

Beginning with Version 3.0, GraphStudio can support modifying multiple graphs within one TigerGraph instance. Read more about 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 of the subsequent steps depend on the graph schema. If you are not on the Design Schema page yet, click "Design Schema" on the left side menu bar.

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

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

  2. Only the superuser, globaldesigner, and designer roles can modify a local graph schema.

When there is no graph schema in the system, this page will show some hints:

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

  2. Only the superuser, globaldesigner, and designer roles modify a local graph schema.

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 in; two-finger moving down zooms out. Similarly, if your mouse has a scroll wheel, spinning forward zooms in, and spinning backward zooms out.

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.

Global View vs. Graph View

For superuser and globaldesigner, they 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. There will be a warning message in the working panel saying user is under global view.

  1. If under global view, other pages except Home and Design Schema will be disabled.

  2. Users other than superuser and globaldesigner cannot access global view.

Users can modify a graph schema under graph view. In a graph, there is one more in the toolbar area - "View global vertex and edge types". And for global vertex and edge types used in a graph, a little global icon is attached to them.

Add A Vertex Type

In this window you specify a vertex type name, primary id name. 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:

You can also upload your own icons by clicking the Upload Icon button, choosing a PNG image, giving a name and click Upload:

Then you can use your uploaded icons:

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

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.

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:

Then click the target vertex type. The add edge type panel will be in the right:

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.

You can also click the green plus sign at the right of the source and target vertex types section to add more source and target vertex types of the edge type.

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

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

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

Delete Vertex Or Edge Type

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

Redo And Undo

View Global Vertex And Edge Types

Only 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

Note that Publish Schema applies to both creating a new schema as well as modifying an existing schema. If you have already loaded data into or created queries for an existing graph, please note that GraphStudio's Publish Schema is only able to retain your existing data in some circumstances. Read the following section carefully.

If you are editing an existing graph schema, GraphStudio will analyze your changes. If the change to a vertex or edge type is to remove some attributes and / or to add some new attributes, or add or remove index to some attributes, GraphStudio will employ a GSQL SCHEMA_CHANGE job in order to retain the graph data you already loaded.

All other types of changes, including renaming the vertex or edge type, changing attribute name or data type, changing edge direction, adding or removing reverse edge will result in removing the old vertex or edge type and then adding the new one with your desired configurations. In that case, the loaded data to that vertex or edge type will be erased. Please think twice before you do this type of changes.

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:

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:

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

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

Last updated