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 (i.e. RUN 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.

Jobs and queries for unaltered parts of the schema will still be available and do not need to be reinstalled. However, even though these jobs are valid (e.g., they can be run), the user may wish to examine whether they still perform the preferred operations (e.g., do you want to run them?)

Global vs. Local Schema Changes

Only a superuser 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 superuser uses a GLOBAL SCHEMA_CHANGE JOB.

An admin or designer user 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. To alter or drop any of these local types, the admin user uses a regular SCHEMA_CHANGE JOB.

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.

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 postalCode attribute of the User vertex, you could create a postalCode_idx (PRIMARY_ID id string, code string) vertex type and hasPostalCode (FROM User, TO postalCode_idx) edge type. Then create an index structure having one edge from each User to a postalCode_idx vertex.

ADD VERTEX | EDGE (local)

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 | GRAPH statements. It may only be used within a SCHEMA_CHANGE JOB.

ALTER VERTEX | EDGE

The ALTER statement is used to add attributes to or remove 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 ... ADD

Added attributes are appended to the end of the schema. The new attributes may include DEFAULT fields:

ALTER ... DROP

DROP VERTEX | EDGE (local)

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 TUPLE

For tuples that are defined within a graph schema, you can drop them by using the following command.

RUN SCHEMA_CHANGE JOB

RUN JOB job_name performs the schema change job. After the schema has been changed, the GSQL system checks all existing GSQL queries (described in "GSQL Language Reference, Part 2: Querying"). 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 GLOBAL

CREATE GLOBAL SCHEMA_CHANGE JOB

Those both global and local schema change jobs have ADD and DROP statements, they have different meanings. The table below outlines the differences.

ADD VERTEX | EDGE (global)

ALTER VERTEX | EDGE

ALTER ... ADD

Added attributes are appended to the end of the schema. The new attributes may include DEFAULT fields:

ALTER ... DROP

DROP VERTEX | EDGE (global)

RUN GLOBAL SCHEMA_CHANGE JOB

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.