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/or DROP 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 which relate to an altered part of the schema. Specifically:

  • A loading job becomes invalid if it refers to a vertex or and an edge which has been dropped (deleted) or altered .

  • A query becomes invalid if it refers to a vertex, and edge, or an attribute which has been dropped .

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.

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 syntax
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 SCHEMA_CHANGE JOB defines a new edge type which connects to a new vertex type, the ADD VERTEX statement should precede the related ADD EDGE statement.However, the ADD EDGE and ADD VERTEX statements can be in the same SCHEMA_CHANGE JOB.

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

  • ADD EDGE

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:

Syntax
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:

Syntax
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:

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

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

Syntax
ALTER VERTEX|EDGE Object_Type_Name DROP ATTRIBUTE (
      attribute_name [',' attribute_name]* );

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.

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

Syntax
DROP TUPLE Tuple_Name [',' Tuple_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.

SCHEMA_CHANGE JOB example
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.

Syntax
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

ADD

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.

DROP

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.

ALTER

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 DROP, ALTER, or ADD statement within the JOB block.

ADD VERTEX | EDGE (global)

The ADD statement adds existing global vertex or edge types to one of the graphs.

Syntax
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:

Syntax
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:

Syntax
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:

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

Syntax
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 …​ DROP
ALTER VERTEX|EDGE Object_Type_Name DROP ATTRIBUTE (
      attribute_name [',' attribute_name]* );

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

GLOBAL SCHEMA_CHANGE JOB example
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 -N, for both global and local scopes, will mark the queries as deprecated and the user will need to manually re-install the deprecated queries.

Local jobs with the -N option will skip recompile and reinstall queries created for the local graph.

Example
RUN SCHEMA_CHANGE JOB test_job -N

Global jobs with the -N option will skip recompile and re-install queries.

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

The warning message will be as follows:
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

This first example runs a schema change job without the option -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.
This example runs a global schema change job with the option -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.

DROP GLOBAL SCHEMA_CHANGE JOB example
USE GLOBAL
DROP JOB alter_friendship_make_library

DROP ALL

The DROP ALL command clears all graph data, all graph schemas, all loading jobs, and all queries. It should only be used when the intent is to erase an entire database design and to start over.

This command is only available to superusers and only when they are in global mode.