Modifying a Graph Schema
After a graph schema has been created , it can be modified. Data already stored in the graph and which is not logically part of the change will be retained. For example, if you had 100 Book vertices and then added an attribute to the Book schema, you would still have 100 Books, with default values for the new attribute. If you dropped a Book attribute, you still would have all your books, but one attribute would be gone.
To safely update the graph schema, the user should follow this procedure:
-
Create a schema change job, which defines a sequence of
ADD
,ALTER
and/orDROP
statements. -
Run the schema change job (using
RUN SCHEMA_CHANGE JOB <job name>
), which will do the following:-
Attempt the schema change.
-
If the change is successful, invalidate any loading job or query definitions which are incompatible with the new schema.
-
if the change is unsuccessful, report the failure and return to the state before the attempt.
-
A schema change will invalidate any loading jobs or query jobs which relate to an altered part of the schema. Specifically:
Invalid loading jobs are dropped, and invalid queries are uninstalled. After the schema update, the user will need to create and install new load and query jobs based on the new schema. |
Load or query operations which begin before the schema change will be completed based on the pre-change schema. Load or query operations which begin after the schema change, and which have not been invalidated, will be completed based on the post-change schema. |
Schema changes that are performed during times with high query or data loading volume may have a chance of failure. It is considered good practice to perform schema changes during times of low graph activity.
Global vs. local schema changes
Users must have the global scope to interact with global schema change jobs (create, delete, run). See |
USE GLOBAL
The USE GLOBAL
command changes a superuser’s mode to Global mode.
In global mode, a superuser can define or modify global vertex and edge types, as well as specifying which graphs use those global types.
For example, the user should run USE GLOBAL
before creating or running a GLOBAL SCHEMA_CHANGE JOB
.
Global Privileges on Schema Change Jobs
Only users with the WRITE_SCHEMA
privilege on the global scope can add, alter, or drop global vertex types or global edge types, which are those that are created using CREATE VERTEX
or CREATE EDGE
.
This rule applies even if the vertex or edge type is used in only one graph.
To make these changes, the user uses a GLOBAL SCHEMA_CHANGE JOB
.
Only users with the WRITE_SCHEMA
privilege on the corresponding graph can add, alter, or drop local vertex types or local edge types which are created in the context of that graph.
Local vertex and edge types are created using an ADD
statement inside a SCHEMA_CHANGE JOB
on one particular graph.
To alter or drop any of these local types, the admin user uses a regular SCHEMA_CHANGE JOB
.
To see which vertices or edges are global, run the ls
command:
>USE GLOBAL
>ls
By restricting the ls
command to only global types, any local types will not appear in the results.
Use the USE
command with a specific graph to view all vertices and edges on that graph, including local types, then compare the results to find which types are local.
Vertex and edge types can share the same name as long as they are defined and used in different scopes. That is, different graphs can have local vertex and edge types with the same name. In addition, graphs can also have local types that share the same name with global types, as long as the global types with the same name are not used in the graph definition. |
The two types of schema change jobs are described below.
CREATE SCHEMA_CHANGE JOB
The CREATE SCHEMA_CHANGE JOB
block defines a sequence of ADD
, ALTER
, and DROP
statements for changing a particular graph.
It does not perform the schema change.
CREATE SCHEMA_CHANGE JOB job_name FOR GRAPH Graph_Name {
[sequence of DROP, ALTER, and ADD statements, each line ending with a semicolon]
}
One use of CREATE SCHEMA_CHANGE JOB
is to define an additional vertex type and edge type to be the structure for a secondary index.
For example, if you wanted to index the postal_code
attribute of the User
vertex, you could create a Postal_Code_IDX (PRIMARY_ID id string, code string)
vertex type and Has_Postal_Code (FROM User, TO Postal_Code_IDX)
edge type.
Then create an index structure having one edge from each User
to a Postal_Code_IDX
vertex.
If a |
ADD VERTEX | EDGE
The ADD
statement defines a new type of vertex or edge and automatically adds it to a graph schema.
The syntax for the ADD VERTEX | EDGE
statement is analogous to that of the CREATE VERTEX | EDGE
statements.
It may only be used within a SCHEMA_CHANGE JOB
.
ADD VERTEX Vertex_Type_Name ( PRIMARY_ID id_name id_type [, attribute_name type [DEFAULT default_value] ]* ) [WITH [STATS="none"|"outdegree_by_edgetype"][primary_id_as_attribute="true"]]
ADD UNDIRECTED EDGE Edge_Type_Name ( FROM Vertex_Type_Name "," TO Vertex_Type_Name [ "|" FROM Vertex_Type_Name "," TO Vertex_Type_Name]* [ "," DISCRIMINATOR "(" attribute_name type ["," attribute_name type]* ")" ] [ "," attribute_name type [DEFAULT default_value]]* )
For example, the following statement in a schema change job adds a directed edge Study_At
with source vertex Person
and target vertex University
. with the attributes class_year
and class_month
as their discriminator:
ADD DIRECTED EDGE Study_At (From Person, To University,
DISCRIMINATOR(class_year INT, class_month INT));
ALTER VERTEX | EDGE
The ALTER
statement adds attributes to or removes attributes from an existing vertex type or edge type. It may only be used within a SCHEMA_CHANGE
JOB
. The basic format is as follows:
ALTER VERTEX|EDGE object_type_name ADD|DROP ATTRIBUTE (attribute_list);
ALTER … ADD
ALTER … ADD
can add attributes to vertex or edge types.
You cannot make changes to a vertex type’s primary key or an edge types discriminator.
Added attributes are appended to the end of the schema. The new attributes may include DEFAULT
fields.
To add attributes to a vertex type, the syntax is as follows:
ALTER VERTEX Vertex_Type_Name ADD
ATTRIBUTE (attribute_name type [DEFAULT default_value]
[',' attribute_name type [DEFAULT default_value]]* );
For example:
ALTER VERTEX Company ADD ATTRIBUTE (industry
STRING, market_cap DOUBLE)
To add to an edge’s endpoint vertex types or attributes, the syntax is as follows:
ALTER EDGE Edge_Type_Name ADD
[ATTRIBUTE (attribute_name type [DEFAULT default_value]
[',' attribute_name type [DEFAULT default_value]]* )];
ALTER EDGE .. ADD PAIR
ALTER EDGE ... ADD PAIR
adds one or more edge pairs, which refer to the FROM
and TO
vertex types of an edge type. To add an edge pair, put the vertex type names in parentheses after keywords FROM
and TO
.
ALTER EDGE Edge_Type ADD PAIR
"(" FROM Vertex_Type, TO Vertex_Type (| FROM Vertex_Type, TO Vertex_Type)* ")”
Example
In the example below, the first statement in the schema change job will add an edge pair (FROM Person, TO Company
) to the edge type Visit
.
The second example adds two edge pairs to the edge type Has_Pet
; the edge type can now connect both Person
and Dog
vertices, as well as Person
and Bird
vertices.
CREATE SCHEMA_CHANGE JOB job_2 FOR GRAPH Example_Graph {
ALTER EDGE Visit ADD PAIR (FROM Person, TO Company);
ALTER EDGE Has_Pet ADD PAIR (FROM Person, TO Dog | FROM Person, TO Bird);
}
ALTER … DROP
The syntax for ALTER … DROP is analogous to that of ALTER … ADD.
ALTER VERTEX|EDGE Object_Type_Name DROP ATTRIBUTE (
attribute_name [',' attribute_name]* );
ALTER VERTEX … WITH
(Deprecated)
Tag-based Vertex-Level Access Control is deprecated as of October 2023. This feature will be completely removed in v4.0. |
The
statement ALTER VERTEX WITH TAGGABLE
is used to mark a vertex type as taggable or untaggable.
Vertex types are untaggable by default.
When a vertex type is marked as taggable, the vertex type can be used to create a tag-based graph. Additionally, users with the tag-access privilege can tag vertices whose vertex type is marked as taggable.
ALTER VERTEX Vertex_Type_Name WITH TAGGABLE = ("true" | "false")
DROP VERTEX | EDGE
The DROP statement removes the specified vertex type or edge type from the database dictionary. The DROP statement should only be used when graph operations are not in progress.
DROP VERTEX Vertex_Type_Name [',' Vertex_Type_Name]*
DROP EDGE Edge_Type_Name [',' Edge_Type_Name]*
DROP TUPLE
For tuples that are defined within a graph schema, you can drop them by using the following command.
DROP TUPLE Tuple_Name [',' Tuple_Name]*
ADD TAG
Tag-based Vertex-Access Access Control is deprecated as of October 2023. TigerGraph will be introducing a more flexible scheme in an upcoming release. |
ADD TAG
defines a tag for the graph. Tags can be used to create tag-based graphs, allowing for finer grain access control.
ADD TAG <tag_name> [DESCRIPTION <tag_description>]
DROP TAG
Tag-based Vertex-Access Access Control is deprecated as of October 2023. TigerGraph will be introducing a more flexible scheme in an upcoming release. |
DROP TAG
drops a tag or multiple tags from the schema, and deletes the tag from each vertex to which it is attached. DROP TAG
cannot be run if the tag to be dropped is used in the definition of a tag-based graph; the graph must be dropped first.
DROP TAG <tag_name> ["," <tag_name>]*
RUN SCHEMA_CHANGE JOB
RUN SCHEMA_CHANGE JOB job_name
performs the schema change job. After the schema has been changed, the GSQL system checks all existing GSQL queries. If an existing GSQL query uses a dropped vertex, edge, or attribute, the query becomes invalid, and GSQL will show the message "Query Query_Name becomes invalid after schema update, please update it.".
Below is an example. The schema change job add_reviews adds a Review vertex type and two edge types to connect reviews to users and books, respectively.
USE GRAPH Book_rating
CREATE SCHEMA_CHANGE JOB add_reviews FOR GRAPH Book_Rating {
ADD VERTEX Review (PRIMARY_ID id UINT, review_date DATETIME, url STRING);
ADD UNDIRECTED EDGE Wrote_Review (FROM User, TO Review);
ADD UNDIRECTED EDGE Review_Of_Book (FROM Review, TO Book);
}
RUN SCHEMA_CHANGE JOB add_reviews
-N Option (Local and Global)
Additionally, an option -N
is currently supported for both local and global schema change jobs.
See -N
Option for more details.
DROP JOB SCHEMA_CHANGE
To drop (remove) a schema change job, run DROP JOB schema_change_job
name from the GSQL shell. The specific schema change job will be removed from GSQL. Refer to the Creating a Loading Job page for more information about dropping jobs.
GSQL > USE GRAPH Book_rating
GSQL > DROP JOB local_schema_change123
The job local_schema_change123 is dropped!
CREATE GLOBAL SCHEMA_CHANGE JOB
The CREATE GLOBAL SCHEMA_CHANGE JOB
block defines a sequence of ADD
, ALTER
, and DROP
statements that modify either the attributes or the graph membership of global vertex or edge types. Unlike the non-global schema change job, the header does not include a graph name. However, the ADD
/ALTER
/DROP
statements in the body do mention graphs.
CREATE GLOBAL SCHEMA_CHANGE JOB job_name {
[sequence of global DROP, ALTER, and ADD statements, each line ending with a semicolon]
}
Although both global and local schema change jobs have ADD
and DROP
statements, they have different meanings. The table below outlines the differences.
Local | Global | |
---|---|---|
|
Defines a new local vertex/edge type; adds it to the graph’s domain |
Adds one or more existing global vertex/edge types to a graph’s domain. |
|
Deletes a local vertex/edge type and its vertex/edge instances |
Removes one or more existing global vertex/edge types from a graph’s domain. |
|
Adds or drops attributes from a local vertex/edge type. |
Adds or drops attributes from a global vertex/edge type, which may affect several graphs. |
Remember to include a semicolon at the end of each |
ADD VERTEX | EDGE
(global)
The ADD statement adds existing global vertex or edge types to one of the graphs.
ADD VERTEX Vertex_Type_Name [',' Vertex_Type_Name...] TO GRAPH Graph_Name;
ADD EDGE Edge_Type_Name [',' Edge_Type_Name...] TO GRAPH Graph_Name;
ALTER VERTEX | EDGE
The ALTER
statement is used to add attributes to or remove attributes from an existing vertex type or edge type.
It can also be used to add or remove source (FROM
) vertex types or destination (TO
) vertex types of an edge type. It may only be used within a SCHEMA_CHANGE JOB
. The basic format is as follows:
ALTER VERTEX|EDGE Object_Type_Name ADD|DROP ATTRIBUTE (attribute_list);
ALTER … ADD
Added attributes are appended to the end of the schema. The new attributes may include default fields. To add attributes to a vertex type, the syntax is as follows:
ALTER VERTEX Vertex_Type_Name ADD
ATTRIBUTE (attribute_name type [DEFAULT default_value]
[',' attribute_name type [DEFAULT default_value]]* );
For example:
ALTER VERTEX Company ADD ATTRIBUTE (industry
STRING, market_cap DOUBLE)
To add to an edge’s endpoint vertex types or attributes, the syntax is as follows:
ALTER EDGE Edge_Type_Name ADD
[FROM (Vertex_Type_Name [','Vertex_Type_Name])]
[TO (Vertex_Type_Name [','Vertex_Type_Name])]
[ATTRIBUTE (attribute_name type [DEFAULT default_value]
[',' attribute_name type [DEFAULT default_value]]* )];
For example:
ALTER EDGE Like ADD TO (Animal) ATTRIBUTE (suggested_by STRING)
ALTER EDGE .. ADD PAIR
ALTER EDGE ... ADD PAIR
adds one or more edge pairs, which refer to the FROM
and TO
vertex types of an edge type. To add an edge pair, put the vertex type names in parentheses after keywords FROM
and TO
.
ALTER EDGE Edge_Type ADD PAIR
"(" FROM Vertex_Type, TO Vertex_Type (| FROM Vertex_Type, TO Vertex_Type)* ")”
Example
In the following example below, the first statement in the schema change job will add an edge pair (FROM person, TO company
) to the edge type visit
.
The second example adds two edge pairs to the edge type has_pet
; the edge type can now connect both person
and dog
vertices, as well as person
and bird
vertices.
CREATE GLOBAL SCHEMA_CHANGE JOB job_2 FOR GRAPH Example_Graph {
ALTER EDGE Visit ADD PAIR (FROM Person, TO Company);
ALTER EDGE Has_Pet ADD PAIR (FROM Person, TO Dog | FROM Person, TO Bird);
}
ALTER … DROP
The syntax for ALTER ... DROP
is analogous to that of ALTER ... ADD
.
ALTER VERTEX|EDGE Object_Type_Name DROP ATTRIBUTE (
attribute_name [',' attribute_name]* );
ALTER VERTEX ... WITH
(Beta)
The statement ALTER VERTEX WITH TAGGABLE
is used to mark a vertex type as taggable or untaggable. Vertex types are untaggable by default. When a vertex type is marked as taggable, the vertex type can be used to create a tag-based graph. Additionally, users with the tag-access privilege can tag vertices whose vertex type is marked as taggable.
ALTER VERTEX Vertex_Type_Name WITH TAGGABLE = ("true" | "false")
DROP VERTEX | EDGE
(global)
The DROP statement removes specified global vertex or edge types from one of the graphs. The command does not delete any data. |
DROP VERTEX Vertex_Type_Name [',' Vertex_Type_Name...] FROM GRAPH Graph_Name;
DROP EDGE Edge_Type_Name [',' Edge_Type_Name...] FROM GRAPH Graph_Name;
RUN GLOBAL SCHEMA_CHANGE JOB
RUN GLOBAL SCHEMA_CHANGE JOB job_name
performs a global schema change job. After the schema has been changed, the GSQL system checks all existing GSQL queries. If an existing GSQL query uses a dropped vertex, edge, or attribute, the query becomes invalid, and GSQL will show the message "Query query_name becomes invalid after schema update, please update it.".
Below is an example. The schema change alter_friendship_make_library drops the on_date attribute from the friend_of edge and adds Book type to the library graph.
USE GLOBAL
CREATE GRAPH Library()
CREATE GLOBAL SCHEMA_CHANGE JOB alter_friendship_make_library {
ALTER EDGE Friend_Of DROP ATTRIBUTE (on_date);
ADD VERTEX Book TO GRAPH library;
}
RUN GLOBAL SCHEMA_CHANGE JOB alter_friendship_make_library
-N
Option
Additionally, an option -N
is currently supported for both local and global schema change jobs.
Option |
Local jobs with the -N
option will skip recompile and reinstall queries created for the local graph.
RUN SCHEMA_CHANGE JOB test_job -N
Global jobs with the -N
option will skip recompile and re-install queries.
RUN GLOBAL SCHEMA_CHANGE JOB test_job -N
Impact Warning
A notification will be displayed to help users understand the impact of running a global or local schema change on a query.
WARNING: When modifying the graph schema, reinstalling all affected queries is required, and the duration of this process may vary based on the number and complexity of the queries. To skip query reinstallation, you can run with the '-N' option, but manual reinstallation of queries will be necessary afterwards.
Users can skip this message by using the -N
option with the schema change job and the queries will not be reinstalled.
Examples
-N
.GLE_6714 (main) $ gsql 2_run_schemage_cahnge_job.gsql
Using graph 'person_movie'
WARNING: When modifying the graph schema, reinstalling all affected queries is required, and the duration of this process may vary based on the number and complexity of the queries. To skip query reinstallation, you can run with the '-N' option, but manual reinstallation of queries will be necessary afterwards.
Kick off schema change job schema_change_job
Doing schema change on graph 'person_movie' (current version: 1)
Trying to add local edge 'has_director' and its reverse edge 'reverse_has_director' to the graph 'person_movie'.
Graph person_movie updated to new version 2
Validating existing queries for graph person_movie ...
Start installing queries, about 1 minute ...
Select 'm1' as compile server, now connecting ...
Node 'm1' is prepared as compile server.
[========================================================================================================] 100% (0/0)
Query installation finished.
The job schema_change_job completes in 6.621 seconds!
Local schema change succeeded.
-N
.GLE_6714 (main) $ cat 3_run_schemage_cahnge_job_without_warning.gsql
RUN GLOBAL SCHEMA_CHANGE JOB global_schema_change_job -N
GLE_6714 (main) $ gsql 3_run_schemage_cahnge_job_without_warning.gsql
Kick off global schema change job global_schema_change_job
Doing schema change on graph 'person_movie' (current version: 2)
Trying to add global edge 'has_friend' and its reverse edge 'reverse_has_friend' to the graph 'person_movie'.
Doing schema change on the global schema (current version: 67)
Graph person_movie updated to new version 3
Global schema change succeeded.
DROP JOB GLOBAL SCHEMA_CHANGE
Global schema change jobs can be dropped by using the DROP JOB command. Refer to the Creating a Loading Job page for more information about dropping jobs.
USE GLOBAL
DROP JOB alter_friendship_make_library