Defining a Graph Schema

Before data can be loaded into the graph store, the user must define a graph schema.

A graph schema is a "dictionary" that defines the types of entities, vertices and edges, in the graph and how those types of entities are related to one another. Each vertex or edge type has a name and a set of attributes (properties) associated with it. For example, a Book vertex could have title, author, publication year, genre, and language attributes.

In the figure below, circles represent vertex types, and lines represent edge types. The labeling text shows the name of each type. This example has four types of vertices: User, Occupation, Book, and Genre. Also, the example has 3 types of edges: user_occupation, user_book_rating, and book_genre. Note that this diagram does not say anything about how many users or books are in the graph database. It also does not indicate the cardinality of the relationship. For example, it does not specify whether a User may connect to multiple occupations.

Figure 1. A schema for a User-Book-Rating graph

An edge connects two vertices: a source vertex and a target vertex . An edge type can be either directed or undirected. A directed edge has a clear semantic direction, from the source vertex to the target vertex. For example, if there is an edge type that represents a plane flight segment, each segment needs to distinguish which airport is the origin (source vertex) and which airport is the destination (target vertex). In the example schema below, all edges are undirected.

A useful test to decide whether an edge should be directed or undirected is the following: "An edge type is directed if knowing there is a relationship from A to B does not tell me whether there is a relationship from B to A." Having nonstop service from Chicago to Shanghai does not automatically imply there is nonstop service from Shanghai to Chicago.

An expanded schema is shown below, containing all the original vertex and edge types plus three additional edge types: friend_of, sequel_of, and user_book_read. Note that friend_of joins a User to a User. The friendship is assumed to be bidirectional, so the edge type is undirected. Sequel_of joins a Book to a Book but it is directed, as evidenced by the arrowhead. The Two Towers is the sequel of The Fellowship of the Ring , but the reverse is not true. User_book_read is added to illustrate that there may be more than one edge type between a pair of vertex types.

Figure 2. Expanded-User-Book-Rating schema with additional edges

The TigerGraph system user designs a graph schema to fit the source data and the user’s needs and interests. The TigerGraph system user should consider what type of relationships are of interest and what type of analysis is needed. The TigerGraph system lets the user modify an existing schema, so the user is not locked into the initial design decision.

In the first schema diagram above, there are seven entities: four vertex types and three edge types. You may wonder why it was decided to make Occupation a separate vertex type instead of an attribute of User. Likewise, why is Genre a vertex type instead of an attribute of Book? These are examples of design choices. Occupation and Genre were separated out as vertex types because in graph analysis, if an attribute will be used as a query variable, it is often easier to work with as a vertex type.

Once the graph designer has chosen a graph schema, the schema is ready to be formalized into a series of GSQL statements.

Graph Creation and Modification Privileges

You need the WRITE_SCHEMA privilege in the scope you are operating on to run commands that alter the graph schema.

To learn more about permission and privileges, see Access Control Model in TigerGraph.

`CREATE VERTEX`

The CREATE VERTEX statement defines a new global vertex type with a name and an attribute list.

Data loaded to a global vertex type in one graph will be shared across all graphs that use that vertex type. See Global vs. local schema changes for instructions on creating local vertices.

At a high level of abstraction, the format is

CREATE VERTEX Vertex_Type_Name (id_and_attribute_list) [ vertex_options ]

More specifically, the syntax is as follows, assuming that the vertex ID is listed first:

CREATE VERTEX Syntax

CREATE VERTEX Vertex_Type_Name "(" primary_id_name_type
    ["," attribute_name type [DEFAULT default_value] ]* ")"
    [WITH [STATS="none"|"outdegree_by_edgetype"][primary_id_as_attribute="true"]]

Required privilege

WRITE_SCHEMA

Keys and Attributes

Beginning with v2.3, there are two syntaxes for specifying the primary id/key:

Legacy PRIMARY_ID syntax: The legacy syntax remains valid, but there are additional options and additional flexibility:

PRIMARY_ID and WITH primary_id_as attribute
PRIMARY KEY syntax. This syntax is modeled after SQL.

`PRIMARY_ID` and `WITH primary_id_as_attribute`

The primary_id is a required field whose purpose is to uniquely identify each vertex instance. GSQL creates a hash index on the primary id with O(1) time complexity. Its data type may be STRING, INT, or UINT. The syntax for the primary_id_name_type term is as follows:

primary_id_name_type := PRIMARY_ID id_name id_type

By default, the primary_id field is not one of the attribute fields. The purpose of this distinction is to minimize storage space for vertices. The functional consequence of this difference is that a query cannot read the primary_id or use it as part of an expression.

Example:

CREATE VERTEX Movie (PRIMARY_ID id UINT, name STRING, year UINT)
    WITH primary_id_as_attribute="true"

`PRIMARY KEY`

Instead of the legacy PRIMARY_ID syntax, starting with v2.3, GSQL now offers another option for specifying the primary key. Append the keyword phrase PRIMARY KEY to any one of the attributes in the attribute list to make the attribute the primary key. It is conventional for the primary key to be the first attribute. Each vertex instance must have a unique value for the primary key attribute. GSQL creates a hash index on the PRIMARY KEY attribute with O(1) time complexity. The primary key data type should STRING, INT, or UINT.

primary_id_name_type := id_name_id_type PRIMARY KEY

Example:

CREATE VERTEX Movie (id UINT PRIMARY KEY, name STRING, year UINT)

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

Composite keys

GSQL supports composite keys - grouping multiple attributes to create a primary key for a specific vertex. To specify a composite key, use the keyword PRIMARY KEY followed by the attributes that form the composite key enclosed in parentheses in the CREATE VERTEX command.

composite_id_name_type := PRIMARY KEY "(" attribute_name ("," attribute_name)* ")"

Example:

CREATE VERTEX Movie (id UINT, title STRING, year UINT, PRIMARY KEY (title,year,id))

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

Vertex Attribute List

The attribute list, enclosed in parentheses, is a list of one or more id definitions and attribute descriptions separated by commas:

primary_id_name_type
[, attribute_name type [DEFAULT default_value ] ]*

The available attribute types, including user-defined types, are listed in the section Attribute Data Types.

Every attribute data type has a built-in default value (e.g., the default value for INT type is 0). The DEFAULT default_value option overrides the built-in value.
Any number of additional attributes may be listed after the primary_id attribute. Each attribute has a name, type, and optional default value (for primitive-type, DATETIME, or STRING COMPRESS attributes only)

Example:

Create vertex types for the graph schema of Figure 1.

Vertex definitions for User-Book-Rating graph

CREATE VERTEX User (PRIMARY_ID user_id UINT, name STRING, age UINT, gender STRING, postalCode STRING)
CREATE VERTEX Occupation (PRIMARY_ID occ_id UINT, occ_name STRING)
    WITH STATS="outdegree_by_edgetype"
CREATE VERTEX Book (PRIMARY_ID bookcode UINT, title STRING, pub_year UINT)
    WITH STATS="none"
CREATE VERTEX Genre (PRIMARY_ID genre_id STRING, genre_name STRING)

Unlike the tables in a relational database, vertex types do not need to have a foreign key attribute for one vertex type to have a relationship to another vertex type. Such relationships are handled by edge types.

`WITH STATS`

By default, when the loader stores a vertex and its attributes in the graph store, it also stores some statistics about the vertex’s outdegree — how many connections it has to other vertices. The optional WITH STATS clause lets the user control how much information is recorded. Recording the information in the graph store will speed up queries which need degree information, but it increases the memory usage. There are two* options.

If outdegree_by_edgetype is chosen, then each vertex records a list of degree count values, one value for each type of edge in the schema.
If "none" is chosen, then no degree statistics are recorded with each vertex. If the WITH STATS clause is not used, the loader acts as if outdegree_by_edgetype were selected.

The graph below has two types of edges between persons: phone_call and text. For Bobby, the outdegree_by_edgetype option records how many phone calls Bobby made (1) and how many text messages Bobby sent (2). This information can be retrieved using the built-in vertex function outdegree(). To get the outdegree of a specific edge type, provide the edgetype name as a string parameter. To get the total outdegree, omit the parameter.

WITH STATS option (case insensitive)	Bobby.outdegree()	Bobby.outdegree("text")	Bobby.outdegree("phone_call")
"none"	not available	not available	not available
"outdegree_by_edgetype" (default)	3	2	1

WITH STATS option (case insensitive)

Bobby.outdegree()

Bobby.outdegree("text")

Bobby.outdegree("phone_call")

"none"

not available

"outdegree_by_edgetype" (default)

`CREATE EDGE`

CREATE EDGE defines a new global edge type. Data loaded to a global edge type in one graph will be shared across all graphs that use that edge type. See Global vs. local schema changes for instructions on creating local edges.

There are two forms of the CREATE EDGE statement, one for directed edges and one for undirected edges. Each edge type must specify that it connects FROM one vertex type TO another vertex type. Additional pairs of FROM and TO vertex types may be added. Then additional attributes may be added. Each attribute follows the same requirements as described in the Attribute List subsection for the CREATE VERTEX section.

CREATE UNDIRECTED EDGE
CREATE DIRECTED EDGE

CREATE UNDIRECTED EDGE Edge_Type_Name "("
        FROM Vertex_Type_Name "," TO Vertex_Type_Name
   ["|" FROM Vertex_Type_Name, TO Vertex_Type_Name]*
   ["," attribute_name type [DEFAULT default_value]]* ")"

CREATE DIRECTED EDGE Edge_Type_Name "("
        FROM Vertex_Type_Name "," TO Vertex_Type_Name
   ["|" FROM Vertex_Type_Name, TO Vertex_Type_Name]*
   ["," attribute_name type [DEFAULT default_value]]* ")"
   [WITH REVERSE_EDGE="Rev_Name"]

A single edge type can be defined between multiple pairs of vertex types, e.g.

CREATE DIRECTED EDGE Member_Of (FROM Person, TO Org | FROM Org, TO Org,
                               joined DATETIME)

Note that edges do not have a PRIMARY_ID field. Instead, each edge is uniquely identified by a FROM vertex, a TO vertex, and optionally other attributes. The edge type may also be a distinguishing characteristic. For example, as shown in Figure 2 above, there are two types of edges between User and Book. Therefore, both types would have attribute lists which begin (FROM User, To Book,...).

Creating an Edge from or to Any Vertex Type

An edge type can be defined which connects FROM and/or TO any of the currently defined types of vertices. Use the wildcard symbol * to indicate "any vertex type". For example, the Any_Edge type below can connect from any vertex to any other vertex:

Wildcard edge type

CREATE DIRECTED EDGE Any_Edge (FROM *, TO *, label STRING)

If new vertex types are added after a wildcard edge type is defined, the new vertex types are NOT included in the wildcard. That is, * is an alias for the vertex types that existed at the point in time that the CREATE EDGE statement is executed.

`WITH REVERSE_EDGE`

If a CREATE DIRECTED EDGE statement includes the WITH REVERSE_EDGE=" rev_name " optional clause, then an additional directed edge type called rev_name is automatically created, with the FROM and TO vertices swapped. Moreover, whenever a new edge is created, a reverse edge is also created. The reverse edge will have the same attributes, and whenever the principal edge is updated, the corresponding reverse edge is also updated.

In a TigerGraph system, reverse edges provide the most efficient way to perform graph queries and searches that need to look "backwards". For example, referring to the schema of Figure 2, the query "What is the sequel of Book X, if it has one?" is a forward search, using Sequel_Of edges. However, the query "Is Book X a sequel? If so, what Book came before X?" requires examining reverse edges.

Example:

Create undirected edges for the three edge types in Figure 1.

Edge definitions for User-Book-Rating graph

CREATE UNDIRECTED EDGE User_Occupation (FROM User, TO Occupation)
CREATE UNDIRECTED EDGE Book_Genre (FROM Book, TO Genre)
CREATE UNDIRECTED EDGE User_Book_Rating (FROM User, TO Book, rating UINT, date_time UINT)

The User_Occupation and Book_Genre edges have no attributes. A User_Book_Rating edge symbolizes that a user has assigned a rating to a book. Therefore it includes an additional attribute rating. In this case the rating attribute is defined to be an integer, but it could just as easily have been set to be a float attribute.

Example:

Create the additional edges depicted in Figure 2.

Additional Edge definitions for Expanded-User-Book-Rating graph

CREATE UNDIRECTED EDGE Friend_Of (FROM User, TO User, on_date UINT)
CREATE UNDIRECTED EDGE User_Book_Read (FROM User, To Book, on_date UINT)
CREATE DIRECTED EDGE Sequel_Of (FROM Book, TO Book) WITH REVERSE_EDGE="Preceded_By"

Every time the GSQL loader creates a Sequel_Of edge, it will also automatically create a Preceded_By edge, pointing in the opposite direction.

`TYPEDEF`

User-defined tuple types defined in a query cannot be used outside their queries or across queries. To use a user-defined tuple or an accumulator that uses a user-defined tuple across queries (such as for the return type of a subquery ), the tuple and the accumulator type must be defined on the catalog level as part of the schema. User-defined types at the catalog level can only be used for query return value types, and cannot be used as an attribute data type.

TYPEDEF statements can be used outside a query to define tuple types, GroupBy accumulator types, and heap accumulator types. Once defined, all graphs in the database have access to these user-defined types, and subqueries can be defined to return the user-defined types.

Example:

The example below defines a tuple type My_Tuple and a heap accumulator type My_Heap, so that the subquery Sub_Query_1 can return a value of My_Heap type to its outer query Query_1.

// Define the heap accumulator at the catalog level
TYPEDEF TUPLE<name string, friends int> My_Tuple
TYPEDEF HeapAccum<My_Tuple>(3, friends DESC) My_Heap

CREATE QUERY subquery1() FOR GRAPH Social_Net RETURNS (My_Heap){
	My_Heap @@heap;
	SumAccum<int> @friends;
	Start = {Person.*};
	Start = SELECT s from Start:s-(Friend:e)-:t
	        ACCUM s.@friends += 1
	        POST-ACCUM @@heap += My_Tuple(s.id,s.@friends);
	RETURN @@heap;
}

CREATE QUERY Query_1() FOR GRAPH Social_Net {
	PRINT Sub_Query_1();
}

Special Options

Sharing a Compression Dictionary

The STRING COMPRESS data type achieves compression by mapping each unique attribute value to a small integer. The mapping table ("this string" = "this integer") is called the dictionary. If two such attributes have the same or similar sets of possible values, then it is desirable to have them share one dictionary because it uses less storage space.

When a STRING COMPRESS attribute is declared in a vertex or edge, the user can optionally provide a name for the dictionary. Any attributes which share the same dictionary name will share the same dictionary. For example, v1.attr1, v1.attr2, and e.attr1 below share the same dictionary named "e1".

Shared STRING COMPRESS dictionaries

CREATE VERTEX V1 (PRIMARY_ID main_id STRING, att1 STRING COMPRESS e1, att2 STRING COMPRESS e1)
CREATE UNDIRECTED EDGE E (FROM V1, TO V2, att1 STRING COMPRESS e1)

`ALTER INDEX`

User-defined indexes (or secondary indexes, as they are called commonly called in the database industry) are a valuable feature that enhances the performance of a database system. Indexes allow users to perform fast lookups on non-key columns or attributes without a full-fledged scan.

The TigerGraph database allows users to define on vertex attributes. The user has the flexibility to create indexes in an empty graph initially or to add indexes later when the database is running. If the index is added on an existing vertex, index data is built in the background.

Indexes can be created on vertices on a single attribute of the following data types only: STRING, UINT, INT, DATETIME, and STRING COMPRESS. Indexes will be used to optimize queries with all predicate types. However, if a predicate uses an in-built function, then index will not be used to optimize the query. Also, built-in queries are not optimized using indexes.

Indexes are very important for data retrieval performance. However, adding indexes will affect write performance. For this reason, users should use caution when adding indexes. Users should review the querying patterns to decide where indexes can help.

Users can create and drop indexes using ALTER VERTEX command as shown below.

Syntax:

CREATE GLOBAL SCHEMA_CHANGE job <job-name>
{
  ALTER VERTEX Object_Type_Name ADD INDEX Index_Type_Name ON (Attribute_Name);
  ALTER VERTEX Vertex_Type_Name DROP INDEX Index_Type_Name;
};

Example:

ALTER VERTEX User ADD INDEX user_country_index ON (country);

`CREATE GRAPH`

CREATE GRAPH defines a graph schema, which contains the given vertex types and edge types, and prepares the graph store to accept data. The vertex types and edge types may be listed in any order. Executing CREATE GRAPH will set the new graph to be the working graph.

Required privilege

WRITE_SCHEMA

Syntax for CREATE GRAPH

CREATE GRAPH Graph_Name (Vertex_Or_Edge_Type, Vertex_Or_Edge_Type...) (1)(2)
                [WITH ADMIN username]

1	Replace graph_name with the name you want to name the graph with
2	Replace vertex_or_edge_type with the vertex and edge types you want to include in the graph

The optional WITH ADMIN clause sets the named user to be the admin for the new graph.

Instead of providing a list of specific vertex types and edge types, you can define a graph type that includes all the available vertex types and edge types by replacing the list of vertex and edge types with *.

You can also create a graph with no vertex or edge types. A schema change can be used later to add vertex and edge types.

Examples of CREATE GRAPH with all vertex & edge types and with an empty domain.

CREATE GRAPH Everything_Graph (*)
CREATE GRAPH Empty_Graph ()

Examples

Create graph Book_rating for the edge and vertex types defined for the below:

Figure 3. A schema for a User-Book-Rating graph

Full definition for the Expanded User-Book-Rating graph

CREATE VERTEX User (PRIMARY_ID user_id UINT, name STRING, age UINT, gender STRING, postalCode STRING)
CREATE VERTEX Occupation (PRIMARY_ID occ_id UINT, occ_name STRING) WITH STATS="outdegree_by_edgetype"
CREATE VERTEX Book (PRIMARY_ID bookcode UINT, title STRING, pub_year UINT) WITH STATS="none"
CREATE VERTEX Genre (PRIMARY_ID genre_id STRING, genre_name STRING)
CREATE UNDIRECTED EDGE User_Occupation (FROM User, TO Occupation)
CREATE UNDIRECTED EDGE Book_Genre (FROM Book, TO Genre)
CREATE UNDIRECTED EDGE User_Book_Rating (FROM User, TO Book, rating UINT, date_time UINT)
CREATE UNDIRECTED EDGE Friend_Of (FROM User, TO User, on_date UINT)
CREATE UNDIRECTED EDGE User_Book_Read (FROM User, To Book, on_date UINT)
CREATE DIRECTED EDGE Sequel_Of (FROM Book, TO Book) WITH REVERSE_EDGE="Preceded_By"
CREATE GRAPH Book_Rating (*) (1)

1	Having created all the necessary vertex and edge types, use the `*` sign to include all vertex and edge types in the graph.

`CREATE GRAPH … AS` (Beta)

CREATE GRAPH … AS creates a tag-based graph of an existing graph. Tag-based graphs include vertices with specific tags from their base graphs, and have their own access control. Users can be granted roles on a tag-based graph and their roles will give them privileges that only apply to the resources in the tag-based graph.

This command can only be run on the base graph and requires the user to have the schema-editing privilege on the base graph.

Synopsis

<create_tag_graph> :=
    CREATE GRAPH <tag_graph_name> AS <base_graph_name>
    ( "(" <tagged_element_name> ("," <tagged_element_name>)* ")" | ":" <tag_expr> )

<tagged_element_name> := <tagged_vertex_name> | <edge_name>

<tagged_vertex_name> := <vertex_name> [":" <tag_expr>]

<tag_expr> := <tag> ("&" <tag_expr>)*

The syntax for creating tag-based graphs is the same as creating a regular graph except that a base graph must be specified with the AS clause after the CREATE GRAPH command, and the definition of the graph must include at least one tagged vertex type. Edges are not tagged in a tag-based graph, but edges with either a source or a target outside of the tag-based graph are not visible to users of the tag-based graph.

Include vertices with multiple tags

Use the ampersand operator (&) to express vertices with multiple tags:

CREATE GRAPH Mixed_Net AS Social_Net(person:public&vip, post:public&tech&dummy,
friend, posted, liked)

Include everything in the base graph with specified tags

Use a colon to specify tags directly after the graph name to include everything in the base graph that has the specified tags:

CREATE GRAPH Public_Net_2 AS Social_Net:Public

`USE GRAPH`

New requirement for MultiGraph support. Applies even if only one graph exists.

Before a user can use a graph, the user must be granted a role on that graph by an admin user of that graph or by a superuser. (Superusers are automatically granted the admin role on every graph). Second, for each GSQL session, the user must set a working graph. The USE GRAPH command sets or changes the user’s working graph, for the current session.

For more about roles and privileges, see the document Managing User Privileges and Authentication.

USE GRAPH syntax

USE GRAPH gname

Instead of the USE GRAPH command, gsql can be invoked with the -g <graph_name> option.

`DROP GRAPH`

Syntax

DROP GRAPH Graph_Name

Required privilege

WRITE_SCHEMA

The DROP GRAPH command deletes the logical definition of the named graph. It will also delete all local vertex or edge types. Local vertex and edge types are created by an ADD VERTEX/EDGE statement within a SCHEMA_CHANGE JOB and so belong only to that graph. Any shared types are unaffected. To delete only selected vertex types or edge types, see DROP VERTEX | EDGE in the Section "Modifying a Graph Schema".

`DROP ALL`

Required privilege

Drop_ALL

The DROP ALL command clears the graph store (i.e. deletes all data) and removes all definitions from the catalog: vertex types, edge types, graph types, jobs, and queries.

Unlike the gsql --reset command, DROP ALL does not erase user and role information.

DROP ALL, along with all DROP operations, is non-reversible.

`SHOW` - View Parts of the Catalog

The SHOW command can be used to show certain aspects of the graph, instead of manually filtering through the entire graph schema when using the ls command. You can either type the exact identifier or use regular expressions / Linux globbing to search.

SHOW <VERTEX> | <EDGE> | <JOB> | <QUERY> | <GRAPH> [ <name> | <glob> | -r <regex> ]

SHOW GRAPH lists vertices and edges without giving their properties, and is also a way to check the JSON API and syntax versions of the graph, as well as any loading jobs. SHOW VERTEX and SHOW EDGE list the properties of the desired vertex or edge respectively.

This feature supports the ? and * from linux globbing operations, and also regular expression matching. Usage of the feature is limited to the scope of the graph the user is currently in - if you are using a global graph, you will not be able to see vertices that are not included in your current graph.

Regular expression searching will not work with escaping characters.

To use regular expressions, you will need to use the -r flag after the part of the schema you wish to show. If you wish to dive deeper into regular expressions, visit "Java Patterns". The following are a few examples of what is supported by the SHOW command.

Linux Globbing examples
SHOW VERTEX us*            //shows all vertices that start with the letters "Us"
SHOW VERTEX co?*y          //shows the vertices that starts with co and ends with y
SHOW VERTEX ?????          //shows all vertices that are 5 letters long

Regular Expression Examples
SHOW VERTEX -r "skil{2}"    //match the pattern "skill"
SHOW EDGE -r "test[1][13579]*"    //match pattern that only contains odd numbers after "test"
SHOW JOB -r "[a-zA-Z]*"     //match all jobs that contain only letters

Defining a Graph Schema

CREATE VERTEX

Required privilege

Keys and Attributes

PRIMARY_ID and WITH primary_id_as_attribute

PRIMARY KEY

Composite keys

Vertex Attribute List

WITH STATS

CREATE EDGE

Creating an Edge from or to Any Vertex Type

WITH REVERSE_EDGE

TYPEDEF

Example:

Special Options

Sharing a Compression Dictionary

ALTER INDEX

CREATE GRAPH

Required privilege

Examples

CREATE GRAPH …​ AS (Beta)

Include vertices with multiple tags

Include everything in the base graph with specified tags

USE GRAPH

DROP GRAPH

Syntax

Required privilege

DROP ALL

Required privilege

SHOW - View Parts of the Catalog

`CREATE VERTEX`

`PRIMARY_ID` and `WITH primary_id_as_attribute`

`PRIMARY KEY`

`WITH STATS`

`CREATE EDGE`

`WITH REVERSE_EDGE`

`TYPEDEF`

`ALTER INDEX`

`CREATE GRAPH`

`CREATE GRAPH … AS` (Beta)

`USE GRAPH`

`DROP GRAPH`

`DROP ALL`

`SHOW` - View Parts of the Catalog