Design Schema

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.

Current Limitations

1. Only users with superuser privilege can use Design Schema to modify a graph schema.

2. 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. Similarly, 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. 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.

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

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

Publish Schema

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

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.

Developer Edition: SCHEMA_CHANGE is not supported. Publish Schema will always "DROP ALL" (erase all data) before creating your new schema.

Enterprise Edition: 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, 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 that kind 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-right 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:

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: