Reference

MultiGraph An Overview


Version 1.2 to 2.0



Updated



Beginning with Version 1.2, one TigerGraph instance can manage multiple graphs, each with its own set of user privileges. This first-of-its-kind capability, dubbed MultiGraph, is available as an optional service in the Enterprise Edition of the TigerGraph platform.  MultiGraph enables several powerful use cases:


  • Multiple Tenancy

    : Use one TigerGraph instance to support several completely separate data sets, each with its own set of users. Each user community is unaware of the other user communities or other data sets.

  • Fine-grained privileges on the same set of data

    : Role-based access control, available on single graphs, grants permission for the privilege to run queries (include data modification queries). In a single graph scheme, there is not a way to say “Query X can be run by some users but not by others.” Using multiple graphs defined over the same set of data, each graph can have its own set of queries and own set of users, in effect customizing who can run which queries.

  • Overlapping graphs

    : Graphs can partially overlap, to enable a combination of shared and private data.

  • Hierarchical subgraphs

    : A Graph X can be defined to cover the domains of Graphs Y and Z, that is, Graph X = (Graph Y) U (Graph Z). This provides
    an interesting
    way to describe a data partitioning or parent-child structure. (This is not the same as defining sub-classes of data types; data types are still independent.)

If you implement only one graph now, you can upgrade to MultiGraph and add additional graphs at any time, without having to redo your existing design.


While the system has the inherent capability of managing multiple graphs, the ability of users to create more than one graph may depend on your license key.

To support the new MultiGraph capabilities, a few changes to the previous specifications are necessary. These changes affect all users, even if only a single graph is deployed. We advise all users to read the

Concepts

and

Modified Specifications

below.

There are also several

New Commands

.



Concepts

Graphs and Graph Domains

A

graph

is a defined as a set of vertex types and edge types. More precisely, it is all the vertices and edges of that collection of types. The

domain

of a graph is its set of vertex types and edge types.

CREATE GRAPH <gname> (<list of vertex types and edge types>)




NEW



  • It is possible to define multiple graphs.


    The domains of two graphs may be completely separate, may overlap, or may coincide exactly.
  • A TigerGraph instance with a basic license key can have one graph. A TigerGraph instance with a MultiGraph license key can create multiple graphs.
  • A vertex type or edge type created by a superuser is a

    global

    type.
  • A superuser can include a global vertex or edge type in one or more graphs. Global types can be

    shared

    among multiple graphs.
  • The admin users or designer users for a particular graph can add

    local

    vertex types and edge types to their own graph.

Graph-Specific Roles and Privileges

The TigerGraph system includes several predefined

roles.

Each role is a fixed and logical set of privileges to perform operations. In order to access a graph, a user must be granted a role on that graph. Without a role, a user has no meaningful access.


CHANGES



  • User roles are granted or revoked on a per-graph basis

    .

    Each GRANT or REVOKE statement specifies not only a role but also a graph.
  • A user may be granted

    different roles on different graphs

    .
  • A new top-level role is added:

    superuser

    . The superuser automatically has admin privilege on every graph, and has additional global privileges.

Setting a Working Graph

Previously, there was only one graph, and so all users were automatically able to use that graph.


NEW



  • A user must set their working graph in order to access that graph.

  • Users who have privileges on more than one graph (including superusers) may only work with one graph at a time. The GLOBAL SCHEMA_CHANGE JOB stretches this rule.

Note that the CREATE commands for queries, loading jobs, and schema_change jobs have always required that the graph name be specified, even when there was support for only one graph. Now, it is clear that these definitions are graph-specific.



New and Modified Specifications



Modified Specifications

If you are a user of an earlier TigerGraph system (v1.1 or earlier), please note the following specifications have changed.

  1. Set the working graph in GSQL: You must always set the working graph, either using the -g flag with the gsql command, or by using the USE GRAPH command.
  2. RESTPP Endpoint changes: Endpoints which pertain to the graph data have been modified to include the name of the graph in the request URL.



    See

    RESTPP API User Guide

    .
  3. User Authentication secrets and tokens: The way in which secrets and tokens are created and used has changed, in order to follow OAuth standards more closely.



    See

    Managing User Privileges and Authentication v2.1

    .
  4. Changes to privileges of certain roles: If you had been using only the single default user with

    admin

    privilege, you will not notice any difference. That user has been promoted to

    superuser

    status. If you are making use of users with different roles, note the following changes in privileges:


    • A new top-level role,

      superuser

      , is defined. The superuser has admin privilege on all graphs, and is the only role who can
      create
      and modify shared vertex types, shared edge types, and graphs.
    • The



      architect



      role is renamed



      designer

      .
    • The



      public



      role is renamed



      observer

      .
    • The following commands are now shifted from

      admin

      and

      designer

      roles to the

      superuser

      role:

      • CREATE / DROP VERTEX|EDGE|GRAPH
      • CLEAR GRAPH STORE
      • DROP ALL
    • Newly created users no longer automatically have the

      observer

      role. They have no role until explicitly granted one.
  5. In the CREATE VERTEX statement, the WITH STATS option “outdegree” is no longer available. “outdegree_by_edgetype” is still supported and is the default.

There are many other details about using the MultiGraph feature, especially if your application has mulitple users with different roles. In the documentation, the Multiple Graph logo is placed next to relevant topics:





New Commands

The following commands are new. This section provides only a summary list. For full details and examples, see the main documentation for the relevant topics.

USE GRAPH <graph_name>

  • For all users
  • Sets the given graph as the user’s working graph.

USE GLOBAL

  • For superusers
  • Must be set to have privilege to create and assign global vertex and edge types.

CREATE GLOBAL SCHEMA_CHANGE JOB

  • For superusers